很多人在 Cesium 里做三维模型展示时都很顺手模型加载出来、摆好视角、加几个飞行相机项目就能交付了。直到客户说“能不能让我用鼠标直接把模型拖到想放的位置”这一刻你从“展示三维场景”进入了“场景内交互编辑”。我第一次做这个功能时低估了它的难度以为给鼠标绑定一个移动事件就行。结果模型要么跟着鼠标满屏飞要么在起伏地形上穿进地下要么拖一个模型连相机都被带偏。后来我把整个交互链路拆开重做才意识到模型拖拽变换的关键不是“让模型跟着鼠标动”这个效果而是三个问题——如何准确拾取到模型如何把鼠标位置换算成场景里的目标位置以及拖拽过程中的状态怎么管理。只要这三件事没有闭环任何一段都可能出问题。换句话说拖拽变换这个功能看起来是给模型加一组鼠标事件实际上是一个从“展示”到“交互编辑”的转折点。它需要你把几件平时不会放在一起考虑的事情串起来模型拾取、坐标转换、鼠标事件状态机、地形与相机的关系。“拖得动”只是第一步“拖得稳、拖得准、拖得符合业务语义”才是真正的分水岭。1. 先别急着绑鼠标事件想清楚拖拽到底在拖什么1.1 从“展示模型”到“编辑模型”到底发生了什么变化展示阶段模型的 position 是代码里写死的相机转一圈模型不动。编辑阶段position 成了需要被鼠标事件修改的活数据。这带来一个很实际的转变你不再单方向控制场景而是要让用户在场景里对某个对象产生一次“操作”场景立刻反馈。这个链路至少包括用户按下鼠标能识别出按到的是哪个模型。鼠标移动时能生成新的位置 / 姿态数据。场景刷新后模型出现在新位置。鼠标抬起后不再误触发移动。看起来像状态机其实就是一个“按下 - 移动 - 抬起”的交互会话。很多人一上来就想着做旋转手柄、缩放控制条、吸附网格结果基础事件还没理顺最后连拖动都做不稳。1.2 一个最小拖拽闭环先把框架立住先把“能拖”这个动作做出来再考虑精度和手感。最小闭环是用ScreenSpaceEventHandler绑定鼠标左键按下事件。在按下事件里用scene.pick拾取模型实体。在鼠标移动事件里计算目标点并更新entity.position。在鼠标抬起事件里清除拖拽状态。不要一上来就加旋转、缩放、吸附、多选和撤销。先验证从 A 点到 B 点是否可控再逐步加复杂度。1.3 拖拽目标、坐标系和参考面一开始就要定下来你拖的是一个 Entity还是一个 Primitive还是一个 3D Tiles 对象处理方式完全不同。Entity 有 position直接改 position 就行。Primitive 可能要先包装成 Entity或者通过修改 modelMatrix 实现。3D Tiles 也要改 modelMatrix但参考点选错整个瓦片会飞走。同时鼠标移动过程中生成的“目标位置”有不同策略。常见三种沿地形表面移动保持在固定高度、沿参考平面移动沿屏幕平行平面移动。这决定你用globe.pick、scene.pickPosition还是自己计算射线与某个参考平面的交点。很多人拖一下就飘往往是在这一点上没有按场景语义选对策略。2. 拖拽前必须搞清楚的坐标和事件基础2.1 鼠标事件、拾取接口和“选中态”Cesium 的ScreenSpaceEventHandler是一套成熟的鼠标事件封装。拖拽功能里常用的三种事件是LEFT_DOWN、MOUSE_MOVE、LEFT_UP。拾取模型时通常用viewer.scene.pick。它返回的是包含id或primitive的拾取结果。如果picked.id存在代表拾取到的是 Entity如果返回的是某个 primitive则直接拿到对象。这里容易忽略一个概念“选中态”。拖拽过程中模型需要处于一个“已经被选中”的状态。这个状态不是 Cesium 帮你维护的而是自己在全局变量里记录。拖拽一开始要做三件事记录被拖拽对象记录起始位置模型当前位置 鼠标当前窗口位置在拖拽期间临时关闭可能干扰的相机操作。为什么要临时关闭相机因为默认情况下鼠标在模型上按下并移动Cesium 会同时触发相机操作。如果你不把screenSpaceCameraController.enableRotate或enableTranslate关掉拖一个模型相机也跟着转场景会乱。2.2 把鼠标位置换算成场景坐标的三种常见策略这是拖拽中真正的技术核心。鼠标的二维坐标必须先转成三维场景里的某个点才能赋给模型。第一种沿地形表面移动。用viewer.scene.globe.pick(ray, scene)得到射线与地形的交点适合地面物体。问题在于当地形起伏大时模型会跟着地形上下用户可能觉得“跳”。同时如果模型起始高度远高于地形拖一下就会被压到地面。第二种保持固定高度移动。先得到模型的当前高度然后在相机射线和“以椭球面为基准、保持这个高度”的平面之间求交。这样模型不会穿地也不会突然浮空。适合建筑楼层、高架设备、空中物体等对象。第三种屏幕平行移动。直接根据鼠标在屏幕上的像素位移换算成场景里的世界位移。适合相机视角相对固定或者需要像“编辑器”一样水平拖动对象的场景。可以用一个表把这三种策略放在一起对比方便后面选型。策略适合对象优点注意点地形贴地globe.pick地面设备、地物模型模型贴合地形实现最简单地形起伏大会跳变模型初始高度较高时容易被吸到地面固定高度平面楼层、高架设备、空中物体高度稳定不穿地不悬空需要自己维护参考平面相机视线接近水平时交点可能不稳定屏幕平行面编辑场景、视觉对齐跟随鼠标直观适合精细移动需要把屏幕位移换算成世界位移不同视角下手感不同2.3 为什么 model.position 不是唯一要维护的东西很多人拖 Entity 模型时只更新 position却发现模型本身有朝向、有高度、有旋转拖完之后方向不对。Cesium 里一个完整模型视觉状态至少由两部分组成position 和 orientation。position 决定它在哪orientation 决定它朝哪。如果你只是把 position 改成新点orientation 保持不变大多数情况下没问题。但如果你同时做了旋转操作就要小心先算旋转再算位置还是先移动再旋转结果完全不一样。比较稳妥的做法是拖拽位置时保留原有 orientation拖拽旋转手柄或进入旋转模式时只更新 orientation不改变 position。把“位置调整”和“姿态调整”拆成两个交互会话避免一次性做太多变换。3. 用 Entity 模型实现一个可用的拖拽流程3.1 最小步骤加载模型、绑定事件、更新位置先给出一个最基础的 Entity 模型加载写法。const viewer new Cesium.Viewer(cesiumContainer); const entity viewer.entities.add({ name: draggableModel, position: Cesium.Cartesian3.fromDegrees(116.391, 39.907, 0), model: { uri: /models/example.glb, scale: 1.0 } }); viewer.flyTo(entity);然后创建事件处理器实现基础拖拽const handler new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas); let isDragging false; let dragEntity null; handler.setInputAction(function (movement) { const picked viewer.scene.pick(movement.position); if (Cesium.defined(picked) picked.id entity) { isDragging true; dragEntity picked.id; // 拖拽期间关闭相机控制避免模型和相机同时被拖动 viewer.scene.screenSpaceCameraController.enableRotate false; viewer.scene.screenSpaceCameraController.enableTranslate false; } }, Cesium.ScreenSpaceEventType.LEFT_DOWN); handler.setInputAction(function (movement) { if (!isDragging || !dragEntity) return; const ray viewer.camera.getPickRay(movement.endPosition); if (!Cesium.defined(ray)) return; const globePosition viewer.scene.globe.pick(ray, viewer.scene); if (Cesium.defined(globePosition)) { dragEntity.position globePosition; } }, Cesium.ScreenSpaceEventType.MOUSE_MOVE); handler.setInputAction(function () { if (isDragging) { isDragging false; dragEntity null; viewer.scene.screenSpaceCameraController.enableRotate true; viewer.scene.screenSpaceCameraController.enableTranslate true; } }, Cesium.ScreenSpaceEventType.LEFT_UP);这套代码就是一个最小闭环。但这里有个问题如果模型本身高于地形globe.pick返回的是地形上的点而不是拖拽平面上的点拖起来会感觉“被地形抓住”了。所以下一个关键步骤是选择并实现合适的坐标策略。3.2 代码写完后先验证三件事第一验证是否只拖动了目标模型。鼠标点在场景空白处不能触发拖拽点到其他模型也不能误伤。第二验证模型是否稳定跟随。鼠标移动时模型是否停留在用户预期位置有没有跳动、漂移、穿地、悬空。第三验证拖拽结束后相机是否恢复正常。很多人写完LEFT_UP后忘记恢复cameraController导致场景里所有操作都失灵。如果三个验证都通过再进入旋转和缩放阶段。不要在一开始就追求所有功能。3.3 从拖拽到旋转、缩放姿态和时间线一起管理如果项目需要旋转可以加一个“旋转模式”。比如按住 Shift 拖拽时旋转模型。这里的关键是旋转要基于一个稳定的初始朝向累加而不是每次重设一个固定值。let baseHPR null; // 在进入旋转模式时记录初始朝向 baseHPR new Cesium.HeadingPitchRoll( Cesium.Math.toRadians(45), 0, 0 ); // MOUSE_MOVE 中判断当前是旋转模式 const dx movement.endPosition.x - movement.startPosition.x; const deltaAngle Cesium.Math.toRadians(dx * 0.3); const currentHPR new Cesium.HeadingPitchRoll( baseHPR.heading deltaAngle, baseHPR.pitch, baseHPR.roll ); dragEntity.orientation Cesium.Transforms.headingPitchRollQuaternion( dragEntity.position.getValue(viewer.clock.currentTime), currentHPR );这里的dx * 0.3是一个灵敏度系数实际项目中建议做成配置项。更好的做法是从当前 orientation 反解出初始 HPR而不是像我示例里这样写死一个初始值。缩放也同样可以做成独立模式通过鼠标滚轮控制entity.model.scale。旋转和缩放不建议和位置拖拽绑定在同一次鼠标会话里因为事件判断会变得复杂容易出现“明明想旋转结果位置也变了”的误触发。注意不要试图在一段拖拽事件里同时处理位移、旋转、缩放三种变换。交互模式分开状态管理才可控。4. 真正影响体感的几个细节和避坑点4.1 拖拽“飘”和“跳”的常见原因拖拽看起来“飘”大部分情况不是渲染卡顿而是坐标转换策略没选对。常见原因有这些一直用globe.pick但模型在高层建筑群中地形被遮挡或高程变化大模型就会跳到地上或者穿楼。只处理了MOUSE_MOVE但误用了movement.startPosition导致模型总是滞后一帧。在拖拽过程中直接修改 position没有做clone多个变量引用同一个Cartesian3后续计算把原值也改了。没有关闭深度测试相关配置导致scene.pickPosition拾取到的是屏幕上不稳定的深度点。鼠标移动事件触发频率和设备窗口尺寸有关在高分屏下坐标换算需要按window.devicePixelRatio做校准。4.2 模型穿地 / 悬空要不要做高度修正拖拽贴地模型时常见逻辑是让模型保持贴地。简单做法是在加载 Entity 时设置model: { uri: /models/example.glb, heightReference: Cesium.HeightReference.CLAMP_TO_GROUND }但对于已经指定了明确海拔的模型这个设置会带来相反效果。如果你希望拖拽后始终保持初始高度就不要设置CLAMP_TO_GROUND而是自己维护一个固定高度。移动时可以用模型当前高度沿法线方向重新投影。从工程经验看业务需求通常分成两类装饰物、临时设备希望贴地拖到哪里都贴合地形。精确的设备和建筑希望严格保持原坐标高度不被地形影响。所以不要一上来就写死“贴地”或者“不贴地”要把高度策略做成参数让上层业务自己选择。4.3 旋转缩放时要避免“连带旋转”问题Cesium 的 orientation 是四元数。如果你反复读取再赋值要注意数值稳定性。每次旋转最好基于一个基准 HPR 计算而不是基于上一次旋转后的四元数再转一次否则累积误差会越来越大。另外模型加载后如果设置了model.headingPitchRoll或者model.nodeTransformations你再用entity.orientation去控制姿态两者可能叠加导致旋转结果不符合预期。Cesium 的模型姿态控制有几个入口Entity 级 orientation、ModelGraphics 的 headingPitchRoll、以及 3D Tiles 的 modelMatrix。在一个场景里建议只选一种作为主要控制手段避免多层变换嵌套。4.4 拖拽和相机手势冲突这是新手最容易遇到、也最不容易定位的坑。如果拖拽时没有禁用screenSpaceCameraController会出现“模型移动了同时场景视野也被拖动”的现象。关键是这个现象有时只在特定相机角度下出现排查起来很迷惑。解决方法是进入拖拽会话时关闭相机控制退出时恢复。如果拖拽的是 3D Tiles 对象还要额外注意中键、右键事件和默认操作的冲突。5. 工程化落地排查链路、适用边界和下一步5.1 一个实用的排查顺序遇到拖拽异常不要先改代码。按顺序检查看现象模型是否在鼠标按下后立刻改变位置是否在移动过程中才出错是否在抬起后又回跳看拾取在LEFT_DOWN里打印scene.pick返回值确认是否命中预期对象。看坐标换算单独把ray和globe.pick/ 平面求交的结果打印出来观察目标点是否合理。看事件函数参数检查用的是movement.position还是endPosition/startPosition。看状态清理检查LEFT_UP、窗口失焦、ESC 取消等场景下拖拽状态是否被正确清除。看环境是否有 terrainProvider、是否开启深度测试、是否开启了pickPosition所需开关。这个顺序可以覆盖大部分问题。最容易被忽略的其实是第 5 步用户如果在拖拽过程中按下了窗口切换或者右键LEFT_UP没有触发isDragging一直是 true下一次点击就会继续拖动。建议在window的blur事件或相机事件里做一次状态重置。注意拖拽状态一定要在窗口失焦、ESC 或者右键按下时被清理否则会出现“模型跟着鼠标乱跑”的幽灵拖拽。5.2 这个方案适合什么、不适合什么基于 Entity ScreenSpaceEventHandler 的方案适合单个模型或少量模型的交互编辑需要快速原型验证的室内 / 室外地物摆放需要在浏览器里给用户提供简单“摆放”能力的低交互场景学习 Cesium 交互机制的中级开发流程。它不适合上百个模型并发拖拽并需要实时性能反馈的场景对碰撞检测、约束、网格吸附有严格需求的产品需要撤回 / 重做、多选、编组、批量变换的编辑器型系统3D Tiles 数据量巨大的场景因为频繁修改 modelMatrix 会导致重算量大拖拽响应会明显变慢。可以用这个表来快速判断自己的项目是否需要换方案。项目类型建议方案展示 单模型简单摆放本文的 Entity 拖拽方案多模型编辑工具需要引入状态栈、命令模式、辅助手柄3D Tiles 大场景编辑需要更谨慎的 modelMatrix 更新策略和性能优化需碰撞检测 / 精确约束需要结合物理引擎或空间索引处理如果目标是做一个完整的模型编辑工具还需要补上操作历史栈撤销 / 重做、拖拽预览线、辅助坐标轴手柄、碰撞检测、网格吸附、坐标输入面板、场景序列化。拖拽变换本身只是其中一小环。5.3 把拖拽能力沉淀成一个可复用工具等你把基础拖拽跑通下一步不是继续加功能而是把“变换逻辑”和“具体模型结构”解耦。可以封装一个 TransformController对外暴露三个方法start(entity)、move(cartesian)、end()。内部维护这些状态当前变换模式move / rotate / scale坐标系策略terrain / fixedHeight / screenParallel灵敏度系数相机控制开关事件清理。然后再考虑跟 UI 集成拖拽时是否显示坐标反馈、是否允许键盘微调、是否保存到后端。这样拖拽能力就不只是挂在一个页面里的一段事件代码而是能被复用到多个项目里的一个模块。回到底层判断你要做的不只是“让模型能拖”而是建立一套“用户与三维场景对象交互”的统一逻辑。这也是 Cesium 里从展示走到编辑的常用路径。先跑通最小闭环再根据业务场景选择坐标策略最后把交互模块化这条路比一开始就追求一个华丽的全功能编辑器要稳得多。