@zhangdali1996/lr-map-viewer 0.0.3 → 0.0.5

package/README.md

@@ -1,15 +1,14 @@
 # @zhangdali1996/lr-map-viewer
 
-`@zhangdali1996/lr-map-viewer` 是面向 Vue 3 项目的地图组件库，提供统一的二维、三维地图承载能力，以及基于组件实例的视角控制与模型信息查询能力。
+`@zhangdali1996/lr-map-viewer` 是面向 Vue 3 项目的三维地图组件库，提供龙软三维场景承载能力，以及基于组件实例的视角控制与模型信息查询能力。
 
 主要能力：
 
-- 支持 Vue 3 项目中以组件方式挂载地图容器。
+- 支持 Vue 3 项目中以组件方式挂载三维地图容器。
 - 支持龙软三维 SDK 的运行时加载。
-- 支持基于 `@longruan/lr-map` 的二维图纸显示。
 - 支持通过运行时配置传入云 GIS 参数。
+- 支持通过运行时配置显式传入三维场景 `basePoint`。
 - 支持按需显示区域显隐面板和调试面板。
-- 支持 `2d / 3d` 模式切换壳层。
 - 支持通过组件实例调用 `moveView(x, y, z)` 移动三维视角。
 - 支持通过组件实例注册 `registerModelInfoQuery(callback)` 查询点击模型信息。
 
@@ -53,96 +52,30 @@ public/
 import { LrMapViewer } from '@zhangdali1996/lr-map-viewer'
 
 const lr3dConfig = {
-  sdk: {
-    // 龙软三维 SDK 静态资源根路径
-    basePath: '/editorapp',
-    // 龙软三维主入口脚本地址
-    scriptSrc: '/editorapp/editorapp.bundle.js',
-    // SDK 挂载到 window 上的全局对象名
-    globalNames: ['lr3dapp', 'EditorApp'],
-    dependencies: [
-      {
-        // THREE 依赖脚本地址
-        src: '/resource/js/three.min.js',
-        // THREE 挂载到 window 上的全局对象名
-        globalNames: ['THREE'],
-      },
-      {
-        // SDK 依赖的 Vue2 脚本地址
-        src: '/resource/js/vue.2.6.11.js',
-        globalNames: ['Vue'],
-      },
-      {
-        // SDK 依赖的 element-ui 脚本地址
-        src: '/resource/js/element_ui.js',
-        globalNames: ['ELEMENT'],
-      },
-      {
-        // SDK 依赖的 jQuery 脚本地址
-        src: '/resource/js/jquery-3.1.1.min.js',
-        globalNames: ['jQuery', '$'],
-      },
-    ],
-  },
-  scene: {
-    // 三维容器 ID，需要保证当前页面内唯一
-    containerId: 'customer-lr3d-viewer',
-    // 窗口尺寸变化时是否自动触发 resize
-    autoResize: true,
-  },
-  initOptions: {
-    // 是否显示 SDK 默认菜单
-    showMenu: false,
-    // 是否显示 SDK 默认工具栏
-    showToolbar: false,
-    // 是否显示 SDK 默认侧边栏
-    showSidebar: false,
-    // SDK 场景主题
-    theme: 'shallow',
-    // 初始 basePoint，组件内部会在加载云 GIS 数据后按地图范围重新计算
-    basePoint: { x: 0, y: 0, z: 0 },
-  },
-  dataSource: {
-    // 数据源类型，使用云 GIS 时传 cloud
-    type: 'cloud',
-    // 是否在场景初始化成功后自动加载云 GIS 数据
-    autoLoad: false,
-    // 数据加载模式，workfaceOnly 表示按工作面/区域/巷道组合加载
-    loadMode: 'workfaceOnly',
-    cloud: {
-      // 云 GIS 服务地址
-      server: '',
-      // 地图服务地址，用于获取地图元数据和范围
-      mapServerUrl: '',
-      // 云 GIS 用户名
-      username: '',
-      // 云 GIS 密码
-      password: '',
-      // 数据源 guid
-      dsGuid: '',
-      // 数据源名称
-      dsname: '',
-      laneSize: {
-        // 巷道渲染宽度
-        width: 10,
-        // 巷道渲染高度
-        height: 10,
-      },
-      // 需要加载的巷道图层名数组
-      // 不传时按服务返回结果处理，传入后会按图层名过滤
-      layers: [],
-      // 需要加载的煤层图层名数组
-      coalLayers: [],
-      // 需要加载的断层图层名数组
-      geofaultLayers: [],
-      // 工作面要素编码数组
-      workfaceFeatureTypes: ['0202030030'],
-      // 区域要素编码数组
-      regionFeatureTypes: ['0202030030', '0106020009', '0202030004', '0202030006'],
-      // 是否启用掘进辅助数据
-      enableRegionAssist: false,
-      // 是否启用巷道加载
-      enableLane: true,
+  // 是否在场景初始化成功后自动加载云 GIS 数据
+  autoLoad: true,
+  cloud: {
+    // 云 GIS 服务地址
+    server: 'https://your-cloud-gis-server/',
+    // 云 GIS 用户名
+    username: 'your_username',
+    // 云 GIS 密码
+    password: 'your_password',
+    // 数据源 guid
+    dsGuid: 'your_ds_guid',
+    // 三维场景基点
+    basePoint: {
+      x: 37517614.46684,
+      y: 4410289.679932,
+      z: 972.148557,
+    },
+    // 需要加载的巷道图层名
+    layers: ['your_lane_layer_name'],
+    laneSize: {
+      // 巷道渲染宽度
+      width: 10,
+      // 巷道渲染高度
+      height: 10,
     },
   },
 }
@@ -165,62 +98,11 @@ const lr3dConfig = {
 />
 ```
 
-## 二维图纸最小接入示例
-
-`2d` 模式通过传入图纸运行参数完成初始化，使用方直接提供所需配置即可。
-
-```vue
-<script setup>
-import { LrMapViewer } from '@zhangdali1996/lr-map-viewer'
-
-const map2dConfig = {
-  behavior: {
-    // 初始化后是否自动创建默认图层
-    autoInitLayer: true,
-    // 初始化后是否自动显示默认图层
-    autoShowLayer: true,
-    // 是否捕获图层树结构
-    captureLayerTree: true,
-  },
-  options: {
-    // 云 GIS 数据源 guid
-    ygis_dsGuid: 'your_ygis_ds_guid',
-    // 云 GIS 服务地址
-    ygis_url: 'https://your-cloud-gis-server/',
-    // 地图服务地址
-    Url: 'https://your-map-server/',
-    // 二维图层名称
-    layerName: 'your_layer_name',
-    // 图层编码，不需要时可留空
-    layerCode: '',
-    // 初始显示范围
-    extent: 'minX,minY,maxX,maxY',
-    // 云 GIS 用户名
-    ygis_username: 'your_username',
-    // 云 GIS 密码
-    ygis_password: 'your_password',
-    // 是否旋转视图
-    rotate: false,
-    // 是否开启平移动画
-    animate: false,
-    // 是否开启缩放动画
-    zoomAnimation: false,
-    // 是否开启 marker 缩放动画
-    markerZoomAnimation: false,
-    // 是否开启淡入淡出动画
-    fadeAnimation: false,
-  },
-}
-</script>
-
-<template>
-  <div style="height: 100vh;">
-    <LrMapViewer mode="2d" :modes="['2d', '3d']" :map2d-config="map2dConfig" />
-  </div>
-</template>
-```
+说明：
 
-如果你使用 token 鉴权，可以用 `token` 替代 `ygis_username / ygis_password`。
+- 三维组件已内置默认的 `sdk`、`scene`、`initOptions`、`dataSource.type`、`dataSource.loadMode` 配置，通常不需要手动传入。
+- 推荐只传 `autoLoad` 和 `cloud` 下的业务参数即可。
+- 如果你有特殊需求，仍然可以继续传完整的 `lr3dConfig` 结构来覆盖默认值。
 
 ## 推荐接入方式
 
@@ -244,14 +126,8 @@ createApp(App).use(LrMapViewerPlugin).mount('#app')
 
 组件 Props：
 
-- `mode`
-  组件显示模式，支持 `2d` 或 `3d`。
-- `modes`
-  当前实例允许使用的模式集合。
 - `lr3dConfig`
   龙软三维运行时配置。
-- `map2dConfig`
-  二维地图运行时配置对象。
 - `showRegionPanel`
   是否显示区域显隐面板，默认 `false`。
 - `showDebugPanel`
@@ -262,7 +138,6 @@ createApp(App).use(LrMapViewerPlugin).mount('#app')
 - `switchMode(mode)`
 - `getCurrentMode()`
 - `getCurrentEngine()`
-- `get2dInstance()`
 - `get3dInstance()`
 - `resize()`
 - `refreshScene()`
@@ -271,8 +146,7 @@ createApp(App).use(LrMapViewerPlugin).mount('#app')
 
 说明：
 
-- `get2dInstance()` 返回二维适配层实例，内部包含 `map`、`layerTree`、`options` 等信息。
-- `refreshScene()` 仅对 `3d` 模式有效。
+- `refreshScene()` 仅对三维场景有效。
 - `moveView(x, y, z)` 传入的是绝对三维坐标，组件内部会自动换算成相对 `basePoint` 坐标后调用聚焦接口。
 - `registerModelInfoQuery(callback)` 会在用户点击三维中的模型对象时触发回调。
 - 模型信息查询返回 4 个字段：`id`、`name`、`layerName`、`position`。
@@ -346,33 +220,67 @@ watch(
 
 ## 云 GIS 配置说明
 
-组件库不再内置任何真实云 GIS 账号或数据源信息。以下字段必须由接入方按项目实际情况传入：
+推荐写法：
 
-- `server`
-- `mapServerUrl`
-- `username`
-- `password`
-- `dsGuid`
-- `dsname`
+```js
+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'],
+    laneSize: {
+      width: 10,
+      height: 10,
+    },
+  },
+}
+```
+
+必填字段：
+
+- `autoLoad`
+  是否在场景初始化成功后自动加载云 GIS 数据。
+- `cloud.server`
+  云 GIS 服务地址。
+- `cloud.username`
+  云 GIS 用户名。
+- `cloud.password`
+  云 GIS 密码。
+- `cloud.dsGuid`
+  数据源 guid。
+- `cloud.basePoint.x`
+  三维场景基点 x 坐标。
+- `cloud.basePoint.y`
+  三维场景基点 y 坐标。
+- `cloud.basePoint.z`
+  三维场景基点 z 坐标。
 
 可选字段：
 
-- `laneSize.width`
+- `cloud.layers`
+  需要加载的巷道图层名数组。
+- `cloud.laneSize.width`
   巷道渲染宽度，默认 `10`
-- `laneSize.height`
+- `cloud.laneSize.height`
   巷道渲染高度，默认 `10`
+- `cloud.mapServerUrl`
+  可按业务需要继续透传，但不再用于组件内部计算 `basePoint`。
+- `cloud.dsname`
+  可按业务需要继续透传，但不再作为三维基础加载必填项。
 
-如果开启：
-
-```js
-dataSource: {
-  autoLoad: true
-}
-```
-
-则组件初始化成功后会自动尝试加载云 GIS 数据。
+兼容说明：
 
-如果不希望默认自动加载，请将其设为 `false`，再通过你的业务流程手动触发三维数据加载。
+- 组件内部仍兼容完整的 `lr3dConfig` 写法。
+- `basePoint` 推荐传入 `{ x, y, z }` 对象。
+- 如果你需要覆盖 SDK 路径、容器参数、初始化参数等高级配置，仍然可以继续传入 `sdk`、`scene`、`initOptions`、`dataSource` 完整结构。
 
 ## 示例配置
 
@@ -380,97 +288,21 @@ dataSource: {
 
 ```js
 const playgroundLr3dConfig = {
-  sdk: {
-    // 龙软三维 SDK 静态资源根路径
-    basePath: '/editorapp',
-    // 龙软三维主入口脚本地址
-    scriptSrc: '/editorapp/editorapp.bundle.js',
-    // SDK 挂载到 window 上的全局对象名
-    globalNames: ['lr3dapp', 'EditorApp'],
-    dependencies: [
-      {
-        // THREE 依赖脚本地址
-        src: '/resource/js/three.min.js',
-        globalNames: ['THREE'],
-      },
-      {
-        // SDK 依赖的 Vue2 脚本地址
-        src: '/resource/js/vue.2.6.11.js',
-        globalNames: ['Vue'],
-      },
-      {
-        // SDK 依赖的 element-ui 脚本地址
-        src: '/resource/js/element_ui.js',
-        globalNames: ['ELEMENT'],
-      },
-      {
-        // SDK 依赖的 jQuery 脚本地址
-        src: '/resource/js/jquery-3.1.1.min.js',
-        globalNames: ['jQuery', '$'],
-      },
-    ],
-  },
-  scene: {
-    // playground 中三维容器 ID
-    containerId: 'playground-lr3d-viewer',
-    // 窗口尺寸变化时自动触发 resize
-    autoResize: true,
-  },
-  initOptions: {
-    // 不显示 SDK 默认菜单
-    showMenu: false,
-    // 不显示 SDK 默认工具栏
-    showToolbar: false,
-    // 不显示 SDK 默认侧边栏
-    showSidebar: false,
-    // 场景主题
-    theme: 'shallow',
+  autoLoad: true,
+  cloud: {
+    server: 'https://your-cloud-gis-server/',
+    username: 'your_username',
+    password: 'your_password',
+    dsGuid: 'your_ds_guid',
     basePoint: {
-      x: 0,
-      y: 0,
-      z: 0,
+      x: 37517614.46684,
+      y: 4410289.679932,
+      z: 972.148557,
     },
-  },
-  dataSource: {
-    // 数据源类型
-    type: 'cloud',
-    // 初始化完成后自动加载云 GIS 数据
-    autoLoad: true,
-    // 按工作面模式加载
-    loadMode: 'workfaceOnly',
-    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',
-      // 需要加载的巷道图层名
-      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,
+    layers: ['your_lane_layer_name'],
+    laneSize: {
+      width: 10,
+      height: 10,
     },
   },
 }
@@ -490,7 +322,7 @@ const playgroundLr3dConfig = {
 
 1. 确认客户项目里确实存在 `public/resource/js/jquery-3.1.1.min.js`。
 2. 确认浏览器访问 `/resource/js/jquery-3.1.1.min.js` 返回 200，而不是 404。
-3. 如果资源目录不在根路径，检查 `lr3dConfig.sdk.dependencies` 里的 `src` 是否已改成真实路径。
+3. 如果资源目录不在根路径，使用完整 `lr3dConfig.sdk.dependencies` 配置覆盖默认脚本路径。
 4. 确认 `editorapp` 与 `resource` 属于同一套 SDK 版本，不要混用不同批次文件。
 
 ### 2. 场景初始化失败：未检测到全局对象
@@ -499,7 +331,7 @@ const playgroundLr3dConfig = {
 
 排查方向：
 
-1. 检查 `globalNames` 配置是否与当前 SDK 版本匹配。
+1. 检查使用的 SDK 版本是否与组件默认配置匹配。
 2. 检查脚本是否被浏览器拦截、跨域策略阻止，或返回了错误 HTML 页面。
 3. 检查依赖加载顺序是否正确，前置依赖必须先于 `editorapp.bundle.js` 完成加载。
 
@@ -508,30 +340,8 @@ const playgroundLr3dConfig = {
 典型原因：
 
 - 组件库默认配置已不再携带真实业务参数。
-- 接入方没有传入 `server`、`mapServerUrl`、`username`、`password`、`dsGuid`、`dsname`。
+- 接入方没有传入 `server`、`username`、`password`、`dsGuid`、`basePoint`。
 
 处理方式：
 
-- 在 `lr3dConfig.dataSource.cloud` 中补齐实际项目所需字段。
-
-### 4. 切换到 2D 后提示配置不完整
-
-当前二维模式要求 `map2dConfig.options` 至少传入：
-
-- `ygis_dsGuid`
-- `ygis_url`
-- `Url`
-- `layerName`
-- `token` 或 `ygis_username + ygis_password`
-
-如果缺少这些字段，组件会直接在页面顶部提示缺失项，而不会继续初始化二维地图。
-
-## 本地联调
-
-在仓库根目录执行：
-
-```bash
-npm run dev:playground
-```
-
-该命令会启动示例工程 [`playground/src/App.vue`](/F:/WorkSpace/jzxy/cloud-gis-3d/playground/src/App.vue)，可用于本地联调和接口验证。
+- 在 `lr3dConfig.cloud` 中补齐实际项目所需字段。