CzmlDataSource

参数可以是 CZML 数组、JSON 字符串或资源地址。传数组时完全离线， 适合把演示数据内联在页面里。

文档结构

数组的第一个元素固定是 document，声明版本与时钟； 之后每个元素是一个 packet，对应一个随时间变化的对象。

[
  {
    "id": "document",
    "version": "1.0",
    "clock": {
      "interval": "2026-10-27T00:00:00Z/2026-10-27T00:02:00Z",
      "currentTime": "2026-10-27T00:00:00Z",
      "multiplier": 10,
      "range": "LOOP_STOP",
      "step": "SYSTEM_CLOCK_MULTIPLIER"
    }
  },
  {
    "id": "uav-01",
    "name": "无人机 01",
    "availability": "2026-10-27T00:00:00Z/2026-10-27T00:02:00Z",
    "position": {
      "epoch": "2026-10-27T00:00:00Z",
      "cartographicDegrees": [
        0,   116.39, 39.90, 800,
        60,  116.42, 39.93, 900,
        120, 116.45, 39.96, 700
      ]
    },
    "point": {
      "pixelSize": 10,
      "color": { "rgba": [77, 155, 255, 255] }
    },
    "path": {
      "resolution": 2,
      "width": 2,
      "material": { "polyline": { "color": { "rgba": [77, 155, 255, 180] } } }
    }
  }
]

时间与坐标的写法

加载并同步时钟

Cesium.CzmlDataSource.load(czml).then(function (ds) {
  viewer.dataSources.add(ds);

  viewer.clock.startTime = Cesium.JulianDate.fromIso8601('2026-10-27T00:00:00Z');
  viewer.clock.stopTime = Cesium.JulianDate.fromIso8601('2026-10-27T00:02:00Z');
  viewer.clock.currentTime = Cesium.JulianDate.fromIso8601('2026-10-27T00:00:00Z');
  viewer.clock.multiplier = 10;
  viewer.clock.shouldAnimate = true;
  viewer.clock.clockRange = Cesium.ClockRange.LOOP_STOP;

  viewer.trackedEntity = ds.entities.getById('uav-01');
});

CZML 里的 clock 不会自动接管场景时钟。必须把 viewer.clock 的四项（起点、终点、当前时间、倍速）设成一致， 否则物体停在第一帧或者直接不可见。

常用成员

可用但容易忽略的属性

CZML 的 packet 支持几乎所有实体的图形属性，字段名就是 Entity 的图形名： label、billboard、model、polyline、 polygon、ellipse、wall。 需要让属性随时间变化时，把数值换成 { "number": [秒, 值, ...] } 这类采样结构，而不是写死一个常量。

"label": {
  "text": "无人机 01",
  "font": "12px sans-serif",
  "pixelOffset": { "cartesian2": [0, -22] },
  "fillColor": { "rgba": [255, 255, 255, 255] }
},
"billboard": {
  "image": "/icons/uav.png",
  "scale": { "number": [0, 0.4, 120, 0.8] }
}

三个常见问题

1. 动画不动

按顺序检查：clock.shouldAnimate 是否为 true、Viewer 是否开了 requestRenderMode、packet 的 availability 是否覆盖当前时间。 三者任一不满足，画面都静止。

2. 物体跳变而不是平滑移动

position 的采样点之间默认按线性插值。需要平滑曲线时， 用 interpolationAlgorithm: "LAGRANGE" 与 interpolationDegree: 5，代价是采样点必须足够密。

3. 与 GeoJSON 混合使用

CZML 与 GeoJSON 可以同时加到 viewer.dataSources， 但两者各自带 clock 时以后添加的为准。多份时间化数据要统一时， 在添加完成后再显式设一次 viewer.clock 的四项。