Cesium 3DTiles分层分户抽屉实现：从节点遍历到动画完整指南

去年接了个房产数字化项目，客户提的需求很简单：一栋楼的3DTiles模型要能像抽屉一样，点某层就“抽”出来，露出里面的户型结构。听起来不难，真正动手才发现，Cesium里做分层分户抽屉，牵涉到数据组织方式、glTF节点访问、矩阵变换、动画插值这一整套链路，任何一个环节没想清楚都会卡壳。这篇文章把我完整的实现思路、核心代码、以及调试中踩过的坑全部整理出来，给准备做同类功能的同学一条可行的捷径。

1. 先想清楚再做：两条技术路线怎么选

1.1 分层分户抽屉到底在解决什么问题

先说场景。这类功能最常见于房产售楼系统、楼宇招商平台、物业管理后台和应急疏散演练。整栋楼以Cesium 3DTiles格式加载到三维地球后，用户需要按楼层查看，甚至按户型查看。传统做法是“切剖”，用剖切面把楼体切开，但这种方式对操作要求高，普通用户根本玩不转。抽屉效果把“剖切”变成“抽拉”——楼层从楼体中水平滑出，内部户型自然暴露，交互直觉非常清晰。

本质上是解决三维模型的信息层级展示问题：楼栋、楼层、户三元层级，用户需要自由下钻，又不能丢失整体空间位置关系。

1.2 方案A：模型预处理拆分

把BIM模型（Revit、SketchUp、Blender都行）按楼层拆分，分别导出切片成多个3DTiles，每个楼层是一个独立的tileset.json。前端维护一个楼层数组，点击楼层时设置对应tileset的偏移量，实现抽屉效果。

优点很突出：

• 每个楼层独立加载，按需流式加载，内存占用小
• 可以做精确的楼层权限控制（比如某层只有特定用户能看）
• 修改某层模型只需重新生成该层的3DTiles，不用全量重出
• 抽屉动画简单，只需要改tileset.modelMatrix

缺点同样明显：建模阶段就要把楼层拆开，如果模型已经是一个整体，拆分工作量大；楼层之间的“缝”容易在视觉上接不上；后续新增楼层要重新走一遍生产管线。

1.3 方案B：单模型加节点变换

模型保持原始完整结构，导出一个3DTiles，在前端加载后通过访问glTF内部节点，对单个楼层节点做矩阵变换。Cesium 3DTiles内部的b3dm、glTF是有节点树结构的，BIM模型如果命名规范，楼层和户型都能按名称找到。

优点：

• 原始模型不拆，避免接缝问题和数据重复
• 运行时可动态控制任意粒度的节点，楼层、户型、墙体都能动
• 适合做交互式拆解，抽屉只是其中一种动画形式

缺点：

• 依赖模型内部命名规范，命名混乱时定位节点非常痛苦
• 前期开发调试成本高，3DTiles节点树不是直观可见的DOM树
• 数据量大的楼栋一次性加载压力大

我做项目时最终选了方案B为主、方案A为辅的混合策略：楼体整体加载，但在建模阶段就要求Revit导出的模型按楼层命名了节点。如果你的项目模型还没建，强烈建议在建模阶段就做节点命名规范，后面省的时间远大于前期沟通成本。

2. 数据侧准备：确保节点能拿到、能识别

2.1 控制好3DTiles的生产参数

模型导出3DTiles时，有几个参数直接影响你能不能做分层分户。

不要设置clampToGround: true。一旦贴地放置，所有楼层会被压扁到地表，高度信息丢失，分层无从谈起。保留模型原始地理坐标和高度，生成后检查tileset的boundingSphere是否覆盖了楼体的完整高度范围。

不要过度压缩几何。有些转换工具默认开Draco压缩，压缩后节点层级和名称可能丢失。我用的生产链路是：Revit导出FBX -> gltf-pipeline转glTF -> 3D Tiles工具切片。FBX转glTF时保留节点层级，之后切片到3DTiles时节点名仍然能保留。

网上很多人在问“shp转3dtiles”“fbx转3dtiles”“cesium模型可以直接加载su吗”——如果你是从GIS数据转，通常没有内部节点概念；如果是建筑模型（su、fbx、rvt），节点名是保留的。倾斜摄影模型基本没有语义化节点，直接放弃方案B，先用单体化处理或手工重建简化模型。

2.2 给楼层和户型的命名约定

这是整个项目的隐性关键。Demo模型随便起名无所谓，生产项目必须约定：

• 楼层节点统一前缀：floor_1、floor_2、floor_3
• 户型节点统一前缀：room_1_1（1层1号房）、room_1_2
• 公共区域：lobby_1代表1层大堂

遍历节点时通过名称解析，比通过位置计算稳定得多。有一版我在没有命名规范的情况下，只能靠节点包围盒的高度反推楼层，一旦模型有地下层、夹层、设备层，反推逻辑写到你怀疑人生。

2.3 没有规范命名的兜底方案

老模型实在改不了，也不是完全没救。可以按节点包围盒中心点的Z坐标来分层：

function getFloorIndexFromNode(node, baseHeight, floorHeight) { const boundingSphere = node.boundingVolume?.boundingSphere; if (!boundingSphere) return null; const centerHeight = boundingSphere.center.z; const index = Math.round((centerHeight - baseHeight) / floorHeight); return index; }

baseHeight取楼栋最低点，floorHeight取标准层高。注意地下层需要另做映射，比如地下室层高4.5米、地上标准层高3米，混在一起计算会错位。这种方案适合应急验证，生产环境我不推荐。

3. 抽屉效果的本质：两套“移动”逻辑

3.1 抽屉是纯平移，不是旋转也不是缩放

很多人第一次做拆解动画会想到旋转展开——像门一样打开。但抽屉效果的本质是纯平移：把目标楼层沿某个水平方向平移到楼体轮廓外，同时保证平移方向可预测、可逆。

平移的距离单位是米。Cesium的笛卡尔坐标Cartesian3单位是米，但注意你操作的是地心坐标系下的绝对坐标，还是模型局部坐标。平移楼层时，正确做法是在模型局部坐标系里做偏移，再通过模型矩阵转换到世界坐标。

3.2 平移作用在哪个层级

这是容易混淆的地方：

1. 平移整个tileset：通过tileset.modelMatrix做，但这样整栋楼一起动，不是分层分户
2. 平移某个楼层对应的glTF节点：推荐方案
3. 平移户型子节点：需要拿到楼层节点下的子节点逐个处理

在Cesium的3DTiles内部，每个tile的content可能是b3dm、pnts等格式。b3dm内部包含一个glTF模型，这个模型的节点树才是我们操作的对象。旧版本Cesium可以通过tileset._root._content._model._getNodeByName(name)拿节点，不同版本内部结构有差异，这一点项目里一定要锁定Cesium版本。

3.3 动画插值决定手感

抽屉不能“瞬移”，要能看到抽拉过程。Cesium没有内置补间动画器，我采用viewer.clock.onTick监听每一帧，根据时间差计算插值系数，再用矩阵运算设置节点的位移量。

插值系数用简单的线性插值就能看，但视觉偏生硬。稍微好一点用缓动函数：

function easeInOutCubic(t) { return t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2; }

实测下来，抽屉动画用easeInOutCubic或easeOutQuad观众视觉感受最舒服，拉开的前半段稍快，快到位时刹住，很像真实抽屉的惯性感。

4. 可复现的完整代码：加载3DTiles并实现分层分户抽屉

4.1 场景初始化和3DTiles加载

先初始化Viewer，关闭不相关的默认控件，加载tileset时关闭clampToGround，并把maximumScreenSpaceError调大减少渲染压力。

const viewer = new Cesium.Viewer('cesiumContainer', { animation: false, timeline: false, terrainProvider: Cesium.createWorldTerrainAsync() }); // 背景和光照的调整，让模型内部结构看得更清楚 viewer.scene.globe.baseColor = Cesium.Color.fromCssColorString('#2b2b2b'); viewer.scene.light = new Cesium.DirectionalLight({ direction: new Cesium.Cartesian3(-0.5, -0.5, -1), intensity: 0.8 }); const tileset = await Cesium.Cesium3DTileset.fromUrl('/data/building/tileset.json'); tileset.maximumScreenSpaceError = 16; viewer.scene.primitives.add(tileset); await viewer.zoomTo(tileset, new Cesium.HeadingPitchRange(0, -0.6, 300));

这里zoomTo不只是起飞视角，它会让相机定位到tileset包围球适合观看的位置。注意createWorldTerrainAsync是异步的，如果不需要地形可以去掉，直接Cesium.Cartesian3.fromDegrees设置相机位置。

4.2 等3DTiles加载完成再遍历节点

这是新手最容易踩的坑：3DTiles是流式加载的，马上遍历tileset.root时内部几何可能还没到位。需要等待加载完成。

await Cesium.when(tileset.readyPromise, async () => { // 确保所有待加载的Tile都渲染完成 const allLoaded = () => tileset.root.contentReady || tileset.root.contentAvailable; // 简单稳妥做法：均匀延时轮询检查 await waitForTilesLoad(tileset); setupFloorNodes(tileset); });

waitForTilesLoad是一个轮询函数，检查tileset._root._content是否存在且content._model已创建。注意_root开头的方法都是Cesium内部API，新版本可能变化，生产代码要锁定版本并包一层Try-Catch。

4.3 遍历glTF节点收集楼层

拿到模型对象后，按命名约定遍历节点。我封装了一个按名称前缀匹配节点的函数：

function findNodesByPrefix(model, prefix) { const matched = []; model._getNodeNames?.()?.forEach((name) => { if (name.startsWith(prefix)) { matched.push({ name, node: model._getNodeByName(name) }); } }); return matched; }

有些Cesium版本没有_getNodeNames，就手动递归遍历model._rootNode的children：

function traverseGltfNode(node, callback) { if (!node) return; callback(node); const children = node._children || node.children; if (children) { children.forEach(child => traverseGltfNode(child, callback)); } }

遍历时注意，glTF节点的访问要用内部属性，和3DTiles的tile节点是两套体系。收集后保存每个节点的初始矩阵，抽屉动画结束后要能恢复。

4.4 核心：楼层抽屉动画控制

构建一个状态机，保存每个楼层的节点、初始矩阵、当前偏移量、动画状态：

const floorState = {}; function setupFloorNodes(tileset) { const model = tileset.root.content.model || tileset._root._content._model; if (!model) return; const floorPrefix = 'floor_'; const roomPrefix = 'room_'; // 遍历模型节点，找到所有楼层 traverseGltfNode(model._rootNode, (node) => { if (node.name && node.name.startsWith(floorPrefix)) { floorState[node.name] = { node: node, originMatrix: node.matrix.clone(), offsetX: 0, isOpen: false, animation: null }; } }); }

有了楼层节点，做抽屉动画就是修改node.matrix。注意，不能直接改节点的position属性，因为glTF节点的position是局部坐标，而我们需要的是相对模型的局部平移。正确做法是：初始矩阵乘以平移矩阵。

function setFloorOffset(floorName, offsetX, offsetY, offsetZ) { const state = floorState[floorName]; if (!state) return; const translationMatrix = Cesium.Matrix4.fromTranslation( new Cesium.Cartesian3(offsetX, offsetY, offsetZ) ); const newMatrix = Cesium.Matrix4.multiply( state.originMatrix, translationMatrix, new Cesium.Matrix4() ); state.node.matrix = newMatrix; state.offsetX = offsetX; }

抽屉效果的位移方向，我选择沿X轴（建筑开间方向）向外平移。不同的模型在建模软件里朝向可能不同，上线前要确认平移方向对用户体验友好。如果模型不是正北朝向，用世界坐标偏移会出现斜向抽拉，最好在局部坐标系做ENU变换。

4.5 抽屉动画插值实现

定义抽屉拉开角度/距离，然后用时间差驱动插值。这里我用viewer.clock.onTick做帧监听：

function animateFloorDrawer(floorName, targetDistance, duration = 1.0) { const state = floorState[floorName]; if (!state) return; const startTime = Cesium.JulianDate.now(); const startOffset = state.offsetX; const targetOffset = targetDistance; if (state.animation) { viewer.clock.onTick.removeEventListener(state.animation); } const update = (clock) => { const currentTime = clock.currentTime; const ratio = Math.min( Cesium.JulianDate.secondsDifference(currentTime, startTime) / duration, 1.0 ); const eased = easeInOutCubic(ratio); const newOffset = startOffset + (targetOffset - startOffset) * eased; setFloorOffset(floorName, newOffset, 0, 0); if (ratio >= 1.0) { viewer.clock.onTick.removeEventListener(update); state.animation = null; state.isOpen = targetOffset !== 0; } }; state.animation = update; viewer.clock.onTick.addEventListener(update); }

这里有一个很重要的点：Cesium的onTick事件在所有渲染帧都会触发，如果多个楼层同时动画，会有多个闭包同时存在，注意清理监听器，避免内存泄漏。我在state.animation里保存了当前动画函数，新动画启动时先移除旧的。

4.6 实现整栋楼的“全拉出”和“全收回”

实际业务中用户不止是单层抽拉，还有“一键全部拉开”的需求。做法就是遍历所有楼层，先统一计算每个楼层抽屉的展开方向和距离，避免层与层重叠，然后逐层做动画，错开启动时间，形成顺序推拉的节奏：

function openAllDrawers(distance = 30, staggerDelay = 120) { const floorNames = Object.keys(floorState); floorNames.forEach((name, index) => { setTimeout(() => { animateFloorDrawer(name, distance, 0.8); }, index * staggerDelay); }); }

4.7 点击楼层实现交互

最简单实用的方式不是直接拾取3DTiles节点，而是给每个楼层添加一个透明拾取盒子。因为3DTiles内部的glTF节点拾取在不同的Cesium版本表现不稳定，透明盒子方案稳定且易于控制，还可以加点击反馈和描边。

function createFloorPickBox(floorName, centerPosition, dimensions) { const entity = viewer.entities.add({ name: `pick_${floorName}`, position: Cesium.Cartesian3.fromDegrees(centerPosition.lng, centerPosition.lat, centerPosition.height), box: { dimensions: new Cesium.Cartesian3(dimensions.x, dimensions.y, dimensions.z), material: Cesium.Color.WHITE.withAlpha(0), outline: false }, properties: { floorName: floorName } }); return entity; } const handler = new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas); handler.setInputAction((movement) => { const picked = viewer.scene.pick(movement.position); if (picked?.id?.properties?.floorName) { const floorName = picked.id.properties.floorName.getValue(); toggleFloorDrawer(floorName); } }, Cesium.ScreenSpaceEventType.LEFT_CLICK);

toggleFloorDrawer里根据isOpen状态决定是拉出还是收回。点击盒子所在楼层后，如果已经展开就收回，否则就展开。

4.8 相机跟随与定位

抽屉拉出后，相机要能自动聚焦到被拉出的楼层。Cesium提供了viewer.flyTo来定位到实体，但3DTiles内部的节点没有直接对外的Entity。需要手动计算节点包围盒的中心：

function flyToFloor(floorName, offset = 50) { const state = floorState[floorName]; if (!state) return; // 节点本身是glTF节点，拿不到transform后的世界位置 // 用节点包围盒中心 + 当前tileset的modelMatrix换算 const tilesetPosition = tileset.boundingSphere.center; const worldPosition = Cesium.Matrix4.multiplyByPoint( tileset.modelMatrix, tilesetPosition, new Cesium.Cartesian3() ); viewer.camera.flyTo({ destination: Cesium.Cartesian3.fromDegrees( Cesium.Math.toDegrees(worldPosition.longitude), Cesium.Math.toDegrees(worldPosition.latitude), worldPosition.height + offset ), orientation: { heading: 0, pitch: Cesium.Math.toRadians(-45), roll: 0 }, duration: 0.8 }); }

5. 实际项目里容易踩的六个坑

5.1 allTilesLoaded永远不触发

很多教程都告诉你tileset.allTilesLoaded事件可以判断加载完成，但这个事件在相机视角不断变化、Tile不断被替换时会反复触发，甚至不触发。稳妥做法是不等这个事件，而是用轮询检查tileset.root._content是否存在并已有_model，配合一个超时上限。我在项目中用了50次轮询，间隔100毫秒，5秒内还没拿到模型就报错提示。

5.2 修改了matrix但不生效或闪跳

修改glTF节点node.matrix在大多数Cesium版本下一帧生效，但如果修改的是_content里尚未加载完成的node，操作会被后续的tile加载覆盖。

解决办法：确认在拿到_model之后再获取节点并保存初始矩阵，动画期间避免摄像头大幅视角切换触发新的Tile细化。如果遇到修正了matrix又跳回原位，检查是否修改的是node.transform而不是node.matrix。两者区别：

• node.transform是glTF规范的标准属性，为Matrix4
• node.matrix是Cesium对节点变换的内部存储

旧版本Cesium中操作的是node.matrix，新版里node.transform更稳定。

5.3 抽屉拉开后楼层之间穿模

这是最影响观感的问题。单纯平移只能拉开抽屉，但相邻楼层之间的公共墙、管线还是会穿帮。两个针对手段：

1. 平移距离必须大于被拉出楼层的最大轮廓尺寸，让楼层完全脱离楼体轮廓
2. 剪裁平面配合：在楼体侧面设置一个或多个ClippingPlane，把当前楼体内部被遮挡的部分“切掉”

const plane = new Cesium.ClippingPlane( new Cesium.Cartesian3(0, 1, 0), // 法线方向 clipDistance );

注意ClippingPlane是无限平面，要配准确的法线和距离，否则会把楼体外部也切了。我实测的结论：动画时长在0.8秒时，剪裁平面跟随抽屉距离线性移动，视觉上几乎看不到穿模。

5.4 平移距离的米制换算问题

抽屉拉开距离不能拍脑袋定，要根据模型的实际宽度算。比如楼体沿X轴方向宽度为32米，那么拉出至少35米。用tileset.boundingSphere.radius * 2可以粗略估算楼体宽度，更精确的做法是获取楼层节点的包围盒尺寸：

const boundingSphere = Cesium.BoundingSphere.fromBoundingSphere( // 部分版本节点有boundingVolume state.node.boundingVolume?.boundingSphere );

如果拿不到node级包围盒，就用tileset的整体包围盒乘以缩放系数。开发阶段在UI上加一个distance滑动条动态调整，是最好的调参方式。

5.5 倾斜摄影模型根本做不了节点抽屉

很多网友搜“cesium倾斜摄影”进来，想给倾斜摄影模型做分层分户。这里必须泼冷水：倾斜摄影的3DTiles是密集Mesh，没有语义化的楼层节点，node名全是随机字符串。要做分层分户只能：

• 用单体化工具把倾斜模型按建筑底面切割
• 或者重建简模（BIM手工建模/自动建模）
• 或者对OSGB数据进行压平和分类

倾斜摄影适合全貌查看、量测，不适合做精细分层。我把这个写在文章里，希望做选型时少走弯路。

5.6 Cesium版本差异是最大的隐藏成本

1.x阶段Cesium迭代非常快，3DTiles内部实现频繁调整。项目里用某版本写好的_root._content._model._getNodeByName，过两个季度升级Cesium后可能完全失效。

项目经验：锁定Cesium版本，升级做专项回归。每次升级先跑节点遍历自测，再跑抽屉动画，最后检查相机拾取。

6. 从抽屉到成品：我的落地功能清单和建议扩展

6.1 基础功能清单

最终交付给客户时，做的分层分户抽屉功能包含以下模块：

6.2 结合单体化做户型信息联动

倾斜摄影做不了抽屉，但是正射场景结合“单体化”可以做户型点击信息联动。所谓单体化，本质上是对3DTiles的Feature增加属性，让前端通过Cesium3DTileFeature读取batchId对应的属性值，然后弹窗显示。这个和抽屉效果可以混搭：楼体用BIM做抽屉，周边环境用倾斜摄影做单体化，房地产项目经常这么组合。

6.3 配合动态光照和热力图做营销效果

抽屉效果做出来后，客户往往会追加两类效果：

一是动态光照，模拟一天内太阳光移动，照射到拉出的楼层和户型，售楼处大屏上效果拔群。实现上用viewer.scene.light的direction随时间变化即可，注意在太阳转至建筑背面时室内光线过暗，需要加环境光保底。

二是热力图，按楼层/户型展示认购率、空置率。可以在地面叠加一个热力图图层，也可以给已售户型做颜色覆盖。数据量小时用Entity的Polygon拾取，数据量大时用GeoJSON加载再样式映射。

6.4 鹰眼和联动定位

详情页和总览页之间需要“鹰眼”地图做定位反馈。Cesium实现鹰眼最简单方式是用一个右下角的小Cesium.Viewer，跟随主相机同步视角，或者用2D地图（如Leaflet）做同步定位。我项目里用的是第二个Viewer同步的方式，代码量少，且可以支持3D联动视角。

6.5 稳定性和老旧设备降级

抽屉动画底层依赖每帧矩阵计算，老旧电脑或浏览器如果不支持WebGL 2.0，大概率白屏卡顿。建议做能力检测：

const canvas = document.createElement('canvas'); const gl = canvas.getContext('webgl2') || canvas.getContext('webgl'); if (!gl) { // 提示用户升级浏览器或使用支持WebGL的设备 }

同时把Cesium的scene.debugShowFramesPerSecond暴露给内部测试，目标设备上帧率低于25fps时降低maximumScreenSpaceError并减少同时展开的楼层数。

我自己在这个项目里最后沉淀下来的体会是：分层分户抽屉谈不上高深算法，但非常考验工程串联能力。数据侧命名规范能省一半前端时间，模型侧层级结构决定你能做多细的节点控制，而前端侧把矩阵变换、动画插值和拾取交互想清楚就成功了大半。如果你正准备做这个功能，建议先拿一个命名规范的测试模型，跑通节点遍历和矩阵动画这一小段，再铺开到完整业务，不要一上来就调大模型。记住，先把一个楼层拉出来，再谈整栋楼。