huweili-cesium

基于 Cesium 的地图工具库。所有 JS 模块 位于包内 js/ 目录（含 toolbar、stores、utils、config、api 子目录）；根目录保留 index.js（npm 主入口）与 index.vue（地图组件）。

安装

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 模块
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 地图组件（开箱即用）

<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 可能无法处理）：

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（推荐）

<CesiumMap
  map-id="default"
  :show-default-toolbar="true"
  :extra-toolbar-buttons="myExtraButtons"
/>

import { useEventBus } from 'huweili-cesium/utils/useEventBus'

const { emit } = useEventBus()

const myExtraButtons = [
  {
    title: '导出',
    text: '导',
    onClick: () => emit('exportMap', {}),
  },
]

完全不用内置默认按钮、自己定义一整组：

<CesiumMap :toolbar-buttons="myToolbarButtons" />

内置默认按钮里的图标路径使用宿主项目的 import.meta.env.BASE_URL（如 /images/new/tj.svg），请在宿主 public/images/new/ 放置对应资源；业务按钮（如「机型统计」）通过 useEventBus 发事件，宿主需自行 on('toggleBarChartControl', ...) 监听。

可选业务钩子

若需光电引导、轨迹列表等业务能力，在应用启动时注入：

import { setDroneMapProvider, setOptGuideHandler } from 'huweili-cesium/config/hooks'

setDroneMapProvider(() => myDroneMap)
setOptGuideHandler((payload) => api.toOptGuide(payload))

发布到 npm（维护者）

cd huweili-cesium
npm login
npm publish

首次发布前可在本地打包预览：

npm pack
# 会生成 huweili-cesium-1.0.0.tgz，解压检查是否包含全部 js

从 tzr 源目录同步更新

cd huweili-cesium
npm run sync
# 同步后需重新修复 @/ 别名为包内相对路径（见 scripts）

地图与自定义工具栏

地图组件来自 npm 包 huweili-cesium，工具栏按钮在业务侧配置，不写在 mapConfig.js 里。

1. 前置配置（constants.js / mapConfig.js）

index.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 导入）：

import { MapInstanceIds } from '@/config/runtimeConfig'

const HOME_MAP_ID = MapInstanceIds?.HOME || 'home-main-map'

2. 页面引用 CesiumMap（首页示例）

src/views/home/indexnew.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：

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/* 等运行依赖。