首页 / Cesium / API 文档

Cesium3DTileFeature

先看结论

一个 3D Tiles 要素：网格、点或标签的单个实例。可读属性、改颜色、临时显隐，是「点击建筑高亮」这类交互的标准入口。

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

由 scene.pick 返回，不直接构造

拾取 3D Tiles 时，scene.pick 返回带 content 的对象， content.featuresLength 大于 0 时可用 content.getFeature(0) 拿到要素。要素对象本身不公开构造函数。

常用成员

成员	说明
`content`	所属的瓦片内容 Cesium3DTileContent
`featureId`	要素在该内容里的索引
`primitive`	所属的 Cesium3DTileset
`tileset`	同上，所属瓦片集（旧名）
`show`	boolean，临时显隐；不影响瓦片加载
`color`	Color，样式色；与瓦片原色按 `colorBlendMode` 混合
`batchId`	要素的批次 id（已废弃，用 featureId）

常用方法

方法	返回	说明
`getProperty(name)`	any	按名取属性值；复合属性如 `attributes.height`
`getPropertyIds(results)`	Array	列出所有属性名，未传 results 时新建数组
`setProperty(name, value)`	—	写属性，供样式表达式引用
`getPropertyNames(results)`	Array	同 getPropertyIds（旧名）

示例

var handler = new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas);
handler.setInputAction(function (movement) {
  var picked = viewer.scene.pick(movement.position);
  if (!Cesium.defined(picked)) { reset(); return; }

  var content = picked.content;
  if (!Cesium.defined(content) || content.featuresLength === 0) return;

  var feature = content.getFeature(0);
  var ids = feature.getPropertyIds();
  var row = {};
  ids.forEach(function (name) {
    row[name] = feature.getProperty(name);
  });
  console.log('要素属性', row);

  feature.color = Cesium.Color.YELLOW.withAlpha(0.8);
}, Cesium.ScreenSpaceEventType.LEFT_CLICK);

function reset() {
  // 恢复整棵瓦片集的样式色
  tileset.style = new Cesium.Cesium3DTileStyle();
}

注意事项

要素的 color 优先级高于瓦片集样式里的 color；重置时给 tileset.style 赋新样式对象即可恢复。
属性名区分大小写；属性不存在时 getProperty 返回 undefined，复合属性要用点号逐级访问。
几何压缩过的瓦片某些属性可能读不到或返回默认值，具体取决于服务端如何打包 batch 属性。
大范围逐要素改颜色性能差，批量需求优先写进 Cesium3DTileStyle 表达式。

引用本文

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