cesium entity point 属性概览

| 属性分类 | 属性名称 (Type) | 默认值 | 描述 |
|----------|--------------------------------------|---------------------------|------------------------|-----------------------------------------------------------------------------------------------------------|
| 核心样式 | show (Property | boolean) | true | 是否显示该点1。 |
| | pixelSize (Property | number) | 1 | 点的大小（像素） 12。 |
| | color (Property | Color) | Color.WHITE | 点的填充颜色12。 |
| | outlineColor (Property | Color) | Color.BLACK | 点的轮廓线颜色12。 |
| | outlineWidth (Property | number) | 0 | 点的轮廓线宽度（像素） 12。 |
| | heightReference (Property | HeightReference) | HeightReference.NONE | 点的高度参考。可选 NONE(绝对高度), CLAMP_TO_GROUND(贴地), RELATIVE_TO_GROUND(相对地面高度)26。 |
| 动态效果 | scaleByDistance (Property | NearFarScalar) | | 根据与相机的距离缩放点的大小 。例如 new Cesium.NearFarScalar(1500, 1.0, 20000, 0.3) 表示在1500米处大小为1倍，20000米处缩小到0.3倍16。 |
| | translucencyByDistance (Property | NearFarScalar) | | 根据与相机的距离改变点的透明度 。用法同 scaleByDistance16。 |
| 显示控制 | distanceDisplayCondition (Property | DistanceDisplayCondition) | | 指定点在特定距离范围内 可见。例如 new Cesium.DistanceDisplayCondition(0, 20000) 表示仅在0到20000米范围内显示16。 |
| | disableDepthTestDistance (Property | number) | 0.0 | 设置从相机到该点的禁用深度测试的距离 。例如设置为 Number.POSITIVE_INFINITY 可防止点被地形或其他实体遮挡（始终可见）18。 |

基本用法与代码示例

1. 创建一个简单的点

js 复制代码

// 直接通过 viewer.entities.add 创建并添加点
const pointEntity = viewer.entities.add({
  position: Cesium.Cartesian3.fromDegrees(116.39, 39.91, 100), // 经度，纬度，高度（米）
  point: {
    pixelSize: 15, // 大小
    color: Cesium.Color.RED, // 填充颜色
    outlineColor: Cesium.Color.WHITE, // 轮廓颜色
    outlineWidth: 2, // 轮廓宽度
    heightReference: Cesium.HeightReference.CLAMP_TO_GROUND // 贴地（当地形开启时）
  },
  name: '我是一个点' // 可选的实体属性
});
viewer.zoomTo(pointEntity); // 飞行定位到该点

2. 创建具有动态效果的点

js 复制代码

// 创建一个随距离缩放和改变透明度的点
const dynamicPoint = viewer.entities.add({
  position: Cesium.Cartesian3.fromDegrees(121.47, 31.23, 500),
  point: {
    pixelSize: 20,
    color: Cesium.Color.BLUE.withAlpha(0.8),
    outlineColor: Cesium.Color.CYAN,
    outlineWidth: 3,
    scaleByDistance: new Cesium.NearFarScalar(1000, 1.5, 10000, 0.5), // 1000米处1.5倍大小，10000米处0.5倍
    translucencyByDistance: new Cesium.NearFarScalar(1000, 1.0, 10000, 0.2), // 1000米处不透明，10000米处透明
    distanceDisplayCondition: new Cesium.DistanceDisplayCondition(0, 20000) // 20公里内可见
  }
});

3. 创建闪烁的点（使用 CallbackProperty）

js 复制代码

// 创建一个透明度周期性变化的点，实现闪烁效果
const flashPoint = viewer.entities.add({
  position: Cesium.Cartesian3.fromDegrees(113.26, 23.13, 200),
  point: {
    pixelSize: 12,
    color: Cesium.Color.YELLOW,
    outlineColor: Cesium.Color.ORANGE,
    outlineWidth: 1,
    // 使用 CallbackProperty 动态计算颜色（透明度变化）
    color: new Cesium.CallbackProperty(function (time, result) {
      // 计算一个在0.3到1.0之间周期性变化的值
      const alpha = 0.3 + 0.7 * (0.5 + 0.5 * Math.sin(Date.now() / 1000)); // 每秒循环一次
      return Cesium.Color.YELLOW.withAlpha(alpha);
    }, false) // false 表示每次渲染帧都调用此函数
  }
});

4. 修改已存在的点属性

js 复制代码

// 获取之前创建的点实体（假设你知道其id或引用）
// const pointEntity = viewer.entities.getById('someId');

if (pointEntity) {
  // 直接修改点的属性
  pointEntity.point.pixelSize = 25;
  pointEntity.point.color = Cesium.Color.GREEN;
  // 如果需要修改整个PointGraphics，可以使用merge方法或重新赋值
  // pointEntity.point = new Cesium.PointGraphics({ ...new options });
}

5. 处理大量点（性能考虑）

当需要添加成千上万个点时，使用 Entity API 可能会对性能有影响。这时可以考虑使用 Primitive API 中的 PointPrimitiveCollection，它为大量静态点的渲染进行了优化6。

js 复制代码

// 使用Primitive API创建点集（性能更好）
const pointPrimitives = viewer.scene.primitives.add(new Cesium.PointPrimitiveCollection());

const positions = [
  Cesium.Cartesian3.fromDegrees(116.41, 39.92),
  Cesium.Cartesian3.fromDegrees(121.48, 31.22),
  // ... 更多位置
];

positions.forEach(function (position) {
  pointPrimitives.add({
    position: position,
    color: Cesium.Color.RED,
    pixelSize: 8
  });
});