首页 / Cesium / API 文档

DataSourceCollection

先看结论

数据源的容器。CZML、GeoJSON、KML 加载后都成为这里的一项，统一控制显隐、顺序与销毁。

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

new Cesium.DataSourceCollection()

构造函数不接受参数。项目里通常直接用 viewer.dataSources，它是 Viewer 建好的同一个实例。

构造参数

参数	类型	说明
无	—	空集合；数据源通过 `add` 加入

常用成员

成员	类型	说明
`length`	number	当前数据源数量
`dataSourceAdded`	Event	新增后触发，回调参数为 `(collection, dataSource)`
`dataSourceRemoved`	Event	移除后触发
`dataSourceMoved`	Event	调用 `raise` 或重排后触发

常用方法

方法	返回	说明
`add(dataSource)`	Promise<DataSource>	可传数据源，也可传返回数据源的 Promise
`remove(dataSource, destroy)`	boolean	`destroy` 为 true 时同时释放资源
`removeAll(destroy)`	Array	清空，返回被移除的数据源
`contains(dataSource)`	boolean	是否在集合里
`get(index)`	DataSource	按下标取
`indexOf(dataSource)`	number	下标，不存在返回 -1
`getByName(name)`	DataSource \| undefined	按 `name` 查找，重名时返回第一个

示例

// add 接受 Promise，加载完成前就先注册进集合
var geojson = viewer.dataSources.add(
  Cesium.GeoJsonDataSource.load('/data/districts.geojson', {
    clampToGround: true
  })
);

geojson.then(function (ds) {
  console.log('要素数', ds.entities.values.length);
  ds.show = false;
});

// 三秒后移除并销毁
setTimeout(function () {
  var ds = viewer.dataSources.getByName('districts')[0];
  if (Cesium.defined(ds)) {
    viewer.dataSources.remove(ds, true);
  }
}, 3000);

注意事项

add 返回的一定是 Promise，即使传入的是已建好的数据源；直接同步使用会拿到 Promise 而不是对象。
同名数据源会互相覆盖查找结果，getByName 只返回第一个，业务上建议自己维护 id 映射。
remove 不传 destroy 时资源仍在，反复加载同一个 KML 会累积内存。
集合只负责管理，不负责渲染顺序；显示层级由各自 entity 与场景深度决定。

引用本文

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