Cesium快速入门29：CMZL数据格式加载

前面我们用"谷歌系"KML 过了一把瘾，今天换 Cesium 亲儿子 ------CZML 。

它同样是"地理 + 时间"的 JSON 套餐，却天生带动态属性：位置、颜色、尺寸都能按时间轴自动插值，一行代码就能让车子跑、让盒子变色、让路线自己长出来。

一、CZML 是什么？

纯 JSON，数组套对象，人类可读；
专为 Cesium 设计，一条时间轴管所有属性；
支持 Entity 全套元素：点、线、面、盒子、模型、广告牌......
后端按格式吐数据，前端 load 完直接渲染，省时省力。

官方指南（老版但够用）：
https://github.com/AnalyticalGraphicsInc/czml-writer/wiki/CZML-Guide

二、最小可运行例子：蓝色大盒子

数组第一项永远是"文档头"，告诉 Cesium 版本号；第二项开始才是真正的"实体"。

复制代码

const czml = [
  {
    id: "document",
    name: "box",
    version: "1.0",          // 必须，告诉 Cesium 这是 CZML 1.0
  },
  {
    id: "shape1",            // 实体 ID，可随意取
    name: "Blue box",
    position: {
      cartographicDegrees: [-114.0, 40.0, 300000.0], // 经度° 纬度° 高度 m
    },
    box: {
      dimensions: {
        cartesian: [400000.0, 300000.0, 500000.0],   // 长 宽 高，单位米
      },
      material: {
        solidColor: {
          color: {
            rgba: [0, 0, 255, 255],                  // 纯蓝不透明
          },
        },
      },
    },
  },
];

一眼就能对上：曾经用代码 viewer.entities.add({ box: {...} }) 写的东西，现在全搬到 JSON 里而已。

三、加载套路：与 GeoJSON/KML 一模一样

复制代码

/* 1. 加载 CZML（返回 Promise） */
const czmlDataSource = Cesium.CzmlDataSource.load(czml);

/* 2. 飞过去看一眼 */
viewer.zoomTo(czmlDataSource);

/* 3. 真正添加到场景 */
czmlDataSource.then((dataSource) => {
  viewer.dataSources.add(dataSource);
});

运行后，一个巨型蓝盒子立刻出现在美国上空------恭喜你，第一条动态数据链已接通！

四、动态属性：时间轴才是灵魂

CZML 最大的杀手锏是"随时间变化"。

把任何字段换成 { "number": [...], "epoch": "2025-12-20T00:00:00Z", "unit": "meter" } 的数组格式，Cesium 就会自动插值。

例子：盒子边飞边变色、路径自己生长、广告牌尺寸呼吸......全部交给后端写数组，前端零代码。

五、想写 shader？Fabric 同样适用

CZML 的 material 也能内嵌 Fabric：

复制代码

"material": {
  "fabric": {
    "type": "CustomMaterial",
    "uniforms": { "uTime": 0 },
    "source": "czm_material czm_getMaterial(...) { ... }"
  }
}

后端把 GLSL 源码当字符串写进去，前端一样能吃到自定义特效。

小结

CZML = JSON + 时间轴，专为 Cesium 打造。
文档头 + 实体数组，格式与 Entity 配置一一对应。
加载套路同 GeoJSON/KML，复用零成本。
后端改数字就能让物体动起来，是"数据驱动"可视化利器。