宏观数字地球（createRegionPolygon / createRegionBoundary）

把世界行政区划（GeoJSON Polygon / MultiPolygon）渲染为渐变色阶抬升多边形，再以 createRegionBoundary 的闭合 polyline 画出清晰可辨的国界分界线，配合 DivPointLayer 叠加随视角显隐的首都标签，构成宏观总览地球。适合大屏态势总览、全球数据分布可视化、数字孪生宏观场景。

能力定位

createRegionPolygon 是一个 Entity 创建工厂：输入单个行政区划 feature 与填充色，返回一个带 perPositionHeight 贴地、向上抬升的 polygon 实体。createRegionBoundary 是其配套工厂：输入同一 feature，返回一条贴合多边形顶面外缘的闭合描边 polyline，用于画出宏观视角下清晰可见的国界分界线。与 createGradient 组合即可为多个区划生成渐变色阶。

宏观总览地球：世界 / 国家级行政区划渐变色阶抬升 + 国界分界线（如本案例 189 国）；
区域数据分级：按指标映射色阶逐个区划着色；
首都 / 地标标签：配合 DivPointLayer 叠加任意 HTML 标签，随相机视高自动显隐。

与相关能力的分工：

能力	形态	差异
`createRegionPolygon`	GeoJSON 区划 → 抬升 polygon 实体	单区划填充工厂，可组合 `createGradient` 色阶
`createRegionBoundary`	GeoJSON 区划 → 闭合描边 polyline 实体	国界分界线工厂，宏观视角下清晰可见
`DivPointLayer`	任意 HTML 覆盖层标注图层	投影 DOM 标签，可锚定首都等点位
`GeoJsonLayer`	GeoJSON 图层	通用矢量渲染，不面向行政区划抬升样式

函数签名

createRegionPolygon(
  feature: RegionGeoJsonFeature,
  fillColor: Color,
  options?: RegionPolygonOptions
): Entity

interface RegionGeoJsonFeature {
  geometry: RegionPolygonGeometry | RegionMultiPolygonGeometry
  properties?: Record<string, unknown>
}

interface RegionPolygonOptions {
  extrudedHeight?: number // 抬升高度（米），默认 100000
  outlineColor?: string   // 描边颜色（CSS 色值），默认 '#a65734'
  outlineWidth?: number   // 描边宽度（像素），默认 1
}

参数	类型	默认值	描述
`feature`	`RegionGeoJsonFeature`	—	GeoJSON 区划 feature；Polygon 取首环，MultiPolygon 取首块首环（对齐源案例，不处理内环）
`fillColor`	`Cesium.Color`	—	填充颜色，通常来自 `createGradient` 生成序列
`options.extrudedHeight`	`number`	`100000`	向上抬升高度（米），对齐源案例 100km 区划抬升
`options.outlineColor`	`string`	`'#a65734'`	描边颜色，对齐源案例 `outlineColor`
`options.outlineWidth`	`number`	`1`	描边宽度（像素，WebGL 下多边形描边恒为 1px，宏观不可见；可见国界请用 `createRegionBoundary`）

createRegionBoundary 函数签名

createRegionBoundary(
  feature: RegionGeoJsonFeature,
  options?: RegionBoundaryOptions
): Entity

interface RegionBoundaryOptions {
  height?: number // 边界线所在高度（米），默认 100000 —— 对齐 createRegionPolygon.extrudedHeight
  width?: number   // 线宽（像素），默认 2
  color?: string   // 描边颜色（CSS 色值），默认 '#a65734'
}

参数	类型	默认值	描述
`feature`	`RegionGeoJsonFeature`	—	与 `createRegionPolygon` 共用同一 feature 与首环提取规则
`options.height`	`number`	`100000`	边界线所在高度，默认对齐多边形顶面（内部再抬升 200m 避免顶盖 z-fighting）
`options.width`	`number`	`2`	线宽（像素）；Cesium polyline 支持任意宽度，宏观视角清晰可辨
`options.color`	`string`	`'#a65734'`	描边颜色，对齐源案例 `outlineColor`

为什么需要它：Cesium 多边形 outline 走原生 GL_LINES，outlineWidth 在 WebGL 上恒为 1，宏观相机距离（数千万米）下 1px 线条被填充覆盖 / 亚像素化而不可见。独立 polyline 可在宏观视角稳定渲染出可调宽度的国界分界线。

基础示例

import { createRegionPolygon, createGradient } from '@nexa/gis-cesium'
import { Color } from 'cesium'

// 为 189 个国家生成渐变色阶（深→浅再 reverse 为浅→深），逐个建实体
const colors = createGradient('#495362', '#C4CCDC', geo.features.length).reverse()
const entities = geo.features.map((f, i) =>
  createRegionPolygon(f, Color.fromCssColorString(colors[i]))
)
// ⚠️ EntityCollection.add 不展开数组（数组会被包成单个空实体），必须逐个添加
entities.forEach((entity) => viewer.entities.add(entity))

进阶示例

区划色阶 + 国界分界线 + 首都锚点 + 随视角显隐的标签。

import { createRegionPolygon, createRegionBoundary, createGradient, DivPointLayer } from '@nexa/gis-cesium'
import { Cartesian3, Color, DistanceDisplayCondition } from 'cesium'

// 1. 世界区划渐变色阶 + 国界分界线
// ⚠️ EntityCollection.add 不展开数组（数组会被包成单个空实体），必须逐个添加
const colors = createGradient('#495362', '#C4CCDC', geo.features.length).reverse()
geo.features
  .flatMap((f, i) => [
    createRegionPolygon(f, Color.fromCssColorString(colors[i])),
    createRegionBoundary(f, { height: 100000, width: 2 }),
  ])
  .forEach((entity) => viewer.entities.add(entity))

// 2. 首都锚点（透明填充 + 外发光描边，仅宏观距离可见）
capitals.features.forEach((f) => {
  viewer.entities.add({
    position: Cartesian3.fromDegrees(f.geometry.coordinates[0], f.geometry.coordinates[1], 100000),
    point: {
      pixelSize: 2,
      color: Color.RED.withAlpha(0),
      outlineColor: Color.fromCssColorString('#FFFF9D'),
      outlineWidth: 2,
      distanceDisplayCondition: new DistanceDisplayCondition(15000000, 23000000),
    },
  })
})

// 3. 首都名称 DOM 标签：相机视高超 2300 万米自动隐藏
const labels = new DivPointLayer({ hideHeight: 23000000 })
labels.on(viewer)
capitals.features.forEach((f) => {
  labels.addPoint({
    position: Cartesian3.fromDegrees(f.geometry.coordinates[0], f.geometry.coordinates[1], 100000),
    content: `<div class="capital">${f.properties.Capital}</div>`,
  })
})

// 退出场景时清理（幂等）
viewer.entities.removeAll()
labels.destroy(viewer)

生命周期与清理责任

createRegionPolygon / createRegionBoundary 只创建实体，不订阅事件、不持有运行时资源；由调用方 viewer.entities.add / removeAll 管理，退出场景时统一清理。
⚠️ EntityCollection.add 不接受数组：源码对非 Entity 入参一律 new Entity(entity)，不会展开——viewer.entities.add([a, b, c]) 会把整个数组包成单个空实体静默不渲染（本案例曾因该用法导致国界分界线整体缺失）。务必逐个 viewer.entities.add(entity)。
DivPointLayer 标签按既有 Lifecycle 契约 on/off/destroy 幂等清理。

Cesium 版本限制

依赖公共 API：Cartesian3.fromDegreesArray、PolygonHierarchy、Entity.polygon （perPositionHeight / extrudedHeight）、Entity.polyline（positions / width）；
多边形 outline 走原生 GL_LINES，outlineWidth 在 WebGL 上恒为 1（实测 width 5 与 width 1 渲染像素完全一致），宏观相机距离下 1px 描边不可见；因此本案例的国界分界线用 createRegionBoundary 的独立 polyline（width 2）渲染，实测宏观视角描边像素从 46 → 611 提升 13 倍，清晰可辨；
源案例 TransparentLabel3d 使用的 SceneTransforms.wgs84ToWindowCoordinates 在目标 Cesium 1.133 已移除，标签投影已迁移为 DivPointLayer 的公共 SceneTransforms.worldToWindowCoordinates；
已验证目标版本：Cesium 1.133.1。

数据资产

示例数据（countries_geo.json 189 国区划、capitals.json 163 首都）来源于源仓库 cesium-example/src/static/data/world_region/，为公开行政区划数据；示例运行时通过 /static/data/world_region/ 加载。

宏观数字地球（createRegionPolygon / createRegionBoundary） ​

能力定位 ​

函数签名 ​

createRegionBoundary 函数签名 ​

基础示例 ​

进阶示例 ​

生命周期与清理责任 ​

Cesium 版本限制 ​

数据资产 ​