Appearance
实体管理
提供作战实体建模、批量管理、事件通知等能力，支持模型/标签/公告板/轨迹/传感器等组件
概述
实体管理模块由三部分组成：
CombatEntity— 作战实体类，封装 Cesium Entity，以数据接口管理模型/标签等组件EntityManager— 实体管理器，管理多个 CombatEntity 实例，提供增删查改和事件通知viewerEntityMixin— Viewer 插件，通过viewer.extend()注入，挂载便捷方法
快速开始
typescript
import { CesiumViewer, viewerEntityMixin } from '@space-air/gis-cesium'
const airGis = new CesiumViewer('container')
const viewer = airGis.viewer
// 加载实体管理插件
viewer.extend(viewerEntityMixin)
// 创建作战实体
const entity = viewer.createEntity({
name: 'F-22 猛禽',
entityType: 'fighter',
position: { x: -2350000, y: 4650000, z: 3660000 },
model: { url: '/models/f22.glb', scale: 1 },
label: { text: 'F-22', color: '#00ff00', font: '14px sans-serif' },
})通过 EntityManager 直接使用
typescript
import { CesiumViewer, EntityManager } from '@space-air/gis-cesium'
const airGis = new CesiumViewer('container')
const manager = new EntityManager({ viewer: airGis.viewer })
const entity = manager.create({
name: '预警机',
entityType: 'fighter',
position: { x: -2350000, y: 4650000, z: 3660000 },
})CombatEntity 详解
实体类型
| 枚举值 | 说明 |
|---|---|
'fighter' | 战斗机 |
'ship' | 舰船 |
'vehicle' | 地面车辆 |
'missile' | 导弹 |
'satellite' | 卫星 |
'radar' | 雷达站 |
'base' | 基地 |
'other' | 其他 |
组件接口
模型组件 CombatModelOptions
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
url | string | - | 模型文件 URL（.glb/.gltf） |
scale | number | - | 模型缩放比例 |
标签组件 CombatLabelOptions
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
text | string | - | 标签文字 |
color | string | - | 文字颜色（CSS 颜色值） |
font | string | - | 字体（如 '14px sans-serif'） |
公告板组件 CombatBillboardOptions
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
url | string | - | 图标图片 URL |
scale | number | - | 缩放比例 |
color | string | - | 着色颜色 |
轨迹组件 CombatTrajectoryOptions
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
color | string | - | 轨迹颜色 |
width | number | - | 轨迹线宽 |
传感器组件 CombatSensorOptions
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
type | 'cone' | 'pyramid' | 'hemisphere' | 'custom' | - | 传感器形状 |
radius | number | - | 传感器范围半径（米） |
color | string | - | 传感器颜色 |
朝向组件 CombatOrientationOptions
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
heading | number | - | 偏航角（度） |
pitch | number | - | 俯仰角（度） |
roll | number | - | 翻滚角（度） |
CombatEntity 属性与方法
| 名称 | 类型 | 描述 |
|---|---|---|
id | string (readonly) | 实体唯一标识 |
name | string (readonly) | 实体名称 |
entityType | CombatEntityType | undefined | 实体类型 |
entity | Cesium.Entity (readonly) | 底层 Cesium Entity |
position | {x,y,z} | undefined | 笛卡尔坐标 |
orientation | CombatOrientationOptions | undefined | 实体朝向 |
sync() | void | 手动同步所有组件 |
destroy() | void | 销毁实体 |
show() / hide() | void | 显示/隐藏 |
setShow(show) | void | 设置显隐 |
EntityManager API
查询
| 方法 | 返回 | 描述 |
|---|---|---|
get(id) | CombatEntity | undefined | 按 ID 获取 |
getAll() | CombatEntity[] | 获取所有 |
getByType(type) | CombatEntity[] | 按类型过滤 |
getByName(name) | CombatEntity[] | 按名称搜索 |
count() | number | 实体数量 |
操作
| 方法 | 返回 | 描述 |
|---|---|---|
create(data) | CombatEntity | 创建并添加 |
add(entity) | void | 添加已有实体 |
remove(id) | boolean | 移除指定实体 |
removeAll() | void | 移除所有 |
show(id) | void | 显示实体 |
hide(id) | void | 隐藏实体 |
toggle(id) | void | 切换显隐 |
update(id, changes) | void | 部分更新 |
clone(id, newId?) | CombatEntity | undefined | 克隆实体 |
createBatch(list) | CombatEntity[] | 批量创建 |
destroy() | void | 销毁所有并清理 |
事件系统
typescript
const off = manager.on((event) => {
console.log(event.type, event.entity.name)
})
// 取消监听
off()事件类型：'add' | 'remove' | 'show' | 'hide' | 'update'
viewerEntityMixin 插件
typescript
viewer.extend(viewerEntityMixin)
// 1. 实体管理器实例
const manager = viewer.entityManager
// 2. 快速创建实体
const entity = viewer.createEntity({ name: '目标', ... })使用案例
案例1：创建多种类型的实体
typescript
viewer.extend(viewerEntityMixin)
// 战斗机（带模型和标签）
const fighter = viewer.createEntity({
name: '歼-20',
entityType: 'fighter',
position: { x: -2350000, y: 4650000, z: 3660000 },
model: { url: '/models/j20.glb', scale: 1 },
label: { text: '歼-20', color: '#ff4444' },
})
// 卫星（带标签和轨迹）
const satellite = viewer.createEntity({
name: '遥感卫星',
entityType: 'satellite',
position: { x: -7000000, y: 0, z: 0 },
label: { text: '卫星-01', color: '#44aaff' },
trajectory: { color: '#44aaff', width: 2 },
})案例2：实体搜索与批量操作
typescript
const fighters = manager.getByType('fighter')
manager.getAll().forEach(e => e.hide())
manager.getByType('satellite').forEach(e => e.show())
console.log('实体总数:', manager.count())案例3：事件监听与响应
typescript
const off = manager.on(({ type, entity, changes }) => {
switch (type) {
case 'add': console.log(`新增: ${entity.name}`); break
case 'remove': console.log(`移除: ${entity.name}`); break
case 'update': console.log(`更新: ${entity.name}`, changes); break
}
})注意事项
- 位置使用
{x, y, z}笛卡尔坐标格式 - 模型 URL 建议放在
public/目录下 destroy()会从 viewer 的 entity collection 中移除实体，移除后不可复用- 事件监听器发生错误不会影响其他监听器
EntityManager.update()采用浅合并方式更新组件