首页 / Cesium / API 文档

PrimitiveCollection

先看结论

图元容器。把多个 Primitive 归到一组，统一显隐、统一销毁，也能像数组一样按下标读取。

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

new Cesium.PrimitiveCollection(options)

构造参数

参数	默认	说明
`destroyPrimitives`	true	销毁集合时是否一并销毁内部图元
`show`	true	整组是否显示

属性

属性	说明
`length`	只读，内部图元数量
`show`	整组显隐，false 时不渲染，子图元的 show 不受影响
`destroyPrimitives`	销毁时机与销毁策略

方法

方法	返回	说明
`add(primitive)`	传入的图元	追加到末尾
`remove(primitive)`	Boolean	移除成功返回 true；`destroyPrimitives` 为 true 时会销毁它
`removeAll()`	—	清空，是否销毁由 `destroyPrimitives` 决定
`contains(primitive)`	Boolean	是否包含指定图元
`get(index)`	Primitive	按下标读取
`destroy()`	—	销毁集合本身
`isDestroyed()`	Boolean	是否已销毁

示例

var group = new Cesium.PrimitiveCollection({
  destroyPrimitives: true,
  show: true
});

group.add(new Cesium.Primitive({
  geometryInstances: instancesA,
  appearance: new Cesium.PerInstanceColorAppearance({ flat: true })
}));

group.add(new Cesium.Primitive({
  geometryInstances: instancesB,
  appearance: new Cesium.PerInstanceColorAppearance({ flat: true })
}));

viewer.scene.primitives.add(group);

// 整组开关，不必逐个遍历
group.show = false;
console.log(group.length);

与 scene.primitives 的关系

viewer.scene.primitives 本身就是一个 PrimitiveCollection，所以可以嵌套：把一组图元装进子集合，再把子集合加入场景。嵌套后 show 会沿层级传递，父集合隐藏时子集合整体不渲染。

remove 的副作用

destroyPrimitives 默认为 true，remove 会直接销毁被移除的图元。如果打算把同一个图元移到另一个集合继续使用，创建集合时把它设为 false，否则再添加时会因为资源已释放而报错。

先销毁再清空，避免显存堆积。频繁重建图元的场景里，每次 removeAll() 后手动调用 destroy() 之外的清理逻辑没有必要，但一定要确认 destroyPrimitives 没有被设为 false。

引用本文

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