快速开始

本文将引导你快速上手 @space-air/gis-cesium，在 Vue 项目中创建第一个三维地球场景。

环境要求

依赖	最低版本	说明
Node.js	18+	推荐使用 LTS 版本
pnpm	8+	推荐使用 pnpm 作为包管理器
Cesium Ion Token	-	使用 Cesium 官方底图/地形时需要 注册获取

安装

安装主包

pnpm add @space-air/gis-cesium

安装 peer 依赖

@space-air/gis-cesium 将 cesium 和 vue 声明为 peer dependency，需要你自行安装：

pnpm add cesium@^1.133.1 vue@^3.5

配置 Cesium Ion Token

在应用入口（如 main.ts）中尽早设置：

import { Ion } from 'cesium'

// 将 YOUR_ION_TOKEN 替换为你在 https://ion.cesium.com 申请的 Token
Ion.defaultAccessToken = 'YOUR_ION_TOKEN'

NOTE

如果仅使用内置的单张底图（默认行为），可以不设置 Ion Token。但使用 Cesium 官方地形、影像服务时必须设置。

基础用法

1. 创建 CesiumViewer

CesiumViewer 是对 Cesium Viewer 的业务封装，接收一个容器元素（或元素 ID）和可选的初始化选项。

import { CesiumViewer } from '@space-air/gis-cesium'

const viewer = new CesiumViewer('cesiumContainer', {
  animation: false,
  timeline: false,
  baseLayerPicker: false,
  fullscreenButton: false,
  geocoder: false,
  homeButton: false,
  sceneModePicker: false,
  navigationHelpButton: false,
})

完成后页面上将显示一个三维地球，默认视角覆盖东亚区域。

2. 安装 Mixin（插件）

包内提供了 12 个 Mixin 函数，它们会向 Cesium Viewer 实例上注入额外的功能方法，例如实体管理、相机控制、网格辅助线等。

import {
  viewerEntityMixin,
  viewerCameraMixin,
  viewerGridMixin,
} from '@space-air/gis-cesium'

// 获取原始 Cesium Viewer 实例
const v = viewer.getViewer()

// 安装 Mixin（扩展 viewer 实例）
viewerEntityMixin(v)
viewerCameraMixin(v)
viewerGridMixin(v)

安装后，v 上便自动获得了 v.createEntity()、v.cameraControl、v.grid 等方法。

TIP

Mixin 的本质是一个以 Cesium.Viewer 实例为入参的函数，通过 Object.defineProperties 在 viewer 上注册新属性与方法。你不需要它们返回任何值，调用即可生效。这种模式可以称为 viewer.extend() 模式。

3. 创建实体

安装 viewerEntityMixin 后，通过 createEntity() 快速创建一个作战实体：

const entity = v.createEntity({
  id: 'sat-001',
  name: '侦察卫星-01',
  entityType: 'Satellite',
  components: [
    {
      id: 'pos-1',
      type: 'PositionComponent',
      lon: 108.94,
      lat: 34.26,
      alt: 400000,
    },
    {
      id: 'lbl-1',
      type: 'LabelComponent',
      text: 'Sat-001',
      color: '#ffd700',
    },
  ],
  modules: [],
})

NOTE

createEntity() 返回的对象包含 entity（Cesium Entity 实例）和 data（原始数据引用），你可以保存并后续操作。

4. 飞行至目标

安装 viewerCameraMixin 后，通过 cameraControl 飞往指定实体或坐标：

// 飞行到刚创建的实体
v.cameraControl.flyToEntity(entity.entity)

// 或直接飞到经纬度坐标
v.cameraControl.flyTo({
  lon: 116.39,
  lat: 39.91,
  height: 0,
  range: 50000,      // 相机距离目标距离（米）
  heading: 0,
  pitch: -45,
  duration: 3,        // 飞行秒数
})

5. 完整示例

以下是一个在 Vue SFC 中使用的最小完整示例：

<template>
  <div id="cesiumContainer" style="width: 100%; height: 100vh;"></div>
</template>

<script setup lang="ts">
import { onMounted } from 'vue'
import { CesiumViewer, viewerEntityMixin, viewerCameraMixin } from '@space-air/gis-cesium'

onMounted(() => {
  // 1. 创建 Viewer
  const viewer = new CesiumViewer('cesiumContainer', {
    animation: false,
    timeline: false,
  })

  // 2. 安装 Mixin
  const v = viewer.getViewer()
  viewerEntityMixin(v)
  viewerCameraMixin(v)

  // 3. 创建实体
  const result = v.createEntity({
    id: 'demo-aircraft',
    name: '预警机',
    entityType: 'Aircraft',
    components: [
      { id: 'pos', type: 'PositionComponent', lon: 120, lat: 30, alt: 8000 },
      { id: 'lbl', type: 'LabelComponent', text: '预警机', color: '#00ff88' },
    ],
    modules: [],
  })

  // 4. 飞往实体
  v.cameraControl.flyToEntity(result.entity)
})
</script>

常用 Mixin 一览

Mixin 函数	Viewer 上注入的能力
viewerEntityMixin	createEntity()、getEntity()、removeEntity()、updateEntity()、clearEntities()
viewerCameraMixin	cameraControl – flyTo()、flyToEntity()、lockView()、unlockView()、captureSnapshot()
viewerGridMixin	grid – 网格辅助线
viewerMaterialMixin	material – 自定义材质管理
viewerAnimationPanelMixin	animationComPress – 动画控制面板
viewerToolMixin	tool – 测量、标绘工具
viewerAxisVectorMixin	axisVector – 坐标轴辅助显示
viewerNodeToTransformMixin	模型节点姿态变换
viewerOffscreenRenderMixin	离屏渲染（后处理 / FBO）

下一步

• Viewer 初始化与生命周期 — 深入了解 CesiumViewer 的构造选项、Clock 管理、Entity CRUD 与销毁生命周期
• 相机控制 — CameraControl 的飞行漫游、视角锁定与快照
• 实体管理 — EntityManager 与 CombatEntity 的完整用法
• 底图与地形 — 运行时切换底图、地形 Provider
• 图层系统 — LayerManager 与 GeoJsonLayer
• 交互事件 — MouseEvents 鼠标拾取与坐标转换
• 绘图工具 — DrawManager 的点/线/多边形绘制
• 特效系统 — 爆炸粒子、探测范围、自定义材质
• 连线管理 — ConnectionManager 实体间连线