Cesium 中 Entity Polyline 的完整属性指南

属性类别	属性名	类型	默认值	描述
基本配置	`show`	`boolean` - `Property`	`true`	控制折线的显示与隐藏。
	`positions`	`Cartesian3[]` - `PositionProperty`	（必填）	定义折线顶点坐标的数组。
样式设置	`material`	`Color` - `MaterialProperty`	`Color.WHITE`	折线的材质，可以是简单颜色或复杂材质（如发光、尾迹）。
	`width`	`number` - `Property`	`1.0`	折线的宽度（以像素为单位）。
	`clampToGround`	`boolean` - `Property`	`false`	是否将折线贴附到地形表面（注意：与`height`和`extrudedHeight`可能互斥）。
几何形状	`height`	`number` - `Property`	`0.0`	折线距离椭球表面的高度（米）。
	`extrudedHeight`	`number` - `Property`		设置折线的挤压高度，与 `height` 配合可形成"墙"的效果。
	`granularity`	`number` - `Property`	`Cesium.Math.RADIANS_PER_DEGREE`	计算折线线段时各点之间的角度步长（弧度），影响曲线平滑度。
高级效果	`arcType`	`Cesium.ArcType` - `Property`	`ArcType.GEODESIC`	折线类型，可选测地线（`GEODESIC`，通常最短的曲线）或罗盘航线（`RHUMB`，恒向线）。58
	`shadows`	`Cesium.ShadowMode` - `Property`	`ShadowMode.DISABLED`	折线是否接收或投射阴影。
	`depthFailMaterial`	`Color` - `MaterialProperty`		当折线被地形等遮挡时显示的材质。

js 复制代码

// 创建 Viewer 实例
const viewer = new Cesium.Viewer('cesiumContainer');

// 添加一条折线 Entity
const redLine = viewer.entities.add({
  name: 'A simple red line',
  polyline: {
    positions: Cesium.Cartesian3.fromDegreesArray([
      -75.0, 35.0, // 起点经度，起点纬度
      -125.0, 35.0, // 第二点经度，第二点纬度
      -125.0, 39.0, // 第三点经度，第三点纬度
      -75.0, 39.0  // 终点经度，终点纬度
    ]),
    width: 5, // 线宽
    material: Cesium.Color.RED, // 线颜色
    clampToGround: false // 不贴地
  }
});

// 飞行到折线
viewer.zoomTo(viewer.entities);

1.基本配置 (Basic Configuration)

show: 控制折线可见性。设置为 false 时，折线隐藏但仍在场景中。
positions: 定义折线路径的点数组。通常使用 Cesium.Cartesian3.fromDegreesArray 或 Cesium.Cartesian3.fromDegreesArrayHeights 从经纬度转换。

js 复制代码

// 使用 fromDegreesArray 转换经纬度坐标
const positions = Cesium.Cartesian3.fromDegreesArray([
  -75.0, 35.0,
  -125.0, 35.0,
  -125.0, 39.0,
  -75.0, 39.0
]);

2.样式设置 (Styling)

material: 定义折线外观。除了纯色，Cesium 提供了多种有趣的材质：
- Cesium.PolylineGlowMaterialProperty: 发光效果。
- Cesium.PolylineOutlineMaterialProperty: 外轮廓线。
- Cesium.PolylineDashMaterialProperty: 虚线效果。
- Cesium.PolylineArrowMaterialProperty: 箭头效果。
- Cesium.PolylineTrailMaterialProperty: 尾迹动画效果。
width: 像素宽度。
clampToGround: 设为 true 可将折线贴附到地形表面（注意可能需要特定地形支持）。

js 复制代码

// 发光材质示例 :cite[3]
material: new Cesium.PolylineGlowMaterialProperty({
    glowPower: 0.2, // 发光强度
    color: Cesium.Color.YELLOW // 线条颜色
})

// 尾迹动画材质示例 :cite[7]
material: new Cesium.PolylineTrailMaterialProperty({
    color: new Cesium.Color.fromCssColorString("rgba(70,130,180, 1.0)"), // 颜色
    trailLength: 0.3, // 尾迹长度比例
    period: 3.0 // 动画周期（秒）
})

3.几何与高度控制 (Geometry & Height)

height: 相对于椭球面的高度（米）。
extrudedHeight: 若设置，则从 height 到 extrudedHeight 挤压形成垂直墙面。
granularity: 影响非直线（GEODESIC 或 RHUMB）路径计算的采样精度，值越小越平滑但性能开销可能增大。
arcType: 定义点与点之间的连接方式。
- Cesium.ArcType.GEODESIC: 测地线（大圆航线），最短路径。
- Cesium.ArcType.RHUMB: 恒向线（等角航线），恒定方位角。
- Cesium.ArcType.NONE: 简单的直线连接（不考虑地球曲率）。

4.高级特效与控制 (Advanced Effects & Controls)

shadows: 控制阴影模式（DISABLED, ENABLED, CAST_ONLY, RECEIVE_ONLY）。
depthFailMaterial: 当折线因深度测试失败（如被地形遮挡）时显示此材质，可用于实现"钻地"效果。
distanceDisplayCondition: 根据与相机的距离控制显示与否，可用于优化性能。

js 复制代码

distanceDisplayCondition: new Cesium.DistanceDisplayCondition(1000.0, 10000.0) // 在1000米到10000米范围内显示

classificationType: 当折线贴地或与3D Tiles交互时使用，决定折线是绘制于地形之上（TERRAIN）、3D Tiles之上（CESIUM_3D_TILE）还是两者皆可（BOTH）。
zIndex: 当多条折线贴地时，控制它们的绘制顺序

常见问题（FAQ）

折线为什么不贴地？
- 检查 clampToGround 是否设为 true。
- 确保地形提供商支持三角化功能（如Cesium World Terrain）。
- 注意 height 和 extrudedHeight 属性可能与贴地互斥，贴地时通常需确保它们未设置或为0。
如何绘制虚线或发光线？
- 使用 Cesium.PolylineDashMaterialProperty 或 Cesium.PolylineGlowMaterialProperty 等特定材质。3
如何让折线动起来？
- 使用 PolylineTrailMaterialProperty 可实现尾迹动画。
- 使用 SampledProperty 动态更新 positions 可实现路径动画。
折线被地形或3D Tiles模型遮挡怎么办？
- 调整 height 或 extrudedHeight 使其抬高。
- 或使用 depthFailMaterial 为被遮挡部分提供不同的视觉效果。
如何处理大量折线的性能问题？
- 对于静态折线，考虑使用 Primitive API 而非 Entity API。2
- 使用 distanceDisplayCondition 优化可见范围。