首页 / Cesium / API 文档

CustomDataSource

先看结论

自建的数据源，本质是一个带名字和时钟的 EntityCollection。用来把不同业务图层分开，各自显隐、各自销毁。

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

new Cesium.CustomDataSource(name)

构造参数

参数	类型	默认	说明
`name`	string	undefined	数据源名称，供 `getByName` 查找

常用成员

成员	类型	说明
`entities`	EntityCollection	实体集合，`add` / `remove` 都在这里
`name`	string	名称，可改
`clock`	DataSourceClock	时间范围，默认全时段
`show`	boolean	整体显隐，默认 true
`isLoading`	boolean	是否正在加载；自建数据源通常为 false
`changedEvent`	Event	内容变化时触发
`loadingEvent` / `errorEvent`	Event	加载状态与错误事件

常用方法

方法	说明
`destroy()`	销毁内部实体集合
`isDestroyed()`	是否已销毁

示例

// 把巡检点单独放一个数据源，方便整体开关
var inspection = new Cesium.CustomDataSource('巡检点位');
viewer.dataSources.add(inspection);

[['A', 116.391, 39.907], ['B', 116.407, 39.916]].forEach(function (p) {
  inspection.entities.add({
    id: p[0],
    position: Cesium.Cartesian3.fromDegrees(p[1], p[2], 10),
    point: {
      pixelSize: 10,
      color: Cesium.Color.ORANGE,
      outlineColor: Cesium.Color.WHITE,
      outlineWidth: 2
    },
    label: {
      text: p[0],
      font: '14px sans-serif',
      pixelOffset: new Cesium.Cartesian2(0, -18),
      style: Cesium.LabelStyle.FILL_AND_OUTLINE,
      outlineWidth: 2,
      verticalOrigin: Cesium.VerticalOrigin.BOTTOM
    }
  });
});

// 勾选框里整体开关
inspection.show = false;

注意事项

自建数据源的 clock 默认为全时段，不会自动参与时间轴动画；需要时间驱动时手动设置起止时间。
show = false 只影响渲染，实体仍在集合里，再次打开不会重新创建。
从 viewer.dataSources 移除时要传 destroy 为 true，否则实体集合留在内存里。
同一个实体 id 重复添加时，后加的会覆盖先加的，可用这一特性做数据更新。

引用本文

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