很多人在 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 里从展示走到编辑的常用路径。先跑通最小闭环，再根据业务场景选择坐标策略，最后把交互模块化，这条路比一开始就追求一个华丽的全功能编辑器要稳得多。
