@zhangdali1996/lr-map-viewer 0.0.4 → 0.0.6

package/README.md

@@ -4,9 +4,13 @@
 
 主要能力：
 
+- 支持 Vue 3 项目中以组件方式挂载二维图纸容器。
 - 支持 Vue 3 项目中以组件方式挂载三维地图容器。
+- 支持 `2d / 3d` 模式切换与统一壳层承载。
 - 支持龙软三维 SDK 的运行时加载。
+- 支持通过运行时配置传入二维图纸参数。
 - 支持通过运行时配置传入云 GIS 参数。
+- 支持通过运行时配置显式传入三维场景 `basePoint`。
 - 支持按需显示区域显隐面板和调试面板。
 - 支持通过组件实例调用 `moveView(x, y, z)` 移动三维视角。
 - 支持通过组件实例注册 `registerModelInfoQuery(callback)` 查询点击模型信息。
@@ -46,6 +50,8 @@ public/
 
 ## 最小接入示例
 
+### 三维示例
+
 ```vue
 <script setup>
 import { LrMapViewer } from '@zhangdali1996/lr-map-viewer'
@@ -56,16 +62,18 @@ const lr3dConfig = {
   cloud: {
     // 云 GIS 服务地址
     server: 'https://your-cloud-gis-server/',
-    // 地图服务地址
-    mapServerUrl: 'https://your-map-server/',
     // 云 GIS 用户名
     username: 'your_username',
     // 云 GIS 密码
     password: 'your_password',
     // 数据源 guid
     dsGuid: 'your_ds_guid',
-    // 数据源名称
-    dsname: 'your_ds_name',
+    // 三维场景基点
+    basePoint: {
+      x: 37517614.46684,
+      y: 4410289.679932,
+      z: 972.148557,
+    },
     // 需要加载的巷道图层名
     layers: ['your_lane_layer_name'],
     laneSize: {
@@ -74,15 +82,6 @@ const lr3dConfig = {
       // 巷道渲染高度
       height: 10,
     },
-    // 需要加载的煤层图层名数组
-    coalLayers: ['your_coal_layer_name'],
-    // 需要加载的断层图层名数组
-    geofaultLayers: [],
-    // 以下开关和要素编码均提供默认值，按需覆盖即可
-    workfaceFeatureTypes: ['0202030030'],
-    regionFeatureTypes: ['0202030030', '0106020009', '0202030004', '0202030006'],
-    enableRegionAssist: false,
-    enableLane: true,
   },
 }
 </script>
@@ -94,6 +93,83 @@ const lr3dConfig = {
 </template>
 ```
 
+### 二维图纸示例
+
+```vue
+<script setup>
+import { LrMapViewer } from '@zhangdali1996/lr-map-viewer'
+
+const map2dConfig = {
+  behavior: {
+    autoInitLayer: true,
+    autoShowLayer: true,
+    captureLayerTree: true,
+  },
+  options: {
+    ygis_dsGuid: 'your_ds_guid',
+    ygis_url: 'https://your-cloud-gis-server/',
+    Url: 'https://your-map-server/',
+    layerName: 'your_layer_name',
+    layerCode: '',
+    token: 'your_token',
+  },
+}
+</script>
+
+<template>
+  <div style="height: 100vh;">
+    <LrMapViewer mode="2d" :modes="['2d']" :map2d-config="map2dConfig" />
+  </div>
+</template>
+```
+
+### 二维三维切换示例
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { LrMapViewer } from '@zhangdali1996/lr-map-viewer'
+
+const activeMode = ref('2d')
+const map2dConfig = {
+  options: {
+    ygis_dsGuid: 'your_ds_guid',
+    ygis_url: 'https://your-cloud-gis-server/',
+    Url: 'https://your-map-server/',
+    layerName: 'your_layer_name',
+    token: 'your_token',
+  },
+}
+
+const lr3dConfig = {
+  autoLoad: true,
+  cloud: {
+    server: 'https://your-cloud-gis-server/',
+    username: 'your_username',
+    password: 'your_password',
+    dsGuid: 'your_ds_guid',
+    basePoint: {
+      x: 37517614.46684,
+      y: 4410289.679932,
+      z: 972.148557,
+    },
+    layers: ['your_lane_layer_name'],
+  },
+}
+</script>
+
+<template>
+  <div style="height: 100vh;">
+    <LrMapViewer
+      :mode="activeMode"
+      :modes="['2d', '3d']"
+      :map2d-config="map2dConfig"
+      :lr3d-config="lr3dConfig"
+    />
+  </div>
+</template>
+```
+
 如果你需要默认显示右上角区域显隐面板和调试面板：
 
 ```vue
@@ -132,6 +208,12 @@ createApp(App).use(LrMapViewerPlugin).mount('#app')
 
 组件 Props：
 
+- `mode`
+  当前激活模式，支持 `2d` 或 `3d`。
+- `modes`
+  当前组件允许启用的模式列表，默认 `['3d']`。
+- `map2dConfig`
+  二维图纸运行时配置。
 - `lr3dConfig`
   龙软三维运行时配置。
 - `showRegionPanel`
@@ -144,6 +226,7 @@ createApp(App).use(LrMapViewerPlugin).mount('#app')
 - `switchMode(mode)`
 - `getCurrentMode()`
 - `getCurrentEngine()`
+- `get2dInstance()`
 - `get3dInstance()`
 - `resize()`
 - `refreshScene()`
@@ -152,11 +235,70 @@ createApp(App).use(LrMapViewerPlugin).mount('#app')
 
 说明：
 
+- `switchMode(mode)` 支持在 `2d / 3d` 间切换当前显示引擎。
+- `get2dInstance()` 返回当前二维 adapter 实例，其中包含 `map`、`options`、`behavior`、`layerTree` 等信息。
 - `refreshScene()` 仅对三维场景有效。
 - `moveView(x, y, z)` 传入的是绝对三维坐标，组件内部会自动换算成相对 `basePoint` 坐标后调用聚焦接口。
 - `registerModelInfoQuery(callback)` 会在用户点击三维中的模型对象时触发回调。
 - 模型信息查询返回 4 个字段：`id`、`name`、`layerName`、`position`。
 
+## 二维图纸配置说明
+
+推荐写法：
+
+```js
+const map2dConfig = {
+  behavior: {
+    autoInitLayer: true,
+    autoShowLayer: true,
+    captureLayerTree: true,
+  },
+  options: {
+    ygis_dsGuid: 'your_ds_guid',
+    ygis_url: 'https://your-cloud-gis-server/',
+    Url: 'https://your-map-server/',
+    layerName: 'your_layer_name',
+    layerCode: '',
+    token: 'your_token',
+    extent: '',
+    rotate: false,
+    animate: false,
+    zoomAnimation: false,
+    markerZoomAnimation: false,
+    fadeAnimation: false,
+  },
+}
+```
+
+必填字段：
+
+- `map2dConfig.options.ygis_dsGuid`
+  二维图纸数据源 guid。
+- `map2dConfig.options.ygis_url`
+  云 GIS 服务地址。
+- `map2dConfig.options.Url`
+  二维地图服务地址。
+- `map2dConfig.options.token`
+  二维认证 token，和用户名密码二选一。
+
+认证兼容说明：
+
+- 如果没有 `token`，则需要同时传入 `map2dConfig.options.ygis_username` 和 `map2dConfig.options.ygis_password`。
+- 当 `map2dConfig.behavior.autoShowLayer` 为 `true` 时，`map2dConfig.options.layerName` 也属于必填项。
+
+常用可选字段：
+
+- `map2dConfig.options.layerCode`
+  图层编码，默认可传空字符串。
+- `map2dConfig.options.extent`
+  初始范围。
+- `map2dConfig.behavior.autoInitLayer`
+  是否自动初始化图层，默认 `true`。
+- `map2dConfig.behavior.autoShowLayer`
+  是否自动显示指定图层，默认 `true`。
+- `map2dConfig.behavior.captureLayerTree`
+  是否抓取图层树，默认 `true`。
+
 ## 接口示例
 
 推荐通过 `ref` 调用组件实例方法：
@@ -203,6 +345,38 @@ watch(
 </template>
 ```
 
+如果你需要切换二维与三维模式：
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { LrMapViewer } from '@zhangdali1996/lr-map-viewer'
+
+const viewerRef = ref(null)
+
+function switchTo2d() {
+  viewerRef.value?.switchMode?.('2d')
+}
+
+function switchTo3d() {
+  viewerRef.value?.switchMode?.('3d')
+}
+</script>
+
+<template>
+  <div style="height: 100vh;">
+    <button type="button" @click="switchTo2d">查看二维</button>
+    <button type="button" @click="switchTo3d">查看三维</button>
+    <LrMapViewer
+      ref="viewerRef"
+      :modes="['2d', '3d']"
+      :map2d-config="map2dConfig"
+      :lr3d-config="lr3dConfig"
+    />
+  </div>
+</template>
+```
+
 模型信息查询回调返回结构：
 
 ```js
@@ -233,18 +407,19 @@ const lr3dConfig = {
   autoLoad: true,
   cloud: {
     server: 'https://your-cloud-gis-server/',
-    mapServerUrl: 'https://your-map-server/',
     username: 'your_username',
     password: 'your_password',
     dsGuid: 'your_ds_guid',
-    dsname: 'your_ds_name',
+    basePoint: {
+      x: 37517614.46684,
+      y: 4410289.679932,
+      z: 972.148557,
+    },
     layers: ['your_lane_layer_name'],
     laneSize: {
       width: 10,
       height: 10,
     },
-    coalLayers: ['your_coal_layer_name'],
-    geofaultLayers: [],
   },
 }
 ```
@@ -255,16 +430,18 @@ const lr3dConfig = {
   是否在场景初始化成功后自动加载云 GIS 数据。
 - `cloud.server`
   云 GIS 服务地址。
-- `cloud.mapServerUrl`
-  地图服务地址。
 - `cloud.username`
   云 GIS 用户名。
 - `cloud.password`
   云 GIS 密码。
 - `cloud.dsGuid`
   数据源 guid。
-- `cloud.dsname`
-  数据源名称。
+- `cloud.basePoint.x`
+  三维场景基点 x 坐标。
+- `cloud.basePoint.y`
+  三维场景基点 y 坐标。
+- `cloud.basePoint.z`
+  三维场景基点 z 坐标。
 
 可选字段：
 
@@ -274,22 +451,11 @@ const lr3dConfig = {
   巷道渲染宽度，默认 `10`
 - `cloud.laneSize.height`
   巷道渲染高度，默认 `10`
-- `cloud.coalLayers`
-  需要加载的煤层图层名数组。
-- `cloud.geofaultLayers`
-  需要加载的断层图层名数组。
-- `cloud.workfaceFeatureTypes`
-  工作面要素编码数组，不传时使用默认值。
-- `cloud.regionFeatureTypes`
-  区域要素编码数组，不传时使用默认值。
-- `cloud.enableRegionAssist`
-  是否启用掘进辅助数据，默认 `false`。
-- `cloud.enableLane`
-  是否启用巷道加载，默认 `true`。
 
 兼容说明：
 
 - 组件内部仍兼容完整的 `lr3dConfig` 写法。
+- `basePoint` 推荐传入 `{ x, y, z }` 对象。
 - 如果你需要覆盖 SDK 路径、容器参数、初始化参数等高级配置，仍然可以继续传入 `sdk`、`scene`、`initOptions`、`dataSource` 完整结构。
 
 ## 示例配置
@@ -301,22 +467,19 @@ const playgroundLr3dConfig = {
   autoLoad: true,
   cloud: {
     server: 'https://your-cloud-gis-server/',
-    mapServerUrl: 'https://your-map-server/',
     username: 'your_username',
     password: 'your_password',
     dsGuid: 'your_ds_guid',
-    dsname: 'your_ds_name',
+    basePoint: {
+      x: 37517614.46684,
+      y: 4410289.679932,
+      z: 972.148557,
+    },
     layers: ['your_lane_layer_name'],
     laneSize: {
       width: 10,
       height: 10,
     },
-    coalLayers: ['your_coal_layer_name'],
-    geofaultLayers: [],
-    workfaceFeatureTypes: ['0202030030'],
-    regionFeatureTypes: ['0202030030', '0106020009', '0202030004', '0202030006'],
-    enableRegionAssist: false,
-    enableLane: true,
   },
 }
 ```
@@ -353,8 +516,8 @@ const playgroundLr3dConfig = {
 典型原因：
 
 - 组件库默认配置已不再携带真实业务参数。
-- 接入方没有传入 `server`、`mapServerUrl`、`username`、`password`、`dsGuid`、`dsname`。
+- 接入方没有传入 `server`、`username`、`password`、`dsGuid`、`basePoint`。
 
 处理方式：
 
-- 在 `lr3dConfig.cloud` 中补齐实际项目所需字段。
+- 在 `lr3dConfig.cloud` 中补齐实际项目所需字段。