首页 / Cesium / API 文档

Cesium3DTile

先看结论

3D Tiles 树上的单个瓦片。一个 tileset 由根瓦片和它的子瓦片组成，每块瓦片各自持有内容、包围体与细化方式。

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

由 Cesium3DTileset 内部构建，不直接 new

成员

成员	说明
`tileset`	所属的 `Cesium3DTileset`
`parent`	父瓦片，根瓦片为 undefined
`children`	子瓦片数组
`content`	瓦片内容，未加载时为 undefined；`content.tileset` 指向嵌套的 tileset
`hasEmptyContent`	内容为空，仅用于占位
`hasTilesetContent`	内容是外部 tileset，用于组合多个数据集
`boundingVolume`	包围体，可能是 `TileBoundingRegion` 或 `TileOrientedBoundingBox`
`contentBoundingVolume`	内容包围体，可为空
`geometricError`	瓦片自身误差，米
`refine`	`ADD` 或 `REPLACE`，控制子瓦片加载后父瓦片是否保留
`transform`	瓦片局部坐标到世界坐标的 `Matrix4`
`selected` / `visible`	当前是否被选中、是否通过可见性测试

方法

方法	说明
`requestContent()`	主动请求内容；`tileset.show` 为 false 时可能被忽略
`unloadContent()`	卸载已加载内容，释放显存
`destroy()` / `isDestroyed()`	销毁瓦片本身
`getScreenSpaceError(frameState)`	当前视角下的屏幕空间误差

遍历已加载瓦片

function walk(tile, depth) {
  if (!tile) {
    return;
  }

  if (tile.content) {
    console.log(
      ' '.repeat(depth) + '内容已加载',
      tile.content.featuresLength
    );
  }

  for (var i = 0; i < tile.children.length; i++) {
    walk(tile.children[i], depth + 1);
  }
}

walk(tileset.root, 0);

refine 的两种含义

ADD 会在子瓦片加载后同时保留父瓦片，适合点云和补充细节； REPLACE 则用子瓦片替换父瓦片，适合整块模型。同一棵树上两种方式可以混用，由每个瓦片自己的 JSON 决定。

手动控制时注意

tileset.maximumScreenSpaceError 才是控制细节层级的总开关，逐个瓦片调用 requestContent 通常没有必要：缓存策略由 tileset 统一管理，绕过调度的请求容易造成重复下载。需要按业务条件筛选瓦片时，优先使用 tileset.tileVisible 事件和 Cesium3DTileStyle。

不要长期持有瓦片引用。内容被卸载后 content 会变成 undefined，之前缓存的 Cesium3DTileFeature 也随之失效。需要跨帧保存的状态，应该记录在业务数据里而不是瓦片对象上。

引用本文

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