首页 / Cesium / API 文档

KmlDataSource

先看结论

解析 KML 与 KMZ，把地标、路径、多边形、地面叠加转成 Entity。 ArcGIS Earth、Google Earth 导出的成果常走这条路。

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

new Cesium.KmlDataSource({ camera, canvas, ellipsoid, credit })

构造参数

参数	类型	默认	说明
`camera`	Camera	—	KML 含屏幕叠加或 viewRefresh 时需要，一般传 `viewer.camera`
`canvas`	HTMLCanvasElement	—	KML 含 GroundOverlay 时使用，一般传 `viewer.canvas`
`ellipsoid`	Ellipsoid	Ellipsoid.WGS84	经纬度换算基准
`credit`	Credit \| string	—	数据版权信息

加载参数

参数	类型	默认	说明
`clampToGround`	boolean	false	贴地绘制，开启后点和线随地形起伏
`sourceUri`	string	—	相对图标与网络链接的基准地址
`screenOverlayContainer`	Element \| string	—	屏幕叠加的 DOM 容器，不传时叠加不显示

常用成员与方法

成员 / 方法	说明
`entities`	解析出的 EntityCollection，逐条改样式从这里取
`name`	数据源名，默认取自 KML 的 Document name
`clock`	KML 时间跨度映射成的 Clock，有 TimeSpan 时不是默认值
`show`	整体显隐，比逐条改 entity 便宜
`KmlDataSource.load(data, options)`	静态方法，返回 `Promise<KmlDataSource>`
`load(data, options)`	实例方法，往已有数据源里追加内容
`changedEvent` / `errorEvent`	内容变更与加载失败的事件
`destroy()`	释放贴图与实体

示例

var kml = new Cesium.KmlDataSource({
  camera: viewer.camera,
  canvas: viewer.canvas
});

viewer.dataSources.add(
  kml.load('/data/city.kml', {
    clampToGround: true,
    screenOverlayContainer: 'map'
  })
).then(function (ds) {
  ds.entities.values.forEach(function (entity) {
    if (Cesium.defined(entity.billboard)) {
      entity.billboard.scale = 0.8;
    }
  });
});

// 显示状态整体切换
viewer.dataSources.dataSourceAdded.addEventListener(function (coll, ds) {
  console.log('已加载', ds.name);
});

注意事项

GroundOverlay 依赖构造时传入的 canvas，漏传会直接跳过该叠加层且不报错。
屏幕叠加不是 WebGL 内容，必须给 screenOverlayContainer，否则只有数据没有图面元素。
KMZ 是压缩包，需要浏览器支持解压；跨域加载时服务端要允许读取二进制并暴露 Content-Type。
KML 里的相对图标路径以 sourceUri 为基准，不传时按当前页面地址推导，容易 404。

引用本文

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