首页 / Cesium / API 文档

Property

先看结论

所有可随时间变化的值的统一接口。Entity 的每个图形属性（position、color、show …）都是 Property，读取要带时间参数。

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

Cesium.Property — 接口，无公开构造函数

写实体时可以直接赋字面量（position: Cesium.Cartesian3.fromDegrees(...)）， Cesium 会自动包成 ConstantProperty。需要随时间变化时再显式换实现类。

接口成员

成员	类型	说明
`isConstant`	boolean	值是否与时间无关；true 时渲染器只求值一次
`definitionChanged`	Event	属性定义变化时触发，用于刷新缓存
`getValue(time, result)`	any	取 `time` 时刻的值，传入 `result` 可复用对象
`equals(other)`	boolean	两个属性是否等价

实现类

类	适用场景
`ConstantProperty`	不随时间变化的固定值
`SampledProperty`	离散采样点，按时间插值，轨迹回放常用
`CallbackProperty`	每帧现算，位置依赖外部状态时用
`TimeIntervalCollectionProperty`	按时间段给不同值
`ReferenceProperty`	引用另一个实体的属性，做联动
`CompositeProperty`	把多个属性按时间段拼起来

示例

var entity = viewer.entities.add({
  position: Cesium.Cartesian3.fromDegrees(116.391, 39.907, 100),
  point: { pixelSize: 8, color: Cesium.Color.CYAN }
});

// 直接读属性拿到的是 Property 对象，不是坐标
var prop = entity.position;

// 按当前时钟取值
var now = viewer.clock.currentTime;
var pos = prop.getValue(now);
console.log(pos instanceof Cesium.Cartesian3, prop.isConstant);

// 属性被替换时收到通知
prop.definitionChanged.addEventListener(function (p, name, value) {
  console.log('属性变化', name);
});

// 运行时把固定位置换成随时间变化的采样位置
entity.position = new Cesium.SampledProperty(Cesium.Cartesian3);

注意事项

不要直接读 entity.position.x，Property 上没有坐标分量；必须先 getValue(time)。
isConstant 由实现类决定，自己写的自定义属性要实现该接口才能被渲染优化。
把新的 Property 赋给实体属性时会触发 definitionChanged，监听该事件比轮询更可靠。
getValue 的 result 参数会复用同一个对象，循环里多次调用不要共用 result，否则值会被覆盖。

引用本文

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