首页 / Cesium / API 文档

Polygon

先看结论

面状要素：行政区、作业区、覆盖范围。默认贴在地形表面，也可以给定高度或拉伸成体块。

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

entity.polygon = new Cesium.PolygonGraphics({ hierarchy, height, material, ... })

参数

参数	默认	说明
`hierarchy`	—	外环顶点，或 `PolygonHierarchy`（含孔洞）
`height`	0	面的高度，米；配合 `perPositionHeight: false` 使用
`heightReference`	NONE	`CLAMP_TO_GROUND` 让它跟随地形
`extrudedHeight`	—	拉伸到该高度，形成体块；不设则不拉伸
`perPositionHeight`	false	true 时用每个顶点自带的高度，忽略 `height`
`material`	WHITE	颜色或材质，建议带 alpha
`fill`	true	false 时只画边不填充
`outline`	false	是否描边；宽度不可控
`outlineColor`	BLACK	描边颜色
`outlineWidth`	1	多数平台不生效，原因见下文
`stRotation`	0	贴图旋转，用图片纹理时才有意义
`classificationType`	BOTH	贴地时影响地形还是 3D Tiles
`zIndex`	0	多个贴地面重叠时的绘制顺序
`shadows`	DISABLED	拉伸体块投影设置

三种高度模式

贴地

不写 height，或者写 heightReference: CLAMP_TO_GROUND。多边形会投影到地形表面，起伏的山地上也贴着走。大范围多边形贴地要走 GroundPrimitive，三角剖分的开销随顶点数增加，几千个顶点就会明显变慢。

平面

给定 height，整个面在同一个海拔上，山体会把面切成两半。这是「悬浮的规划红线」的常见写法，需要配合半透明材质。

拉伸体

height: 0 加 extrudedHeight: 120，得到一个高 120 米的柱体。建筑轮廓、管控空域都用这种画法。拉伸体受光照影响，需要 scene.globe.enableLighting = true 才有明暗差别。

viewer.entities.add({
  polygon: {
    hierarchy: Cesium.Cartesian3.fromDegreesArray([
      116.30, 39.86,
      116.48, 39.86,
      116.48, 39.98,
      116.30, 39.98
    ]),
    height: 0,
    extrudedHeight: 300,
    material: Cesium.Color.fromCssColorString('#4d9bff').withAlpha(0.35),
    outline: true,
    outlineColor: Cesium.Color.fromCssColorString('#4d9bff')
  }
});

带孔洞的多边形

hierarchy 传对象而不是数组时，可以用 holes 挖洞。孔洞的顶点顺序与外环相反，Cesium 会自动处理：

viewer.entities.add({
  polygon: {
    hierarchy: new Cesium.PolygonHierarchy(
      Cesium.Cartesian3.fromDegreesArray([
        116.30, 39.86, 116.50, 39.86,
        116.50, 40.00, 116.30, 40.00
      ]),
      [
        new Cesium.PolygonHierarchy(
          Cesium.Cartesian3.fromDegreesArray([
            116.36, 39.90, 116.36, 39.95,
            116.44, 39.95, 116.44, 39.90
          ])
        )
      ]
    ),
    material: Cesium.Color.fromCssColorString('#3fe0b0').withAlpha(0.3)
  }
});

outline 不可靠

outline: true 的边线在所有平台上都按 1 像素绘制， outlineWidth 基本被忽略。需要可控宽度的边线时，另加一条 polyline，顶点取同一组坐标，并设 clampToGround: true。

面闪烁。两个同高度、同范围的面重叠时会出现 z-fighting。给其中一个设 height: 0.5，或用 zIndex 明确顺序。贴地多边形之间的层级由 zIndex 决定，不是由添加顺序决定。

顶点数量与性能

贴地多边形的三角剖分在 CPU 上完成，每次相机移动都可能重新计算。省级边界动辄几万个顶点，直接当 Entity 多边形画会卡。做法是先做抽稀（把容差放到 100 米量级），再按视距分级显示。

引用本文

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