cesium-kit

基于 Vue 3 + TypeScript 的 CesiumJS 二次封装库，提供 19 个组合式 Hooks、12 个开箱即用组件、统一的插件扩展机制，让三维地图应用开发像写普通 Vue 应用一样简单。

特性

• Vue 3 组合式 API 优先 — 19 个 Hooks 全部以 useXxx() 形式提供，与 ref / watch 同等顺滑
• 12 个开箱即用组件 — Viewer 容器、图层切换、底图选择、绘制工具条、量算面板、坐标悬浮、弹窗、比例尺、视角预设、时间轴
• 插件机制 — 命令式 definePlugin 与 Setup 风格 defineSetupPlugin 双形态，4 个示例插件可参考
• 天地图优先 — 内置天地图矢量/影像/地形底图与注记层，零配置可用
• 完整 TypeScript 类型 — 全部 API 均有 .d.ts，编辑器内即得智能提示
• 生产可用 — 28 个单元测试覆盖核心能力，pnpm typecheck 零错误，构建产物 gzip 后 < 30 KB

安装

pnpm add cesium-kit cesium vue
# 或
npm install cesium-kit cesium vue

依赖说明：vue 与 cesium 均为 peerDependencies，请确保已安装。

5 分钟上手

<script setup lang="ts">
import { ref, shallowRef } from 'vue'
import * as Cesium from 'cesium'
import { CesiumKit, CesiumViewer, MapToolbar, BaseMapPicker, ScaleBar, CoordInfo } from 'cesium-kit'
import 'cesium-kit/style.css'

// 1. 初始化全局 token（可选，有默认值）
CesiumKit.configure({
  cesiumIonToken: 'your-ion-token',  // 不传则用默认 token
  tiandituKey: 'your-tianditu-key',   // 不传则用默认 key（仅限开发）
})

// 2. 创建 viewer 容器
const viewerRef = ref<HTMLDivElement>()

// 3. 可选：响应式 viewer 实例
const viewer = shallowRef<Cesium.Viewer | null>(null)
</script>

<template>
  <div style="position: relative; width: 100vw; height: 100vh">
    <CesiumViewer ref="viewerRef" :base-map="'tianditu-vec'" />
    <MapToolbar position="top-right" direction="vertical">
      <BaseMapPicker />
    </MapToolbar>
    <MapToolbar position="bottom-left">
      <ScaleBar />
    </MapToolbar>
    <MapToolbar position="bottom-right">
      <CoordInfo />
    </MapToolbar>
  </div>
</template>

运行后即可看到一个完整的三维地图应用，包含：天地图矢量底图、右上角底图切换器、左下角比例尺、右下角实时坐标。

核心概念

1. 容器组件 <CesiumViewer>

cesium-kit 的一切都建立在 Viewer 容器之上。它负责：

• 创建 Cesium.Viewer 实例并托管其生命周期
• 注入响应式 viewer 上下文（useViewerInject()）
• 注册插件注册器，自动应用通过 <UsePlugin :plugins="[]" /> 挂载的插件

<CesiumViewer
  :base-map="'tianditu-vec'"  // tianditu-vec | tianditu-img | tianditu-ter | ion | none
  :terrain="false"             // 是否启用 cesium 世界地形
  :show-default-ui="true"      // Cesium 自带控件
  style="width:100%; height:100%"
  @ready="onViewerReady"
/>

2. 组合式 Hooks（19 个）

所有 Hook 内部都基于响应式 API，无需手动管理事件订阅生命周期。

| 分类 | Hook | 用途 | |---|---|---| | 核心 | useViewer | 独立创建/管理 Viewer 实例 | | | useViewerInject | 在 <CesiumViewer> 子树中获取 viewer 上下文 | | 相机 | useCamera | setView / flyTo / 姿态控制 | | | useFlyTo | 封装常用飞行操作（边界飞行、跟踪目标） | | 数据 | useEntity | 响应式 Entity CRUD（点/线/面/模型/标签） | | | useLayer | 影像图层管理（增删/排序/透明度/显隐） | | | useModel | glTF/GLB 模型加载 | | | use3DTiles | 3D Tiles 加载与样式 | | | useTileMap | 切片地图（XYZ/ArcGIS/WMTS） | | 交互 | useDraw | 交互式绘制（点/线/面/圆/矩形） | | | useMeasure | 量算（距离/面积/高度/方位） | | | useSelection | 实体选择与高亮 | | | useEvent | ScreenSpaceEventHandler 生命周期管理 | | | useCoordinate | 鼠标实时坐标 + 相机姿态 | | | usePopup | 经纬度定位弹窗 | | 场景 | useCluster | 点聚合 | | | useHeatMap | 热力图 | | | useTerrain | 地形（cesium ion / 椭球） | | | usePostProcess | 后期处理（雾、亮度、对比度） | | 时间 | useTimeLine | 时间轴 + 倍速控制 |

示例：动态创建实体

import { useEntity } from 'cesium-kit'

const { add, remove, clear, entities, count } = useEntity()

// 添加一个点
add({
  id: 'beijing',
  type: 'point',
  position: { lng: 116.39, lat: 39.9 },
  style: { color: '#ff0000', pixelSize: 12 },
})

// 添加一条折线
add({
  id: 'bj-sh',
  type: 'polyline',
  positions: [
    [116.39, 39.9],
    [121.47, 31.23],
  ],
  style: { width: 3, material: '#3388ff' },
})

// 删除 / 清空
remove('beijing')
clear()

3. 开箱即用组件（12 个）

| 组件 | 作用 | |---|---| | <CesiumViewer> | Viewer 容器 | | <MapToolbar> | 浮层定位容器（6 个角 + 居中） | | <MapControlButton> | 原子按钮（active/disabled/iconOnly） | | <BaseMapPicker> | 5 种底图下拉选择 | | <LayerSwitcher> | 图层增删/排序/透明度控制 | | <DrawToolbar> | 5 种绘制工具按钮组 | | <MeasurePanel> | 4 种量算类型切换 | | <CoordInfo> | 实时坐标 + 相机姿态悬浮条 | | <Popup> | 经纬度定位信息弹窗 | | <ScaleBar> | 比例尺（自动适配 100px） | | <CameraPreset> | 5 个默认视角 + 自定义 | | <TimeSlider> | 时间轴倍速控制（1×~3600×） | | <UsePlugin> | 声明式插件挂载 |

示例：绘制工具条

<template>
  <CesiumViewer>
    <MapToolbar position="top-left">
      <DrawToolbar />
    </MapToolbar>
  </CesiumViewer>
</template>

4. 插件机制

cesium-kit 提供两种风格的插件 API：

对象式

import { definePlugin, installPlugin } from 'cesium-kit'

const myPlugin = definePlugin({
  name: 'my-plugin',
  install(viewer, { bus }) {
    viewer.scene.globe.enableLighting = true
    bus.on('click:coord', (coord) => console.log(coord))
  },
  uninstall(viewer) {
    viewer.scene.globe.enableLighting = false
  },
})

// 全局注册并立即应用
installPlugin(myPlugin, viewer.value)

Setup 式（类似 Vue 组合式 API）

import { defineSetupPlugin } from 'cesium-kit'
import * as Cesium from 'cesium'

export default defineSetupPlugin(({ viewer, bus }) => {
  const handler = new Cesium.ScreenSpaceEventHandler(viewer.canvas)
  handler.setInputAction(({ position }) => {
    const cartesian = viewer.scene.pickPosition(position)
    if (cartesian) bus.emit('click:coord', cartesian)
  }, Cesium.ScreenSpaceEventType.LEFT_CLICK)

  // 返回 cleanup 自动在卸载时调用
  return () => handler.destroy()
})

声明式挂载（推荐）

<CesiumViewer>
  <UsePlugin :plugins="[debugMonitor, clickCoord, fullscreen]" />
</CesiumViewer>

内置示例插件（cesium-kit/plugins/examples）：

• debugMonitor — 监听 camera.changed 输出调试信息
• clickCoord — LEFT_CLICK → bus.emit('click:coord')
• selectionInfo — selectedEntityChanged → bus.emit('selection:info')
• fullscreen — F11 切换全屏

项目结构

cesium-kit-monorepo/
├── packages/
│   └── cesium-kit/             # 核心库
│       ├── src/
│       │   ├── components/     # 12 个 Vue 组件
│       │   ├── composables/    # 19 个组合式 Hooks
│       │   ├── core/           # 15+ 核心模块（不依赖 Vue）
│       │   ├── plugins/        # 插件机制 + 4 个示例
│       │   ├── utils/          # 工具函数（坐标、事件总线、token）
│       │   ├── constants/      # 常量（provide key、默认配置）
│       │   ├── types/          # 公共类型
│       │   └── styles/         # SCSS（CSS 变量、按钮、工具栏）
│       ├── __tests__/          # 28 个单元测试
│       ├── vite.config.ts
│       └── package.json
├── pnpm-workspace.yaml
└── README.md

设计原则

1. 依赖反转 — core/ 零依赖 Vue，可独立用于纯 JS 项目；composables/ 依赖 Vue 但封装所有生命周期；components/ 只负责 UI 表达。
2. provide/inject 优先 — <CesiumViewer> 注入 viewer 上下文，子组件/Hook 通过 useViewerInject() 拿到，所有操作"水到渠成"。
3. 插件即一等公民 — 4 个示例插件覆盖监听、交互、选择、视图四类典型需求，新功能应优先以插件形态提供。
4. 类型先行 — 严格 TypeScript 模式，所有公开 API 提供完整类型签名。
5. 不重新发明轮子 — cesium-kit 不替代 Cesium 任何 API，而是 Vue 风格的薄封装。

文档

• API 参考 — 19 Hooks + 12 组件 + 插件的完整签名
• 架构设计 — 分层模型、依赖关系、关键设计决策
• 插件开发指南 — 如何编写一个生产级插件
• 迁移指南 — 从原生 Cesium 迁移到 cesium-kit
• 常见问题 — 已知问题与解决方案
• 示例合集 — 47 个可直接运行的示例

开发

# 安装依赖
pnpm install

# 类型检查
pnpm typecheck

# 运行测试
pnpm test

# 构建
pnpm build

# 启动 demo（开发态）
pnpm dev

路线图

• [x] M1 — Monorepo 与核心结构
• [x] M2 — 15+ 核心模块（不依赖 Vue）
• [x] M3 — 19 个组合式 Hooks
• [x] M4 — 12 个组件 + 插件机制
• [x] M5 — 文档 + 47 个示例
• [ ] M6 — 发布到 npm

许可证

MIT