cesium 中的 KmlDataSource

KmlDataSource

简介

KmlDataSource是 Cesium 中用于解析 KML / KMZ 文件的数据源类，它实现了DataSource接口。KML（Keyhole Markup Language 2.2）是 Google Earth 常用的地理标注格式，Cesium 解析后会把每一个要素转成Entity（线、点、面、图标等），统一放到entities集合中管理。

它同时支持：

• kml/ovkml：纯文本的 KML 文件；
• kmz/ovkmz：zip 压缩包形式的 KML，Cesium 内部会自动解压，包内的图片、图标等相对资源也能一并解析。

基本使用

加载文件（URL）

最简单的方式是直接传一个文件地址，load返回一个 Promise：

viewer.dataSources.add(Cesium.KmlDataSource.load("../../SampleData/facilities.kmz",{camera:viewer.scene.camera,canvas:viewer.scene.canvas,}));

三种数据形态（重点）

load的第一个参数支持三种类型，它们的含义完全不同：

// 1. 字符串（URL）awaitCesium.KmlDataSource.load("/data/xxx.ovkml");// 2. Blob（KMZ / ovkmz）constblob=awaitfetch("/data/xxx.ovkmz").then((r)=>r.blob());constds=awaitCesium.KmlDataSource.load(blob,{sourceUri:"/data/xxx.ovkmz",});// 3. XML Document（ovkml）consttext=await(awaitfetch("/data/xxx.ovkml")).text();constdoc=newDOMParser().parseFromString(text,"application/xml");constds=awaitCesium.KmlDataSource.load(doc,{sourceUri:"/data/xxx.ovkml",});

注意：把 KML 文本字符串直接传给load，会被当成 URL 请求，导致加载失败甚至抛RuntimeError。

加载选项 LoadOptions

• sourceUri：解析 KML 内相对路径（图片、图标等）的基准 URL；
• clampToGround：几何要素（线、面）是否贴地，默认false；
• screenOverlayContainer：屏幕叠加层（ScreenOverlay）挂载的容器；
• camera/canvas：KML 的 NetworkLink 等特性需要相机参数时传入viewer.scene.camera和viewer.scene.canvas。

挂载到地图

viewer.dataSources.add(ds);// 显示图层viewer.dataSources.remove(ds,false);// 移除显示，false 表示不销毁，可重新加回viewer.dataSources.contains(ds);// 判断图层是否已挂载

解析结果

解析完成后，数据源上可以拿到所有要素和相关信息：

• ds.entities/ds.entities.values：要素集合，每个要素是一个Entity；
• entity.name：Placemark 的名称（如 YL_58）；
• entity.polyline/entity.polygon/entity.point/entity.billboard：对应的图形对象；
• entity.parent：<MultiGeometry>拆出来的多个 entity 共享同一个 parent（即原 Placemark），可用于把同一条线的高亮整组处理；
• entity.kml：KmlFeatureData，包含 author、link 等 KML 元数据。

数据源本身还提供事件：

• errorEvent：解析过程中出错时触发；
• loadingEvent：开始/结束加载时触发；
• changedEvent：底层数据变化时触发；
• unsupportedNodeEvent：遇到不支持的 KML 节点时触发。

修改样式

Cesium 里所有样式字段都是 Property，修改时要用属性类包装：

constnow=Cesium.JulianDate.now();// 读取当前线宽constwidth=entity.polyline.width?.getValue(now);// 修改线宽和颜色entity.polyline.width=newCesium.ConstantProperty(8);entity.polyline.material=newCesium.ColorMaterialProperty(Cesium.Color.fromCssColorString("#ffd400"));// 面的填充 / 描边entity.polygon.material=newCesium.ColorMaterialProperty(Cesium.Color.fromCssColorString("#ffd400").withAlpha(0.45));entity.polygon.outline=newCesium.ConstantProperty(true);entity.polygon.outlineColor=newCesium.ConstantProperty(Cesium.Color.fromCssColorString("#ffd400"));

常见问题

1. 传字符串报错 / RuntimeError：字符串被当成 URL，而不是文件内容；改为传 Blob 或 Document。
2. 一条长线显示成一段一段：源数据里<MultiGeometry>把折线拆成了多段<LineString>，每段是一个 entity；可以用entity.parent分组，把同一 Placemark 的段一起高亮。
3. KMZ 内的图标不显示：要把整个 KMZ Blob 交给 Cesium 解析，而不是手动解压只取doc.kml文本，否则包内相对资源无法解析。

参考资料:

• KmlDataSource

• KmlDataSource