@zhangdali1996/lr-map-viewer 0.0.2

package/README.md

@@ -0,0 +1,537 @@
+# @zhangdali1996/lr-map-viewer
+
+`@zhangdali1996/lr-map-viewer` 是面向 Vue 3 项目的地图组件库，提供统一的二维、三维地图承载能力，以及基于组件实例的视角控制与模型信息查询能力。
+
+主要能力：
+
+- 支持 Vue 3 项目中以组件方式挂载地图容器。
+- 支持龙软三维 SDK 的运行时加载。
+- 支持基于 `@longruan/lr-map` 的二维图纸显示。
+- 支持通过运行时配置传入云 GIS 参数。
+- 支持按需显示区域显隐面板和调试面板。
+- 支持 `2d / 3d` 模式切换壳层。
+- 支持通过组件实例调用 `moveView(x, y, z)` 移动三维视角。
+- 支持通过组件实例注册 `registerModelInfoQuery(callback)` 查询点击模型信息。
+
+## 安装
+
+```bash
+npm install @zhangdali1996/lr-map-viewer
+```
+
+`vue` 和 `element-plus` 作为 `peerDependencies` 提供，要求使用方项目自行安装。
+
+## 静态资源放置
+
+该包不会携带龙软 SDK 的大体积静态资源。以下目录需要由实施方单独提供给客户：
+
+- `editorapp`
+- `resource`
+
+推荐放置到客户项目的 `public` 目录：
+
+```text
+public/
+  editorapp/
+  resource/
+```
+
+对应默认访问路径：
+
+- `/editorapp/editorapp.bundle.js`
+- `/resource/js/three.min.js`
+- `/resource/js/vue.2.6.11.js`
+- `/resource/js/element_ui.js`
+- `/resource/js/jquery-3.1.1.min.js`
+
+如果客户项目的静态资源目录不是根路径，需要通过 `lr3dConfig.sdk` 自定义覆盖路径。
+
+## 最小接入示例
+
+```vue
+<script setup>
+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,
+    },
+  },
+}
+</script>
+
+<template>
+  <div style="height: 100vh;">
+    <LrMapViewer :lr3d-config="lr3dConfig" />
+  </div>
+</template>
+```
+
+如果你需要默认显示右上角区域显隐面板和调试面板：
+
+```vue
+<LrMapViewer
+  :lr3d-config="lr3dConfig"
+  :show-region-panel="true"
+  :show-debug-panel="true"
+/>
+```
+
+## 二维图纸最小接入示例
+
+`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`。
+
+## 推荐接入方式
+
+推荐直接按需引入组件：
+
+```js
+import { LrMapViewer } from '@zhangdali1996/lr-map-viewer'
+```
+
+也支持作为插件安装：
+
+```js
+import { createApp } from 'vue'
+import LrMapViewerPlugin from '@zhangdali1996/lr-map-viewer'
+import App from './App.vue'
+
+createApp(App).use(LrMapViewerPlugin).mount('#app')
+```
+
+## 公开能力
+
+组件 Props：
+
+- `mode`
+  组件显示模式，支持 `2d` 或 `3d`。
+- `modes`
+  当前实例允许使用的模式集合。
+- `lr3dConfig`
+  龙软三维运行时配置。
+- `map2dConfig`
+  二维地图运行时配置对象。
+- `showRegionPanel`
+  是否显示区域显隐面板，默认 `false`。
+- `showDebugPanel`
+  是否显示调试面板，默认 `false`。
+
+组件 expose：
+
+- `switchMode(mode)`
+- `getCurrentMode()`
+- `getCurrentEngine()`
+- `get2dInstance()`
+- `get3dInstance()`
+- `resize()`
+- `refreshScene()`
+- `moveView(x, y, z)`
+- `registerModelInfoQuery(callback)`
+
+说明：
+
+- `get2dInstance()` 返回二维适配层实例，内部包含 `map`、`layerTree`、`options` 等信息。
+- `refreshScene()` 仅对 `3d` 模式有效。
+- `moveView(x, y, z)` 传入的是绝对三维坐标，组件内部会自动换算成相对 `basePoint` 坐标后调用聚焦接口。
+- `registerModelInfoQuery(callback)` 会在用户点击三维中的模型对象时触发回调。
+- 模型信息查询返回 4 个字段：`id`、`name`、`layerName`、`position`。
+
+## 接口示例
+
+推荐通过 `ref` 调用组件实例方法：
+
+```vue
+<script setup>
+import { ref, watch } from 'vue'
+import { LrMapViewer } from '@zhangdali1996/lr-map-viewer'
+
+const viewerRef = ref(null)
+
+function handleMoveView() {
+  viewerRef.value?.moveView?.(
+    // x 坐标（绝对坐标）
+    37515326.469929,
+    // y 坐标（绝对坐标）
+    4412734.214238,
+    // z 坐标（绝对坐标）
+    1311.15,
+  )
+}
+
+watch(
+  viewerRef,
+  (viewer) => {
+    if (!viewer?.registerModelInfoQuery) {
+      return
+    }
+
+    viewer.registerModelInfoQuery((payload) => {
+      // payload 为点击模型后返回的模型信息
+      console.log('model info', payload)
+    })
+  },
+  { immediate: true },
+)
+</script>
+
+<template>
+  <div style="height: 100vh;">
+    <button type="button" @click="handleMoveView">移动视角</button>
+    <LrMapViewer ref="viewerRef" :lr3d-config="lr3dConfig" />
+  </div>
+</template>
+```
+
+模型信息查询回调返回结构：
+
+```js
+{
+  // 模型或实体标识
+  id: '...',
+  // 模型或实体名称
+  name: '...',
+  // 所属图层名
+  layerName: '...',
+  position: {
+    // 模型本地坐标 x
+    x: 0,
+    // 模型本地坐标 y
+    y: 0,
+    // 模型本地坐标 z
+    z: 0,
+  },
+}
+```
+
+## 云 GIS 配置说明
+
+组件库不再内置任何真实云 GIS 账号或数据源信息。以下字段必须由接入方按项目实际情况传入：
+
+- `server`
+- `mapServerUrl`
+- `username`
+- `password`
+- `dsGuid`
+- `dsname`
+
+可选字段：
+
+- `laneSize.width`
+  巷道渲染宽度，默认 `10`
+- `laneSize.height`
+  巷道渲染高度，默认 `10`
+
+如果开启：
+
+```js
+dataSource: {
+  autoLoad: true
+}
+```
+
+则组件初始化成功后会自动尝试加载云 GIS 数据。
+
+如果不希望默认自动加载，请将其设为 `false`，再通过你的业务流程手动触发三维数据加载。
+
+## 示例配置
+
+下面这份三维配置可直接作为联调参考：
+
+```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',
+    basePoint: {
+      x: 0,
+      y: 0,
+      z: 0,
+    },
+  },
+  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,
+    },
+  },
+}
+```
+
+## 常见错误排查
+
+### 1. 场景初始化失败：SDK 前置依赖加载失败
+
+典型错误：
+
+```text
+场景初始化失败：SDK 前置依赖加载失败: /resource/js/jquery-3.1.1.min.js
+```
+
+排查方向：
+
+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` 是否已改成真实路径。
+4. 确认 `editorapp` 与 `resource` 属于同一套 SDK 版本，不要混用不同批次文件。
+
+### 2. 场景初始化失败：未检测到全局对象
+
+这类错误通常表示脚本文件虽然加载了，但脚本执行后没有挂出预期全局变量。
+
+排查方向：
+
+1. 检查 `globalNames` 配置是否与当前 SDK 版本匹配。
+2. 检查脚本是否被浏览器拦截、跨域策略阻止，或返回了错误 HTML 页面。
+3. 检查依赖加载顺序是否正确，前置依赖必须先于 `editorapp.bundle.js` 完成加载。
+
+### 3. 云 GIS 数据源配置缺失
+
+典型原因：
+
+- 组件库默认配置已不再携带真实业务参数。
+- 接入方没有传入 `server`、`mapServerUrl`、`username`、`password`、`dsGuid`、`dsname`。
+
+处理方式：
+
+- 在 `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)，可用于本地联调和接口验证。