@vsleem-realsee-viewer/projection-plugin 2.1.2 → 2.1.4

package/README.internal.md

@@ -6,6 +6,18 @@
 
 依赖@vsleem-realsee-viewer/shared（共享类）
 
+## 目录
+
+- [1. Projection映射组件](#1-projection映射组件)
+- [2. 子组件说明](#2-子组件说明)
+- [3. 枚举类型](#3-枚举类型)
+- [4. 类型定义](#4-类型定义)
+- [5. 配置常量](#5-配置常量)
+- [6. 工具函数](#6-工具函数)
+- [7. API接口](#7-api接口)
+- [8. 导出说明](#8-导出说明)
+- [9. 示例](#9-示例)
+
 ### 1.1.1 坐标系枚举
 
 - **空间坐标系** (参考`CoordinateLevel`枚举):
@@ -116,18 +128,325 @@ enum CoordinateModelType {
 }
 ```
 
-# 2. 示例
+# 9. 示例
 
 通过以下方式来注册组件
 
-## 2.1 安装
+## 9.1 安装
 
 `npm install @vsleem-realsee-viewer/projection-plugin @vsleem-realsee-viewer/shared`
 
 `pnpm add @vsleem-realsee-viewer/projection-plugin @vsleem-realsee-viewer/shared`
 
-## 2.2 例子
+## 9.2 例子
 
 `vsleem-realsee-demo仓库下的views/projection`
 
 仓库地址：https://gitee.com/yangleistudio/vsleem-realsee-demo
+
+---
+
+# 2. 子组件说明
+
+## 2.1 Projection 主组件
+
+映射组件的主入口，提供配置注入和事件转发功能。
+
+### Props
+
+继承所有 [ProjectionProps](#12-projectionprops-参数说明) 属性。
+
+### Events
+
+| 事件名称           | 参数类型                            | 说明                    |
+| ------------------ | ----------------------------------- | ----------------------- |
+| `bindingSubmit`    | `(formData: Coordinate[]) => void`  | 模型绑定完成后触发      |
+| `projectionSubmit` | `(result: ProjectionModel) => void` | 模型/空间映射完成后触发 |
+
+### Slots
+
+| 插槽名称         | 参数类型    | 说明            |
+| ---------------- | ----------- | --------------- |
+| `leftBimViewer`  | `SlotProps` | 左侧BIM视图插槽 |
+| `rightBimViewer` | `SlotProps` | 右侧BIM视图插槽 |
+
+## 2.2 ModelPicker 模型选择器
+
+用于选择模型坐标系的级联选择器组件。
+
+### Props
+
+| 属性                 | 类型           | 默认值 | 说明             |
+| -------------------- | -------------- | ------ | ---------------- |
+| `defaultValue`       | `number`       | -      | 默认选中项ID     |
+| `coordinateTree`     | `Coordinate`   | -      | 坐标系树         |
+| `activedCoordinate`  | `Coordinate`   | -      | 被激活的坐标系   |
+| `includeModelType`   | `number[]`     | -      | 包含的模型类型   |
+| `excludedCoordinate` | `Coordinate[]` | `[]`   | 排除的坐标系列表 |
+| `showShortName`      | `boolean`      | `true` | 是否显示缩写名   |
+
+### Events
+
+| 事件名称 | 参数类型                    | 说明           |
+| -------- | --------------------------- | -------------- |
+| `change` | `(value: number[]) => void` | 选择变化时触发 |
+
+## 2.3 SpacePicker 空间选择器
+
+用于选择空间坐标系的级联选择器组件。
+
+### Props
+
+| 属性                 | 类型           | 默认值 | 说明             |
+| -------------------- | -------------- | ------ | ---------------- |
+| `defaultValue`       | `number`       | -      | 默认选中项ID     |
+| `coordinateTree`     | `Coordinate`   | -      | 坐标系树         |
+| `excludedCoordinate` | `Coordinate[]` | `[]`   | 排除的坐标系列表 |
+| `showShortName`      | `boolean`      | `true` | 是否显示缩写名   |
+
+### Events
+
+| 事件名称 | 参数类型                    | 说明           |
+| -------- | --------------------------- | -------------- |
+| `change` | `(value: number[]) => void` | 选择变化时触发 |
+
+## 2.4 其他内部组件
+
+| 组件名称           | 说明                         |
+| ------------------ | ---------------------------- |
+| `ProjectionViewer` | 映射视图容器，包含双视图布局 |
+| `SpaceBindViewer`  | 空间绑定视图                 |
+| `SpaceMapViewer`   | 空间地图视图                 |
+| `BimControl`       | BIM模型控制组件              |
+| `CadControl`       | CAD图纸控制组件              |
+| `GeoControl`       | 地理控制组件                 |
+| `ScaleControl`     | 比例尺控制组件               |
+| `TitleControl`     | 标题控制组件                 |
+| `ConfigProvider`   | 配置提供者组件               |
+| `FlatModelPicker`  | 扁平模型选择器               |
+| `FlatSpacePicker`  | 扁平空间选择器               |
+| `GeoModal`         | 地理信息弹窗                 |
+| `HeightModal`      | 高度设置弹窗                 |
+
+---
+
+# 3. 枚举类型
+
+## 3.1 MappingType 映射类型
+
+| 值             | 说明                                                   |
+| -------------- | ------------------------------------------------------ |
+| `SpaceMapping` | 空间映射 (0)                                           |
+| `ModelMapping` | 模型映射 (1)                                           |
+| `ScaleMapping` | 比例尺映射 (2)                                         |
+| `FixedMapping` | 固定映射 (3) - 如空间首次绑定模型并且模型是BIM直接映射 |
+
+## 3.2 PointActionType 点位操作类型
+
+| 值       | 说明     |
+| -------- | -------- |
+| `Point1` | 第一个点 |
+| `Point2` | 第二个点 |
+
+---
+
+# 4. 类型定义
+
+## 4.1 AppSetting 应用设置
+
+```typescript
+type AppSetting = AppConfig & {
+  theme?: ThemeConfig; // 主题配置
+  flattenPicker?: boolean; // 选项扁平化
+  showTitleHead?: boolean; // 是否显示标题头
+};
+```
+
+## 4.2 ProjectionProps 投影组件参数
+
+```typescript
+type ProjectionProps = {
+  appSetting: AppSetting; // 应用程序配置
+  mapSetting?: MapSetting; // 地图配置
+  projectId: number; // 项目唯一标识符
+  bindModelId?: number; // 绑定的模型标识符
+  bindCoordinateId?: number; // 绑定的目标坐标系标识符
+  srcCoordinateId?: number; // 映射源坐标系标识符
+  dstCoordinateId?: number; // 映射目标坐标系标识符
+  srcModelType?: number[]; // 映射指定源坐标系的模型类型
+  dstModelType?: number[]; // 映射指定目标坐标系的模型类型
+};
+```
+
+## 4.3 MapSetting 地图配置
+
+```typescript
+type MapSetting = {
+  options?: MapOptions; // 地图选项
+  tileLayers: TileLayer[]; // 瓦片图层列表
+  keywordSearchFn?: (keyword: string) => Promise<GeoPoint | undefined>; // 地理编码查询
+};
+```
+
+## 4.4 TileLayer 瓦片图层
+
+```typescript
+type TileLayer = {
+  url: string; // 瓦片url
+  options?: TileLayerOptions; // 瓦片选项
+};
+```
+
+## 4.5 ControlProps 控制组件传参
+
+```typescript
+type ControlProps = {
+  mapSetting?: MapSetting; // 地图配置
+  currentProject?: ProjectModel; // 项目详情
+  currentModel?: Coordinate; // 当前模型
+  points?: Point[]; // bim模型坐标点
+  connected?: boolean; // 是否连接
+};
+```
+
+## 4.6 SlotProps 插槽状态
+
+```typescript
+interface SlotProps {
+  currentModel?: Coordinate; // 当前模型坐标系
+  points: Point[]; // 点坐标数组
+  setPoint1: (position: Vector3) => void; // 设置第一个点坐标
+  setPoint2: (position: Vector3) => void; // 设置第二个点坐标
+}
+```
+
+---
+
+# 5. 配置常量
+
+## 5.1 MAP_OPTIONS 地图选项
+
+```typescript
+{
+  center: [31.3016935, 120.5810725],  // 地图初始化时经纬度
+  zoom: 17,                           // 地图初始化时的缩放等级
+  attributionControl: true,           // 是否将版权控件添加到地图中
+  zoomControl: false,                 // 是否将缩放控件添加到地图中
+}
+```
+
+## 5.2 TILE_LAYERS 瓦片图层配置
+
+默认天地图瓦片图层配置，包含：
+
+- 矢量底图图层
+- 矢量标注图层
+
+## 5.3 GEO_CODER_URL 地理编码地址
+
+天地图地理编码查询服务地址。
+
+## 5.4 MAP_SETTING 地图设置
+
+组合了地图选项、瓦片图层和地理编码查询函数的完整配置。
+
+---
+
+# 6. 工具函数
+
+## 6.1 useResizeObserver 尺寸观察
+
+用于监听元素尺寸变化的 Vue 组合式函数。
+
+| 参数       | 类型                                         | 说明     |
+| ---------- | -------------------------------------------- | -------- |
+| `target`   | `MaybeRef<HTMLElement \| null \| undefined>` | 目标元素 |
+| `callback` | `(entries: ResizeObserverEntry[]) => void`   | 回调函数 |
+| `options`  | `UseResizeObserverOptions`                   | 选项     |
+
+**返回值**: `{ width: Ref<number>, height: Ref<number>, stop: () => void }`
+
+## 6.2 withInstall 安装包装器
+
+用于为 Vue 组件添加 install 方法的包装函数，支持组件全局注册。
+
+| 参数      | 类型 | 说明     |
+| --------- | ---- | -------- |
+| `options` | `T`  | 组件选项 |
+
+**返回值**: `WithInstall<T>`
+
+## 6.3 camelize 驼峰转换
+
+将短横线命名转换为驼峰命名。
+
+| 参数  | 类型     | 说明             |
+| ----- | -------- | ---------------- |
+| `str` | `string` | 短横线命名字符串 |
+
+**返回值**: `string` - 驼峰命名字符串
+
+---
+
+# 7. API接口
+
+## 7.1 getModelDetail 获取模型详情
+
+获取模型详细信息。
+
+| 参数      | 类型                  | 说明     |
+| --------- | --------------------- | -------- |
+| `params`  | `Record<string, any>` | 请求参数 |
+| `options` | `RequestOptions`      | 请求选项 |
+
+**返回值**: `Promise<ViewModel>`
+
+## 7.2 getGeoPoint 地理编码查询
+
+根据关键词查询地理坐标。
+
+| 参数      | 类型     | 说明       |
+| --------- | -------- | ---------- |
+| `keyWord` | `string` | 查询关键词 |
+
+**返回值**: `Promise<GeoPoint \| undefined>`
+
+---
+
+# 8. 导出说明
+
+```js
+import 'leaflet/dist/leaflet.css';
+import { ModelPicker, Projection as ProjectionPlugin, SpacePicker } from '@vsleem-realsee-viewer/projection-plugin';
+
+/** 枚举导出 */
+export { MappingType } from '@vsleem-realsee-viewer/projection-plugin';
+
+/** 组件导出 */
+export {
+  ModelPicker,      // 模型选择器
+  ProjectionPlugin, // 映射组件
+  SpacePicker,      // 空间选择器
+} from '@vsleem-realsee-viewer/projection-plugin';
+
+/** 类型导出 */
+export type {
+  AppSetting,       // 应用程序配置
+  MapOptions,       // 地图选项
+  MapSetting,       // 地图配置参数
+  ProjectionProps,  // 投影组件参数
+  SlotProps,        // 插槽状态
+  ThemeConfig,      // 主题配置
+  TileLayer,        // 瓦片图层
+  TileLayerOptions, // 瓦片图层选项
+} from '@vsleem-realsee-viewer/projection-plugin';
+
+/** 配置常量导出 */
+export {
+  GEO_CODER_URL,    // 地理编码地址
+  MAP_OPTIONS,      // 地图选项
+  TILE_LAYERS,      // 瓦片图层配置
+} from '@vsleem-realsee-viewer/projection-plugin';
+```
+
+---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vsleem-realsee-viewer/projection-plugin",
-  "version": "2.1.2",
+  "version": "2.1.4",
   "description": "Projection plugin for VSLeem RealSee Viewer",
   "main": "./dist/index.umd.js",
   "module": "./dist/index.mjs",
@@ -13,11 +13,11 @@
     "dist"
   ],
   "dependencies": {
-    "@vsleem-realsee-viewer/shared": "2.1.2"
+    "@vsleem-realsee-viewer/shared": "2.1.4"
   },
   "peerDependencies": {
     "vue": "^3.0.0",
-    "@vsleem-realsee-viewer/shared": "2.1.2"
+    "@vsleem-realsee-viewer/shared": "2.1.4"
   },
   "peerDependenciesMeta": {
     "vue": {