@zhangdali1996/lr-map-viewer 0.0.5 → 0.0.7

package/README.md

@@ -4,8 +4,11 @@
 
 主要能力：
 
+- 支持 Vue 3 项目中以组件方式挂载二维图纸容器。
 - 支持 Vue 3 项目中以组件方式挂载三维地图容器。
+- 支持 `2d / 3d` 模式切换与统一壳层承载。
 - 支持龙软三维 SDK 的运行时加载。
+- 支持通过运行时配置传入二维图纸参数。
 - 支持通过运行时配置传入云 GIS 参数。
 - 支持通过运行时配置显式传入三维场景 `basePoint`。
 - 支持按需显示区域显隐面板和调试面板。
@@ -47,20 +50,18 @@ public/
 
 ## 最小接入示例
 
+### 三维示例
+
 ```vue
 <script setup>
 import { LrMapViewer } from '@zhangdali1996/lr-map-viewer'
 
+const credentialKey = 'your_credential_key'
+
 const lr3dConfig = {
   // 是否在场景初始化成功后自动加载云 GIS 数据
   autoLoad: true,
   cloud: {
-    // 云 GIS 服务地址
-    server: 'https://your-cloud-gis-server/',
-    // 云 GIS 用户名
-    username: 'your_username',
-    // 云 GIS 密码
-    password: 'your_password',
     // 数据源 guid
     dsGuid: 'your_ds_guid',
     // 三维场景基点
@@ -83,7 +84,85 @@ const lr3dConfig = {
 
 <template>
   <div style="height: 100vh;">
-    <LrMapViewer :lr3d-config="lr3dConfig" />
+    <LrMapViewer :lr3d-config="lr3dConfig" :credential-key="credentialKey" />
+  </div>
+</template>
+```
+
+### 二维图纸示例
+
+```vue
+<script setup>
+import { LrMapViewer } from '@zhangdali1996/lr-map-viewer'
+
+const credentialKey = 'your_credential_key'
+
+const map2dConfig = {
+  behavior: {
+    autoInitLayer: true,
+    autoShowLayer: true,
+    captureLayerTree: true,
+  },
+  options: {
+    ygis_dsGuid: 'your_ds_guid',
+    layerName: 'your_layer_name',
+    layerCode: '',
+  },
+}
+</script>
+
+<template>
+  <div style="height: 100vh;">
+    <LrMapViewer
+      mode="2d"
+      :modes="['2d']"
+      :map2d-config="map2dConfig"
+      :credential-key="credentialKey"
+    />
+  </div>
+</template>
+```
+
+### 二维三维切换示例
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { LrMapViewer } from '@zhangdali1996/lr-map-viewer'
+
+const activeMode = ref('2d')
+const credentialKey = 'your_credential_key'
+
+const map2dConfig = {
+  options: {
+    ygis_dsGuid: 'your_ds_guid',
+    layerName: 'your_layer_name',
+  },
+}
+
+const lr3dConfig = {
+  autoLoad: true,
+  cloud: {
+    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"
+      :credential-key="credentialKey"
+    />
   </div>
 </template>
 ```
@@ -93,6 +172,7 @@ const lr3dConfig = {
 ```vue
 <LrMapViewer
   :lr3d-config="lr3dConfig"
+  :credential-key="credentialKey"
   :show-region-panel="true"
   :show-debug-panel="true"
 />
@@ -126,8 +206,16 @@ createApp(App).use(LrMapViewerPlugin).mount('#app')
 
 组件 Props：
 
+- `mode`
+  当前激活模式，支持 `2d` 或 `3d`。
+- `modes`
+  当前组件允许启用的模式列表，默认 `['3d']`。
+- `map2dConfig`
+  二维图纸运行时配置。
 - `lr3dConfig`
   龙软三维运行时配置。
+- `credentialKey`
+  内部凭证解密 Key，二维与三维都会使用它解析内置认证信息。
 - `showRegionPanel`
   是否显示区域显隐面板，默认 `false`。
 - `showDebugPanel`
@@ -138,6 +226,7 @@ createApp(App).use(LrMapViewerPlugin).mount('#app')
 - `switchMode(mode)`
 - `getCurrentMode()`
 - `getCurrentEngine()`
+- `get2dInstance()`
 - `get3dInstance()`
 - `resize()`
 - `refreshScene()`
@@ -146,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` 调用组件实例方法：
@@ -197,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
@@ -271,10 +451,6 @@ const lr3dConfig = {
   巷道渲染宽度，默认 `10`
 - `cloud.laneSize.height`
   巷道渲染高度，默认 `10`
-- `cloud.mapServerUrl`
-  可按业务需要继续透传，但不再用于组件内部计算 `basePoint`。
-- `cloud.dsname`
-  可按业务需要继续透传，但不再作为三维基础加载必填项。
 
 兼容说明：