首页 / Cesium / API 文档

Polyline

先看结论

三维折线。顶点是一串 Cartesian3，线宽在多数平台被限制为 1 像素，这是 WebGL 的硬限制而不是配置问题。

最后验证 2026-11-03 · CesiumJS 1.121 · 更新 2026-10-27 · 引用本文

entity.polyline = new Cesium.PolylineGraphics({ positions, width, material, ... })

参数

参数	默认	说明
`positions`	—	Cartesian3 数组，可用 `fromDegreesArray` 生成
`width`	1	像素宽度，受 WebGL 限制通常最大 1
`material`	WHITE	颜色或材质对象
`clampToGround`	false	贴地绘制，跟随地形起伏
`arcType`	GEODESIC	GEODESIC 大圆 / RHUMB 等角航线 / NONE 空间直线
`granularity`	—	弧线采样间隔，弧度
`depthFailMaterial`	—	被地形或模型遮挡时使用的材质
`zIndex`	0	贴地线的绘制顺序
`distanceDisplayCondition`	—	按距离控制显隐

三个关键参数

arcType

GEODESIC 是默认值，两点之间沿地球表面的大圆走。做航线、国界这类地理要素时必须用它。NONE 会让线在三维空间中直接连过去，长距离时会切进地球内部。短距离的两者看不出差别，跨省、跨国之后就非常明显。

clampToGround

开启后线会贴着地形画，代价是每帧都要把线投影到地形上，数据量大时明显变慢。贴地线在地形加载完成之前会短暂出现在错误高度，地形加载完才归位。

depthFailMaterial

普通线被山体挡住就整段消失。给 depthFailMaterial 指定另一种材质（比如半透明的同色），被遮挡的部分会以淡色继续显示，视觉上能看出「路在山后面」。

var route = viewer.entities.add({
  polyline: {
    positions: Cesium.Cartesian3.fromDegreesArray([
      116.391263, 39.907359,
      121.473701, 31.230416,
      113.264385, 23.129112
    ]),
    width: 2,
    arcType: Cesium.ArcType.GEODESIC,
    material: new Cesium.PolylineGlowMaterialProperty({
      color: Cesium.Color.fromCssColorString('#ffb13d').withAlpha(0.9),
      glowPower: 0.2,
      taperPower: 0.6
    }),
    depthFailMaterial: new Cesium.ColorMaterialProperty(
      Cesium.Color.fromCssColorString('#ffb13d').withAlpha(0.2)
    )
  }
});

常用材质

材质	效果	主要参数
`Cesium.Color`	纯色实线	直接赋颜色对象即可
`PolylineGlowMaterialProperty`	发光带，中亮边暗	`glowPower`、`taperPower`
`PolylineDashMaterialProperty`	虚线	`dashLength`、`dashPattern`
`PolylineOutlineMaterialProperty`	带描边的线	`color`、`outlineColor`、`outlineWidth`
`PolylineArrowMaterialProperty`	末端的箭头	`color`
`PolylineTrailMaterialProperty`	拖尾流光	社区扩展，核心包不含，需要自定义

粗线的替代方案

WebGL 只在部分平台支持大于 1 的线宽，靠 width 做不出道路那种粗线。三种可行做法：

Cesium.PolylineVolumeGraphics：沿路径挤出方管，能做出真实宽度并接受光照。
Cesium.CorridorGraphics：沿中心线生成带状面，适合道路、河流。
用 PolylineGlowMaterialProperty 提高对比度，视觉上「看起来更粗」。

线不显示先查顶点数。positions 少于两个点不会绘制；数组里混入 undefined 会导致整条线消失，而控制台不报错。

引用本文

经纬志（2026）。《Polyline》。https://www.jingweizhi.com/cesium/api/polyline.html（访问日期 2026-11-03）。