huweili-cesium 1.2.33 → 1.2.35

package/README.md

@@ -1,297 +1,297 @@
-# huweili-cesium
-
-基于 Cesium 的地图工具库。所有 **JS 模块** 位于包内 `js/` 目录（含 `toolbar`、`stores`、`utils`、`config`、`api` 子目录）；根目录保留 `index.js`（npm 主入口）与 `index.vue`（地图组件）。
-
-## 安装
-
-```bash
-npm install huweili-cesium
-```
-
-### 对等依赖（需在项目中已安装）
-
-- `cesium` 1.136.0
-- `vue` ^3.3
-- `pinia` ^2 或 ^3
-- `mitt` 3
-- `qrcode` 1.5
-
-## 使用前准备
-
-1. 在 HTML 中加载与宿主项目一致的 `constants.js`（定义 `window.DroneStatus`、`window.MapInstanceIds` 等），或自行赋值这些全局变量。
-2. 在 Vue 应用中 `app.use(pinia)`，地图组件初始化后调用各 `*Config()` 工厂函数。
-
-## 引入示例
-
-### JS 模块
-
-```js
-// 主入口同时支持：默认导出组件 + 命名导出 JS 模块
-import CesiumMap, { basicConfig, setPoint, movePointConfig } from 'huweili-cesium'
-
-// 仅 JS 模块（不含 Vue 组件）可用子路径
-import { basicConfig } from 'huweili-cesium/js'
-
-// 或按文件引入
-import { basicConfig } from 'huweili-cesium/basis'
-import { hemisphereConfig } from 'huweili-cesium/hemisphere'
-import { createCustomToolbarButtons } from 'huweili-cesium/customToolbarButtons'
-```
-
-### Vue 地图组件（开箱即用）
-
-```vue
-<template>
-  <div class="map-page">
-    <CesiumMap map-id="default" @onload="onMapLoad" />
-  </div>
-</template>
-
-<script setup>
-// 推荐：包主入口默认导出组件
-import CesiumMap from 'huweili-cesium'
-// 等价写法：
-// import CesiumMap from 'huweili-cesium/index.vue'
-// import CesiumMap from 'huweili-cesium/CesiumMap'
-
-function onMapLoad({ map, center }) {
-  console.log('地图已加载', map, center)
-}
-</script>
-
-<style scoped>
-.map-page {
-  width: 100%;
-  height: 100vh;
-}
-</style>
-```
-
-**Vite 宿主项目**需在 `vite.config` 中允许编译该依赖（否则 `.vue` 可能无法处理）：
-
-```js
-export default defineConfig({
-  optimizeDeps: {
-    include: ['huweili-cesium'],
-  },
-})
-```
-
-组件 props：
-
-| prop | 类型 | 默认 | 说明 |
-|------|------|------|------|
-| `mapId` | `string` | `'default'` | 多地图实例 ID，与 `mapStore` 对应 |
-| `options` | `object` | — | 覆盖/合并 `MapConfig` 的配置 |
-
-事件：`@onload`，参数 `{ map, center, mapId, toolbar }`（`map` 为 Cesium `Viewer` 实例；`toolbar` 可在加载后动态增删按钮）。
-
-### 为何不用 Cesium 内置 2D 模式
-
-Viewer 固定为 `SCENE3D`，业务上的「2D」是 **正交相机 + 俯视**（`basis.js` / `cameraInteraction.js`），不切换 `SCENE2D` / `COLUMBUS_VIEW`。简要优点：
-
-- **2D/3D 切换更顺**：无场景变形（morph），透视与正交互换，缩放与锚点更易对齐（含工具栏切换、RTK 跟飞）。
-- **渲染一致**：无人机、轨迹、围栏等与 3D 同一套规则，少踩 2D 投影下的显示差异。
-- **交互可控**：2D 可锁定俯视、自定义滚轮缩放（正交宽度），避免与内置 2D 控制器行为不一致。
-- **语义清晰**：`mapStore` 的 `2D`/`3D` 表示业务视角，不与 Cesium `SceneMode` 枚举混用。
-
-配置里 `scene.sceneMode: '2D'` 表示初始化俯视正交，而非启用 Cesium 平面地图模式。
-
-### 各项目自定义工具栏
-
-**方式 1：组件 props（推荐）**
-
-```vue
-<CesiumMap
-  map-id="default"
-  :show-default-toolbar="true"
-  :extra-toolbar-buttons="myExtraButtons"
-/>
-```
-
-```js
-import { useEventBus } from 'huweili-cesium/utils/useEventBus'
-
-const { emit } = useEventBus()
-
-const myExtraButtons = [
-  {
-    title: '导出',
-    text: '导',
-    onClick: () => emit('exportMap', {}),
-  },
-]
-```
-
-完全不用内置默认按钮、自己定义一整组：
-
-```vue
-<CesiumMap :toolbar-buttons="myToolbarButtons" />
-```
-
-内置默认按钮里的图标路径使用宿主项目的 `import.meta.env.BASE_URL`（如 `/images/new/tj.svg`），请在宿主 `public/images/new/` 放置对应资源；业务按钮（如「机型统计」）通过 `useEventBus` 发事件，宿主需自行 `on('toggleBarChartControl', ...)` 监听。
-
-## 可选业务钩子
-
-若需光电引导、轨迹列表等业务能力，在应用启动时注入：
-
-```js
-import { setDroneMapProvider, setOptGuideHandler } from 'huweili-cesium/config/hooks'
-
-setDroneMapProvider(() => myDroneMap)
-setOptGuideHandler((payload) => api.toOptGuide(payload))
-```
-
-## 发布到 npm（维护者）
-
-```bash
-cd huweili-cesium
-npm login
-npm publish
-```
-
-首次发布前可在本地打包预览：
-
-```bash
-npm pack
-# 会生成 huweili-cesium-1.0.0.tgz，解压检查是否包含全部 js
-```
-
-## 从 tzr 源目录同步更新
-
-```bash
-cd huweili-cesium
-npm run sync
-# 同步后需重新修复 @/ 别名为包内相对路径（见 scripts）
-```
-
-## 地图与自定义工具栏
-
-地图组件来自 npm 包 **`huweili-cesium`**，工具栏按钮在业务侧配置，不写在 `mapConfig.js` 里。
-
-### 1. 前置配置（`constants.js` / `mapConfig.js`）
-
-`index.html` 中已按顺序引入：
-
-```html
-<script src="/config/constants.js"></script>
-<script src="/config/mapConfig.js"></script>
-```
-
-| 文件 | 作用 | 与地图组件的关系 |
-|------|------|------------------|
-| `public/config/constants.js` | `window.MapInstanceIds` 定义多地图 ID（如 `HOME: 'home-main-map'`） | `:map-id` 须与之一致，工具栏回调里的 `mapId` 也要传同一个值 |
-| `public/config/mapConfig.js` | `window.MapConfig`（中心点、2D/3D、底图列表、是否显示 Cesium 自带控件等） | 控制地图初始化；`control.homeButton: false` 时由自定义工具栏替代 |
-
-在页面中引用常量（从 `runtimeConfig` 导入）：
-
-```js
-import { MapInstanceIds } from '@/config/runtimeConfig'
-
-const HOME_MAP_ID = MapInstanceIds?.HOME || 'home-main-map'
-```
-
-### 2. 页面引用 `CesiumMap`（首页示例）
-
-`src/views/home/indexnew.vue`：
-
-```vue
-<template>
-  <CesiumMap
-    :map-id="HOME_MAP_ID"
-    :toolbar-buttons="getHomeToolbarButtons({ mapId: HOME_MAP_ID })"
-    @onload="mapOnLoad"
-  />
-</template>
-
-<script setup>
-import CesiumMap from 'huweili-cesium'
-import { MapInstanceIds } from '@/config/runtimeConfig'
-import { getHomeToolbarButtons } from '@/utils/homeToolbarButtons'
-
-const HOME_MAP_ID = MapInstanceIds?.HOME || 'home-main-map'
-</script>
-```
-
-- **`toolbar-buttons`**：传入整组按钮（首页不用包内默认按钮，因此不必再写 `show-default-toolbar`）
-- **`map-id`**：与 `constants.js` 里 `MapInstanceIds.HOME` 保持一致
-
-### 3. 工具栏按钮配置（`src/utils/homeToolbarButtons.js`）
-
-通用按钮（指北针、机型统计、回中心、2D/3D、缩放、底图、全屏）集中在此文件维护。
-
-页面只需追加自己的按钮时，使用 `extra`：
-
-```js
-import { useEventBus } from 'huweili-cesium/utils/useEventBus'
-import { getHomeToolbarButtons } from '@/utils/homeToolbarButtons'
-
-const { emit } = useEventBus()
-
-getHomeToolbarButtons({
-  mapId: HOME_MAP_ID,
-  extra: [
-    {
-      title: '导出',
-      text: '导',
-      onClick: () => emit('exportMap', {}),
-    },
-  ],
-})
-```
-
-按钮项字段说明：
-
-| 字段 | 说明 |
-|------|------|
-| `title` | 悬停提示 |
-| `text` / `iconSrc` | 文字或图标（二选一，图标放 `public/images/new/`） |
-| `isCompass: true` | 指北针专用 |
-| `onClick(viewer, button)` | 点击回调 |
-
-「机型统计」等通过 `useEventBus` 发事件，页面需 `on('toggleBarChartControl', ...)` 监听。
-
-### 4. 其他页面
-
-- 复用首页整套按钮：`getHomeToolbarButtons({ mapId: '你的 mapId' })`
-- 完全自定义：直接传数组给 `:toolbar-buttons="[...]"`
-- 地图加载后动态增删：在 `@onload` 回调里使用返回的 `toolbar.addToolbarButton(...)`
-
-图标资源路径使用 `import.meta.env.BASE_URL`（如 `/jlap/images/new/xxx.svg`），请放在 `public/images/new/`。
-
-## 目录结构
-
-```
-huweili-cesium/
-├── index.js          # npm 主入口（默认导出 CesiumMap + 转发 js 模块）
-├── index.vue         # 地图 Vue 组件
-├── components/       # 组件（如 wsIndicator）
-├── js/               # 全部 JS 模块
-│   ├── basis.js
-│   ├── toolbar/
-│   ├── stores/
-│   ├── utils/
-│   ├── config/
-│   └── api/
-└── package.json
-```
-
-## 包含的文件清单（均在 `js/` 下）
-
-| 文件 | 说明 |
-|------|------|
-| js/basis.js | 地图基础操作 |
-| js/setPoint.js / js/movePoint.js | 点位与移动 |
-| js/setPath.js / js/movePath.js | 路径与轨迹 |
-| js/groundLink.js | 地面连接线 |
-| js/hemisphere.js | 半球区域 |
-| js/geometry.js | 几何图形 |
-| js/drawFence.js / js/drawFenceNew.js | 电子围栏 |
-| js/cardPool.js / js/labelDiv.js | 信息牌 |
-| js/clickHandler.js | 点击交互 |
-| js/tileProviders.js | 底图瓦片 |
-| js/customToolbarButtons.js | 工具栏 |
-| js/toolbar/* | 指南针、底图切换、缩放、全屏 |
-| js/droneRipple.js / js/qrCodeGenerator.js | 涟漪、二维码 |
-
-另含 `js/stores/mapStore.js`、`js/utils/*`、`js/config/*`、`js/api/*` 等运行依赖。
+# huweili-cesium
+
+基于 Cesium 的地图工具库。所有 **JS 模块** 位于包内 `js/` 目录（含 `toolbar`、`stores`、`utils`、`config`、`api` 子目录）；根目录保留 `index.js`（npm 主入口）与 `index.vue`（地图组件）。
+
+## 安装
+
+```bash
+npm install huweili-cesium
+```
+
+### 对等依赖（需在项目中已安装）
+
+- `cesium` 1.136.0
+- `vue` ^3.3
+- `pinia` ^2 或 ^3
+- `mitt` 3
+- `qrcode` 1.5
+
+## 使用前准备
+
+1. 在 HTML 中加载与宿主项目一致的 `constants.js`（定义 `window.DroneStatus`、`window.MapInstanceIds` 等），或自行赋值这些全局变量。
+2. 在 Vue 应用中 `app.use(pinia)`，地图组件初始化后调用各 `*Config()` 工厂函数。
+
+## 引入示例
+
+### JS 模块
+
+```js
+// 主入口同时支持：默认导出组件 + 命名导出 JS 模块
+import CesiumMap, { basicConfig, setPoint, movePointConfig } from 'huweili-cesium'
+
+// 仅 JS 模块（不含 Vue 组件）可用子路径
+import { basicConfig } from 'huweili-cesium/js'
+
+// 或按文件引入
+import { basicConfig } from 'huweili-cesium/basis'
+import { hemisphereConfig } from 'huweili-cesium/hemisphere'
+import { createCustomToolbarButtons } from 'huweili-cesium/customToolbarButtons'
+```
+
+### Vue 地图组件（开箱即用）
+
+```vue
+<template>
+  <div class="map-page">
+    <CesiumMap map-id="default" @onload="onMapLoad" />
+  </div>
+</template>
+
+<script setup>
+// 推荐：包主入口默认导出组件
+import CesiumMap from 'huweili-cesium'
+// 等价写法：
+// import CesiumMap from 'huweili-cesium/index.vue'
+// import CesiumMap from 'huweili-cesium/CesiumMap'
+
+function onMapLoad({ map, center }) {
+  console.log('地图已加载', map, center)
+}
+</script>
+
+<style scoped>
+.map-page {
+  width: 100%;
+  height: 100vh;
+}
+</style>
+```
+
+**Vite 宿主项目**需在 `vite.config` 中允许编译该依赖（否则 `.vue` 可能无法处理）：
+
+```js
+export default defineConfig({
+  optimizeDeps: {
+    include: ['huweili-cesium'],
+  },
+})
+```
+
+组件 props：
+
+| prop | 类型 | 默认 | 说明 |
+|------|------|------|------|
+| `mapId` | `string` | `'default'` | 多地图实例 ID，与 `mapStore` 对应 |
+| `options` | `object` | — | 覆盖/合并 `MapConfig` 的配置 |
+
+事件：`@onload`，参数 `{ map, center, mapId, toolbar }`（`map` 为 Cesium `Viewer` 实例；`toolbar` 可在加载后动态增删按钮）。
+
+### 为何不用 Cesium 内置 2D 模式
+
+Viewer 固定为 `SCENE3D`，业务上的「2D」是 **正交相机 + 俯视**（`basis.js` / `cameraInteraction.js`），不切换 `SCENE2D` / `COLUMBUS_VIEW`。简要优点：
+
+- **2D/3D 切换更顺**：无场景变形（morph），透视与正交互换，缩放与锚点更易对齐（含工具栏切换、RTK 跟飞）。
+- **渲染一致**：无人机、轨迹、围栏等与 3D 同一套规则，少踩 2D 投影下的显示差异。
+- **交互可控**：2D 可锁定俯视、自定义滚轮缩放（正交宽度），避免与内置 2D 控制器行为不一致。
+- **语义清晰**：`mapStore` 的 `2D`/`3D` 表示业务视角，不与 Cesium `SceneMode` 枚举混用。
+
+配置里 `scene.sceneMode: '2D'` 表示初始化俯视正交，而非启用 Cesium 平面地图模式。
+
+### 各项目自定义工具栏
+
+**方式 1：组件 props（推荐）**
+
+```vue
+<CesiumMap
+  map-id="default"
+  :show-default-toolbar="true"
+  :extra-toolbar-buttons="myExtraButtons"
+/>
+```
+
+```js
+import { useEventBus } from 'huweili-cesium/utils/useEventBus'
+
+const { emit } = useEventBus()
+
+const myExtraButtons = [
+  {
+    title: '导出',
+    text: '导',
+    onClick: () => emit('exportMap', {}),
+  },
+]
+```
+
+完全不用内置默认按钮、自己定义一整组：
+
+```vue
+<CesiumMap :toolbar-buttons="myToolbarButtons" />
+```
+
+内置默认按钮里的图标路径使用宿主项目的 `import.meta.env.BASE_URL`（如 `/images/new/tj.svg`），请在宿主 `public/images/new/` 放置对应资源；业务按钮（如「机型统计」）通过 `useEventBus` 发事件，宿主需自行 `on('toggleBarChartControl', ...)` 监听。
+
+## 可选业务钩子
+
+若需光电引导、轨迹列表等业务能力，在应用启动时注入：
+
+```js
+import { setDroneMapProvider, setOptGuideHandler } from 'huweili-cesium/config/hooks'
+
+setDroneMapProvider(() => myDroneMap)
+setOptGuideHandler((payload) => api.toOptGuide(payload))
+```
+
+## 发布到 npm（维护者）
+
+```bash
+cd huweili-cesium
+npm login
+npm publish
+```
+
+首次发布前可在本地打包预览：
+
+```bash
+npm pack
+# 会生成 huweili-cesium-1.0.0.tgz，解压检查是否包含全部 js
+```
+
+## 从 tzr 源目录同步更新
+
+```bash
+cd huweili-cesium
+npm run sync
+# 同步后需重新修复 @/ 别名为包内相对路径（见 scripts）
+```
+
+## 地图与自定义工具栏
+
+地图组件来自 npm 包 **`huweili-cesium`**，工具栏按钮在业务侧配置，不写在 `mapConfig.js` 里。
+
+### 1. 前置配置（`constants.js` / `mapConfig.js`）
+
+`index.html` 中已按顺序引入：
+
+```html
+<script src="/config/constants.js"></script>
+<script src="/config/mapConfig.js"></script>
+```
+
+| 文件 | 作用 | 与地图组件的关系 |
+|------|------|------------------|
+| `public/config/constants.js` | `window.MapInstanceIds` 定义多地图 ID（如 `HOME: 'home-main-map'`） | `:map-id` 须与之一致，工具栏回调里的 `mapId` 也要传同一个值 |
+| `public/config/mapConfig.js` | `window.MapConfig`（中心点、2D/3D、底图列表、是否显示 Cesium 自带控件等） | 控制地图初始化；`control.homeButton: false` 时由自定义工具栏替代 |
+
+在页面中引用常量（从 `runtimeConfig` 导入）：
+
+```js
+import { MapInstanceIds } from '@/config/runtimeConfig'
+
+const HOME_MAP_ID = MapInstanceIds?.HOME || 'home-main-map'
+```
+
+### 2. 页面引用 `CesiumMap`（首页示例）
+
+`src/views/home/indexnew.vue`：
+
+```vue
+<template>
+  <CesiumMap
+    :map-id="HOME_MAP_ID"
+    :toolbar-buttons="getHomeToolbarButtons({ mapId: HOME_MAP_ID })"
+    @onload="mapOnLoad"
+  />
+</template>
+
+<script setup>
+import CesiumMap from 'huweili-cesium'
+import { MapInstanceIds } from '@/config/runtimeConfig'
+import { getHomeToolbarButtons } from '@/utils/homeToolbarButtons'
+
+const HOME_MAP_ID = MapInstanceIds?.HOME || 'home-main-map'
+</script>
+```
+
+- **`toolbar-buttons`**：传入整组按钮（首页不用包内默认按钮，因此不必再写 `show-default-toolbar`）
+- **`map-id`**：与 `constants.js` 里 `MapInstanceIds.HOME` 保持一致
+
+### 3. 工具栏按钮配置（`src/utils/homeToolbarButtons.js`）
+
+通用按钮（指北针、机型统计、回中心、2D/3D、缩放、底图、全屏）集中在此文件维护。
+
+页面只需追加自己的按钮时，使用 `extra`：
+
+```js
+import { useEventBus } from 'huweili-cesium/utils/useEventBus'
+import { getHomeToolbarButtons } from '@/utils/homeToolbarButtons'
+
+const { emit } = useEventBus()
+
+getHomeToolbarButtons({
+  mapId: HOME_MAP_ID,
+  extra: [
+    {
+      title: '导出',
+      text: '导',
+      onClick: () => emit('exportMap', {}),
+    },
+  ],
+})
+```
+
+按钮项字段说明：
+
+| 字段 | 说明 |
+|------|------|
+| `title` | 悬停提示 |
+| `text` / `iconSrc` | 文字或图标（二选一，图标放 `public/images/new/`） |
+| `isCompass: true` | 指北针专用 |
+| `onClick(viewer, button)` | 点击回调 |
+
+「机型统计」等通过 `useEventBus` 发事件，页面需 `on('toggleBarChartControl', ...)` 监听。
+
+### 4. 其他页面
+
+- 复用首页整套按钮：`getHomeToolbarButtons({ mapId: '你的 mapId' })`
+- 完全自定义：直接传数组给 `:toolbar-buttons="[...]"`
+- 地图加载后动态增删：在 `@onload` 回调里使用返回的 `toolbar.addToolbarButton(...)`
+
+图标资源路径使用 `import.meta.env.BASE_URL`（如 `/jlap/images/new/xxx.svg`），请放在 `public/images/new/`。
+
+## 目录结构
+
+```
+huweili-cesium/
+├── index.js          # npm 主入口（默认导出 CesiumMap + 转发 js 模块）
+├── index.vue         # 地图 Vue 组件
+├── components/       # 组件（如 wsIndicator）
+├── js/               # 全部 JS 模块
+│   ├── basis.js
+│   ├── toolbar/
+│   ├── stores/
+│   ├── utils/
+│   ├── config/
+│   └── api/
+└── package.json
+```
+
+## 包含的文件清单（均在 `js/` 下）
+
+| 文件 | 说明 |
+|------|------|
+| js/basis.js | 地图基础操作 |
+| js/setPoint.js / js/movePoint.js | 点位与移动 |
+| js/setPath.js / js/movePath.js | 路径与轨迹 |
+| js/groundLink.js | 地面连接线 |
+| js/hemisphere.js | 半球区域 |
+| js/geometry.js | 几何图形 |
+| js/drawFence.js / js/drawFenceNew.js | 电子围栏 |
+| js/cardPool.js / js/labelDiv.js | 信息牌 |
+| js/clickHandler.js | 点击交互 |
+| js/tileProviders.js | 底图瓦片 |
+| js/customToolbarButtons.js | 工具栏 |
+| js/toolbar/* | 指南针、底图切换、缩放、全屏 |
+| js/droneRipple.js / js/qrCodeGenerator.js | 涟漪、二维码 |
+
+另含 `js/stores/mapStore.js`、`js/utils/*`、`js/config/*`、`js/api/*` 等运行依赖。

package/index.vue

@@ -18,7 +18,7 @@ import { processMapConfigColors } from './js/tileProviders.js'
 import { applyImageryLayers, resolveOnlineBasemap } from './js/utils/mapImagery.js'
 import { createCustomToolbarButtons } from './js/customToolbarButtons.js'
 const { merge } = objectUtils()
-const { mouseController, setInitialCameraView, syncCameraInteractionMode, waitForMapReady } = basicConfig()
+const { mouseController, setInitialCameraView, syncCameraInteractionMode } = basicConfig()
 const {
   addToolbarButton,
   addToolbarButtons,
@@ -239,13 +239,10 @@ const initCesium = async () => {
       })
     }
 
-    const readyMap = await waitForMapReady(props.mapId)
-    if (readyMap) {
-      mouseController(readyMap, props.mapId, {
-        onRightClick: (position) => emit('rightClick', position),
-        onLeftClick: (event) => emit('leftClick', event),
-      }) // 初始化鼠标控制器
-    }
+    mouseController(map, props.mapId, {
+      onRightClick: (position) => emit('rightClick', position),
+      onLeftClick: (event) => emit('leftClick', event),
+    }) // 初始化鼠标控制器
 
     mapStore.setMapInfo(
       'center',