Cesium 三维地球开发：一站式弹窗、坐标转换与可视化扩展（持续进化中）

Cesium SDK 全面使用指南

本文适用于希望在 CesiumJS 上快速实现弹窗、位置计算、UI 控制、坐标转换等功能的开发者。

1. 项目简介

Cesium SDK 是一个基于 CesiumJS 的轻量级扩展库，专为地理信息可视化、三维地球应用场景设计。它极大简化了弹窗、实体屏幕位置、UI 控制、坐标系转换等常见需求的开发流程，支持中国主流坐标系，兼容 Vue 组件弹窗。

目前功能还在持续扩展中，后续会有其他功能迭代。

可视化方向：聚合，电子围栏，雷达，等

功能方向：弹框优化，可播放的运动轨迹动画等

计算方向：根据线返回扇形朝向角度等

2. 环境准备

2.1 依赖要求

CesiumJS（建议 1.90+）
浏览器支持 ES6
（可选）Vue 2.x 用于弹窗自定义组件

2.2 目录结构建议

python 复制代码

project/
├── dist/                  # 构建后 Cesium SDK 文件
│   └── cesium-sdk.min.js
├── examples/              # 示例代码
├── docs/                  # 文档与截图
│   └── screenshots/
├── index.html             # 入口页面
└── ...

3. 快速上手

3.1 引入依赖

xml 复制代码

<script src="https://unpkg.com/cesium/Build/Cesium/Cesium.js"></script>
<link href="https://unpkg.com/cesium/Build/Cesium/Widgets/widgets.css" rel="stylesheet">
<script src="dist/cesium-sdk.min.js"></script>

3.2 初始化与最小示例

csharp 复制代码

const viewer = new Cesium.Viewer('cesiumContainer');
CesiumSDK.init(Cesium, viewer, {
  watermark: true,        // 显示水印
  hideDefaultUI: false    // 是否隐藏默认UI
});

4. 核心功能概览

🎯 实体屏幕位置与可见性计算
🎨 弹窗系统（属性表/HTML/Vue 组件）
🎛️ UI 控制
🌍 坐标转换
🧩 扩展功能（安全飞行、标记、GeoJSON、天地图、带线实体、工具提示等）

5. 基础用法详解

5.1 实体添加与事件绑定

php 复制代码

const entity = viewer.entities.add({
  id: 'my-entity',
  name: '测试点',
  position: Cesium.Cartesian3.fromDegrees(116.4, 39.9),
  point: { pixelSize: 10, color: Cesium.Color.RED },
  properties: { type: 'POI', customData: 123 }
});

viewer.screenSpaceEventHandler.setInputAction((event) => {
  const picked = viewer.scene.pick(event.position);
  if (picked && picked.id) {
    CesiumSDK.showPopup(picked.id, {
      title: picked.id.name,
      content: '类型: ' + picked.id.properties.type.getValue()
    });
  }
}, Cesium.ScreenSpaceEventType.LEFT_CLICK);

5.2 弹窗系统

5.2.1 属性表弹窗

ini 复制代码

CesiumSDK.showPopup(entity);

5.2.2 纯 HTML 弹窗

php 复制代码

CesiumSDK.showPopup(entity, {
  title: '自定义标题',
  content: '<b>自定义内容</b><br>支持 HTML',
  width: 300,
  height: 200
});

5.2.3 Vue 组件弹窗

xml 复制代码

<script src="https://unpkg.com/vue@2/dist/vue.js"></script>

css 复制代码

const MyPopup = {
  template: `<div><h3>{{ title }}</h3><p>{{ description }}</p></div>`,
  props: ['title', 'description']
};
CesiumSDK.setVueComponent(MyPopup);
CesiumSDK.showPopup(entity, {
  title: 'Vue 组件弹窗',
  data: { title: '标题', description: '描述' }
});

5.2.4 数据传递与事件回调

css 复制代码

CesiumSDK.showPopup(entity, {
  title: '带回调',
  data: { foo: 123 },
  onClose: () => alert('弹窗关闭')
});

5.2.5 关闭弹窗

ini 复制代码

CesiumSDK.closePopup();

5.2.6 弹窗样式自定义

覆盖 .cesium-sdk-popup CSS 类自定义样式

5.3 UI 控制

5.3.1 初始化隐藏所有 UI

csharp 复制代码

CesiumSDK.init(Cesium, viewer, { hideDefaultUI: true });

5.3.2 运行时切换 UI

ini 复制代码

CesiumSDK.hideDefaultUI();
CesiumSDK.showDefaultUI();

5.3.3 单独隐藏/显示某个控件

dart 复制代码

viewer.uiControl.hide('homeButton');
viewer.uiControl.show('timeline');

5.3.4 获取 UI 状态

ini 复制代码

const isHidden = viewer.uiControl.isHidden('timeline');

5.4 坐标转换

5.4.1 单点转换

ini 复制代码

const [gcjLng, gcjLat] = viewer.extensions.coordinateTransform.wgs84_to_gcj02(116.4, 39.9);

5.4.2 批量转换

ini 复制代码

const arr = [[116.4,39.9],[121.47,31.23]];
const gcjArr = viewer.extensions.coordinateTransform.batchTransform(arr, 'WGS84', 'GCJ02');

5.4.3 实体坐标转换

arduino 复制代码

viewer.extensions.coordinateTransform.transformEntity(entity, 'WGS84', 'GCJ02');

5.4.4 地图服务对接建议

GCJ02 适用于高德、腾讯、阿里等国内地图
BD09 适用于百度地图
CGCS2000 适用于国测局数据

6. 进阶用法

6.1 Vue 组件弹窗进阶

组件 props 自动绑定 data，支持响应式
可在组件内通过 $parent.entity 访问当前实体
生命周期、数据响应、与实体交互

kotlin 复制代码

methods: {
  focusEntity() {
    this.$parent.viewer.flyTo(this.$parent.entity);
  }
}
// 关闭弹窗
this.$parent.close();

6.2 扩展功能 API

6.2.1 安全飞行定位

ini 复制代码

viewer.extensions.safeFlyTo([lng, lat, height], duration = 3);

6.2.2 添加安全标记点

ini 复制代码

viewer.extensions.addSecureMarker([lng, lat], '标记名称');

6.2.3 添加 GeoJSON 图层

ini 复制代码

viewer.extensions.addGeoJSONLayer(geojsonObject, styleOptions);

6.2.4 添加天地图影像图层

php 复制代码

viewer.extensions.addTianDiTuLayer({ type: 'img', token: 'xxx' });

6.2.5 添加带线实体

lua 复制代码

viewer.extensions.addEntityWithLine([[lng1, lat1], [lng2, lat2]], options);

ini 复制代码

viewer.extensions.tooltip.show([x, y], '提示内容');
viewer.extensions.tooltip.hide();

6.2.7 实体位置计算 positionCalculator

ini 复制代码

viewer.extensions.positionCalculator.calculateScreenPosition(entity);
viewer.extensions.positionCalculator.calculateWorldPosition(entity);
viewer.extensions.positionCalculator.calculateBoundingBox(entity);
viewer.extensions.positionCalculator.isEntityVisible(entity);
viewer.extensions.positionCalculator.getDistanceToCamera(entity);

6.2.8 坐标转换 coordinateTransform

scss 复制代码

viewer.extensions.coordinateTransform.transform(lng, lat, fromSystem, toSystem);
viewer.extensions.coordinateTransform.batchTransform(coordinates, fromSystem, toSystem);
viewer.extensions.coordinateTransform.transformEntity(entity, fromSystem, toSystem);
// 直接转换方法、工具方法同上

11. API 参考

11.1 CesiumSDK 主对象 API

CesiumSDK.init

csharp 复制代码

CesiumSDK.init(Cesium, viewer, options)

初始化 SDK 并扩展 Viewer 实例。
参数：
- Cesium：Cesium 全局对象
- viewer：Cesium.Viewer 实例
- options (object)：配置项
  - watermark (boolean, 默认 true)：是否显示水印
  - hideDefaultUI (boolean, 默认 true)：是否隐藏默认 UI
返回值：扩展后的 Cesium.Viewer 实例

CesiumSDK.showPopup

scss 复制代码

CesiumSDK.showPopup(entity, options)

显示弹窗。
参数：
- entity：Cesium 实体对象
- options (object)：弹窗配置
  - title (string)：弹窗标题
  - content (string)：HTML 内容
  - width (number)：宽度
  - height (number)：高度
  - data (object)：传递给 Vue 组件的数据
  - onClose (function)：关闭回调
返回值：无

CesiumSDK.closePopup

scss 复制代码

CesiumSDK.closePopup()

关闭当前弹窗。

CesiumSDK.calculateScreenPosition

scss 复制代码

CesiumSDK.calculateScreenPosition(entity)

计算实体在屏幕上的像素坐标、可见性、距离相机等。
返回值：{ x, y, visible, distanceToCamera } 或 null

CesiumSDK.setVueComponent

scss 复制代码

CesiumSDK.setVueComponent(VueComponent)

设置全局弹窗 Vue 组件。
参数：VueComponent（Vue 2.x 组件对象）

CesiumSDK.hideDefaultUI / showDefaultUI

scss 复制代码

CesiumSDK.hideDefaultUI(viewer)
CesiumSDK.showDefaultUI(viewer)

隐藏/显示所有默认 UI 元素。
参数：viewer（Cesium.Viewer 实例）

11.2 viewer.extensions 扩展 API

实体操作

viewer.extensions.safeFlyTo(coords, duration)
- 平滑飞行到指定坐标
- coords: [lng, lat, height]
- duration: 动画时长（秒，默认3）
viewer.extensions.addSecureMarker(coords, label)
- 添加安全标记点
- coords: [lng, lat]
- label: 标记文本
viewer.extensions.addGeoJSONLayer(geojson, style)
- 加载 GeoJSON 图层
- geojson: GeoJSON 对象
- style: 样式对象（可选）
viewer.extensions.addTianDiTuLayer(options)
- 添加天地图图层
- options: { type, token }
viewer.extensions.addEntityWithLine(coordsArr, options)
- 添加带线实体
- coordsArr: [[lng, lat], ...]
- options: 样式、属性等

弹窗与工具提示

viewer.extensions.tooltip.show([x, y], message)
viewer.extensions.tooltip.hide()

位置计算

viewer.extensions.positionCalculator.calculateScreenPosition(entity)
viewer.extensions.positionCalculator.calculateWorldPosition(entity)
viewer.extensions.positionCalculator.calculateBoundingBox(entity)
viewer.extensions.positionCalculator.isEntityVisible(entity)
viewer.extensions.positionCalculator.getDistanceToCamera(entity)

UI 控制

viewer.uiControl.hide(controlName)
viewer.uiControl.show(controlName)
viewer.uiControl.isHidden(controlName)
- controlName 支持：homeButton、sceneModePicker、baseLayerPicker、geocoder、navigationHelpButton、animation、timeline、fullscreenButton、vrButton、projectionPicker、infoBox、selectionIndicator、logo

坐标转换

viewer.extensions.coordinateTransform.transform(lng, lat, fromSystem, toSystem)
viewer.extensions.coordinateTransform.batchTransform(coordinates, fromSystem, toSystem)
viewer.extensions.coordinateTransform.transformEntity(entity, fromSystem, toSystem)
viewer.extensions.coordinateTransform.wgs84_to_gcj02(lng, lat) 等直接转换方法
viewer.extensions.coordinateTransform.isInChina(lng, lat)
viewer.extensions.coordinateTransform.getCoordinateInfo(lng, lat)
viewer.extensions.coordinateTransform.COORDINATE_SYSTEMS（常量枚举）

11.3 坐标系类型与常量

perl 复制代码

viewer.extensions.coordinateTransform.COORDINATE_SYSTEMS
// {
//   WGS84: 'WGS84',
//   GCJ02: 'GCJ02',
//   BD09: 'BD09',
//   CGCS2000: 'CGCS2000'
// }

11.4 典型用法示例

添加安全标记点

ini 复制代码

viewer.extensions.addSecureMarker([116.4, 39.9], '北京');

坐标批量转换

ini 复制代码

const arr = [[116.4,39.9],[121.47,31.23]];
const gcjArr = viewer.extensions.coordinateTransform.batchTransform(arr, 'WGS84', 'GCJ02');

弹窗自定义 Vue 组件

php 复制代码

const MyPopup = { template: '<div>{{ title }}</div>', props: ['title'] };
CesiumSDK.setVueComponent(MyPopup);
CesiumSDK.showPopup(entity, { title: 'Hello', data: { title: '内容' } });

Cesium 三维地球开发：一站式弹窗、坐标转换与可视化扩展（持续进化中）

Cesium SDK 全面使用指南

1. 项目简介

2. 环境准备

2.1 依赖要求

2.2 目录结构建议

3. 快速上手

3.1 引入依赖

3.2 初始化与最小示例

4. 核心功能概览

5. 基础用法详解

5.1 实体添加与事件绑定

5.2 弹窗系统

5.2.1 属性表弹窗

5.2.2 纯 HTML 弹窗

5.2.3 Vue 组件弹窗

5.2.4 数据传递与事件回调

5.2.5 关闭弹窗

5.2.6 弹窗样式自定义

5.3 UI 控制

5.3.1 初始化隐藏所有 UI

5.3.2 运行时切换 UI

5.3.3 单独隐藏/显示某个控件

5.3.4 获取 UI 状态

5.4 坐标转换

5.4.1 单点转换

5.4.2 批量转换

5.4.3 实体坐标转换

5.4.4 地图服务对接建议

6. 进阶用法

6.1 Vue 组件弹窗进阶

6.2 扩展功能 API

6.2.1 安全飞行定位

6.2.2 添加安全标记点

6.2.3 添加 GeoJSON 图层

6.2.4 添加天地图影像图层

6.2.5 添加带线实体

6.2.6 工具提示 Tooltip

6.2.7 实体位置计算 positionCalculator

6.2.8 坐标转换 coordinateTransform

11. API 参考

11.1 CesiumSDK 主对象 API

CesiumSDK.init

CesiumSDK.showPopup

CesiumSDK.closePopup

CesiumSDK.calculateScreenPosition

CesiumSDK.setVueComponent

CesiumSDK.hideDefaultUI / showDefaultUI

11.2 viewer.extensions 扩展 API

实体操作

弹窗与工具提示

位置计算

UI 控制

坐标转换

11.3 坐标系类型与常量

11.4 典型用法示例

添加安全标记点

坐标批量转换

弹窗自定义 Vue 组件