Label

参数

font 的正确写法

font 走的是 canvas 的字体字符串，格式必须是「字号 字体族」， 中间可以插字重。下面第一行有效，第二行无效（缺字号），第三行看起来对， 但部分环境缺少该字重会回退成默认字体：

font: '14px "Microsoft YaHei", sans-serif'      // 有效
font: '"Microsoft YaHei", 14px sans-serif'      // 无效，整条被忽略
font: '600 14px "PingFang SC", sans-serif'      // 依赖系统字体

中文字体名称里有空格时必须加引号。字体族最后一定要跟一个通用族 （sans-serif），否则在没装该字体的机器上会退化成浏览器默认字体。

带描边的城市名

viewer.entities.add({
  position: Cesium.Cartesian3.fromDegrees(116.391263, 39.907359),
  label: {
    text: '北京',
    font: '500 13px "Microsoft YaHei", sans-serif',
    style: Cesium.LabelStyle.FILL_AND_OUTLINE,
    fillColor: Cesium.Color.WHITE,
    outlineColor: Cesium.Color.fromCssColorString('#0e1116'),
    outlineWidth: 3,
    pixelOffset: new Cesium.Cartesian2(0, -22),
    disableDepthTestDistance: Number.POSITIVE_INFINITY
  }
});

深色底图上不要用纯黑描边配纯白字，对比过强会让文字边缘发虚。 描边色取一层比背景稍亮的颜色更自然。

贴地标注

让文字跟随地形起伏需要同时设置两处：

viewer.scene.globe.depthTestAgainstTerrain = true;

label: {
  text: '垭口',
  heightReference: Cesium.HeightReference.CLAMP_TO_GROUND,
  disableDepthTestDistance: 0
}

CLAMP_TO_GROUND 只改文字的高度，不改水平位置。 disableDepthTestDistance 保持默认 0，地面的山体才能挡住背面的文字。 如果发现远处标注仍然穿过山体，检查是否把它设成了无穷大。

大量标注怎么办

每个 label 都会在纹理图集里占一块位置，上千个之后会出现重建图集导致的卡顿。 三种处理方式：

1. 用 distanceDisplayCondition 让远景不画，通常能砍掉九成。
2. 把静态文字预渲染成 canvas 图标，改用 billboard 显示。
3. 同一位置的多个字段合并成多行文本，一个 label 代替三个。