首页 / Cesium / API 文档

PolylineGeometry

先看结论

底层折线几何。描述一串三维顶点如何连成线，本身不参与绘制，需要 createGeometry 转成 Geometry 后交给 Primitive。

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

new Cesium.PolylineGeometry(options)

参数

参数	默认	说明
`positions`	必填	Cartesian3 数组，少于两个顶点不产生几何
`width`	1.0	像素宽度
`colors`	[Color.WHITE]	Color 数组，长度与 `positions` 对应
`colorsPerVertex`	false	为 true 时逐顶点取色，否则整条线用 `colors[0]`
`arcType`	ArcType.GEODESIC	GEODESIC 大圆 / RHUMB 等角航线 / NONE 直线
`granularity`	按弧长自动	相邻采样点的经度间隔，弧度；越小越贴合大圆、顶点越多
`vertexFormat`	VertexFormat.DEFAULT	决定输出几何携带哪些属性

成员与方法

成员	读写	说明
`positions`	只读	原始顶点数组
`width`	可读写	线宽像素值
`colors`	可读写	顶点颜色数组
`colorsPerVertex`	可读写	是否逐顶点着色
`arcType`	可读写	连接方式
`granularity`	可读写	采样间隔
`vertexFormat`	可读写	顶点属性布局
`PolylineGeometry.createGeometry(geometry)`	静态方法	返回 `Geometry`，失败时返回 undefined

配合 Primitive 使用

var positions = Cesium.Cartesian3.fromDegreesArrayHeights([
  116.39, 39.91, 120,
  117.20, 39.13, 260,
  118.10, 39.35, 180
]);

var geometry = Cesium.PolylineGeometry.createGeometry(
  new Cesium.PolylineGeometry({
    positions: positions,
    width: 2,
    colors: [
      Cesium.Color.RED,
      Cesium.Color.YELLOW,
      Cesium.Color.LIME
    ],
    colorsPerVertex: true
  })
);

viewer.scene.primitives.add(new Cesium.Primitive({
  geometryInstances: new Cesium.GeometryInstance({ geometry: geometry }),
  appearance: new Cesium.PolylineColorAppearance()
}));

两种外观的取舍

PolylineColorAppearance 读取几何里的 color 属性，逐顶点插值，适合渐变线；PerInstanceColorAppearance 只认 GeometryInstance 上的 color 属性，一条线只有一种颜色，但可以配合 geometryInstances 数组一次提交多条线。

宽度与颜色长度的陷阱

colors 长度必须与 positions 相同，否则 createGeometry 直接返回 undefined 且没有警告。 colorsPerVertex: false 时只取第一个颜色，后面的值被忽略，但仍然必须提供完整长度。

WebGL 的原生线宽限制同样作用于几何方式：多数桌面环境把 width 压到 1 像素。需要真实宽度改用 PolylineVolumeGeometry 或 CorridorGeometry。

顶点多不等于画得顺。arcType 为 GEODESIC 时，每个采样点都会进入缓冲区。长航线把 granularity 调大能显著减少顶点，视觉上几乎看不出差别。

引用本文

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