首页 / Cesium / API 文档

Entity

先看结论

面向业务的对象：一个实体同时承载位置、图形和属性表，是 Viewer 默认渲染与拾取的单位。

最后验证 2026-11-03 · CesiumJS 1.121 · 更新 2026-10-27 · 引用本文

new Cesium.Entity(options)

构造参数

参数	类型	说明
`id`	string	唯一标识，省略时自动生成 GUID。`getById` 依赖它
`name`	string	显示名，infoBox 与图例默认读它
`show`	boolean	是否渲染，默认 true
`position`	PositionProperty	位置，图形属性的参照点
`orientation`	Property	姿态四元数，模型与椭球用
`viewFrom`	Cartesian3	`zoomTo` 时相机相对实体的偏移
`parent`	Entity	父子关系，父实体隐藏时子实体跟着隐藏
`properties`	PropertyBag	业务字段，拾取后可读
`billboard`	BillboardGraphics	图标
`box` / `cylinder` / `ellipsoid`	对应 Graphics	规则几何体
`corridor` / `polylineVolume`	对应 Graphics	沿线生成的带状体
`ellipse` / `rectangle` / `polygon`	对应 Graphics	面状要素
`label`	LabelGraphics	文字
`model`	ModelGraphics	glTF 模型
`path`	PathGraphics	随时间绘制的轨迹线
`point`	PointGraphics	像素点
`polyline`	PolylineGraphics	折线
`wall`	WallGraphics	竖直墙面或围栏
`tileset`	Cesium3DTilesetGraphics	把整个瓦片集挂到实体上

图形属性只写需要的

一个实体可以同时挂 label、point、polyline，三者共用同一个 position。没写的图形属性不会创建对象，也几乎不占开销，所以「一个点位实体挂点和标签」比创建两个实体更省。

viewer.entities.add({
  id: 'sensor-07',
  name: '传感器 07',
  position: Cesium.Cartesian3.fromDegrees(116.391263, 39.907359, 80),
  point: { pixelSize: 9, color: Cesium.Color.fromCssColorString('#4d9bff') },
  label: {
    text: '传感器 07',
    font: '500 12px sans-serif',
    pixelOffset: new Cesium.Cartesian2(0, -20),
    disableDepthTestDistance: Number.POSITIVE_INFINITY
  },
  properties: { online: true, type: 'PM2.5' }
});

Property 体系

给参数传普通值时，Cesium 会自动包成 ConstantProperty；传 JSON 对象时会包成对应的 XxxGraphics。需要随时间变化时必须显式构造：

类型	行为	典型用途
`ConstantProperty`	恒定值	静态数据
`SampledProperty`	按时间点线性或 Hermite 插值	轨迹、遥测数据回放
`TimeIntervalCollectionProperty`	按时间段切换固定值	状态分档
`CallbackProperty`	每帧调用一次回调取值	闪烁、扫描、跟随计算
`PositionPropertyArray`	返回坐标数组	动态折线顶点
`ColorMaterialProperty`	面的材质	配合 alpha 做半透明面

// 动态折线：顶点每帧重算
entity.polyline.positions = new Cesium.CallbackProperty(function () {
  return Cesium.Cartesian3.fromDegreesArray([116.39, 39.90, 116.45, 39.95]);
}, false);

常用成员与方法

成员	说明
`entity.position`	PositionProperty，读值要传时间：`getValue(time)`
`entity.isShowing`	自身与所有父级都可见时才为 true
`entity.addProperty(name, value)`	运行时追加业务字段
`entity.propertyNames`	所有业务字段名
`entity.merge(source)`	把另一个实体的非空属性合并进来
`entity.billboard.show = false`	单独关掉某一种图形

拾取之后

scene.pick 返回的对象里，picked.id 是实体实例。读业务字段要用 getValue：

var picked = viewer.scene.pick(movement.position);
if (Cesium.defined(picked) && picked.id instanceof Cesium.Entity) {
  var e = picked.id;
  var online = e.properties.online.getValue(viewer.clock.currentTime);
  console.log(e.id, e.name, online);
}

直接写 e.properties.online 拿到的是 Property 对象，不是字段值。这是 infoBox 里最常见的取值错误。

删除与隐藏不同。entity.show = false 保留对象、保留属性、保留内存占用，适合频繁切换显隐的图层。viewer.entities.remove(entity) 才真正释放引用，滚动更新的实时数据要按时移除，否则内存会持续增长。

数量控制

Viewer 的实体集合每次变更都会触发事件并重建绘制批次。批量加载时用 viewer.entities.suspendEvents() 与 resumeEvents() 包住循环，能让几千个实体的加载时间从数秒降到数百毫秒。超过一万个对象时，考虑改用 Primitive 或直接贴 3D Tiles。

引用本文

经纬志（2026）。《Entity》。https://www.jingweizhi.com/cesium/api/entity.html（访问日期 2026-11-03）。