做三維 GIS 項目時最常被問到的需求之一就是“這個模型能不能直接用鼠標(biāo)拖一下”包括拖拽移動、旋轉(zhuǎn)朝向、縮放大小。很多新手會被 Cesium 的坐標(biāo)體系和事件機(jī)制勸退一查資料發(fā)現(xiàn)要么是只講加載模型要么是貼一段 200 行的代碼卻完全沒講為什么。這篇文章會從模型交互相關(guān)的核心概念講起結(jié)合完整的可運行示例把三維模型的拖拽、旋轉(zhuǎn)、縮放思路完整拆開幫你在自己的項目里快速落地。如果你正在折騰 Cesium 模型交互、模型姿態(tài)控制或場景編輯功能這篇文章會比較適合你。1. 背景與核心概念1.1 為什么需要拖拽變換在 Web GIS 項目里模型不只是用來“看”的。城市規(guī)劃場景中需要把建筑模型擺放到指定位置園區(qū)管理系統(tǒng)中需要調(diào)整設(shè)備模型的方向來匹配實際朝向數(shù)字孿生項目中操作員經(jīng)常要實時調(diào)整模型的位置和姿態(tài)。如果這些操作都靠輸入坐標(biāo)參數(shù)來改體驗會非常差也很難在演示場景里快速完成調(diào)整。拖拽變換解決的問題非常直接用鼠標(biāo)選中一個模型按住拖動改變位置通過快捷鍵或滾輪調(diào)整旋轉(zhuǎn)角度和縮放比例整個過程所見即所得。這就是三維場景中非常典型的“交互式模型編輯”能力。如果只講概念可能還是有點抽象我們先明確一下本文所說的“拖拽變換”包含三個獨立的能力能力說明常見操作方式平移拖拽改變模型在地圖上的位置鼠標(biāo)左鍵按住模型拖動旋轉(zhuǎn)改變模型的朝向航向、俯仰、翻滾鼠標(biāo)右鍵拖動或快捷鍵組合縮放改變模型的顯示大小鼠標(biāo)滾輪或滑塊這三種操作在 Cesium 中的實現(xiàn)思路不同但核心都依賴坐標(biāo)轉(zhuǎn)換和鼠標(biāo)事件處理下面逐一展開。1.2 Cesium 模型交互的核心對象在動手寫代碼之前先認(rèn)識幾個 Cesium 中負(fù)責(zé)模型交互的關(guān)鍵對象后面所有代碼都和它們相關(guān)。ViewerCesium 的視圖容器負(fù)責(zé)創(chuàng)建三維場景、管理相機(jī)、綁定鼠標(biāo)交互。EntityCesium 中面向數(shù)據(jù)的高層對象可以用來加載三維模型、點、線、面等。對模型來說entity.position控制位置entity.orientation控制姿態(tài)。ModelGraphicsEntity中專門描述三維模型的屬性例如uri模型地址、scale縮放、minimumPixelSize最小像素尺寸等。ScreenSpaceEventHandlerCesium 的鼠標(biāo)事件處理器可以監(jiān)聽單擊、雙擊、鼠標(biāo)移動、滾輪等事件。Camera場景相機(jī)包含pickEllipsoid方法用于把屏幕坐標(biāo)轉(zhuǎn)換成橢球體上的世界坐標(biāo)。這是實現(xiàn)拖拽時最重要的方法之一。從官方提供的示例出發(fā)加載一個 glTF 模型通常只需要幾行代碼const entity viewer.entities.add({ position: Cesium.Cartesian3.fromDegrees(116.39, 39.9, 0), model: { uri: path/to/model.glb, scale: 1 } }); viewer.zoomTo(entity);但加載容易交互難。拖拽變換要解決的核心問題是如何把鼠標(biāo)在屏幕上的二維移動轉(zhuǎn)換成模型在三維世界中的位置、朝向和大小變化。這就是本文接下來要講的重點。2. 環(huán)境準(zhǔn)備與版本說明2.1 開發(fā)環(huán)境本文示例基于 Web 項目使用原生 JavaScript HTML 開發(fā)不涉及框架集成。你只需要準(zhǔn)備好一個支持 WebGL 的現(xiàn)代瀏覽器Chrome、Edge、Firefox 均可。一個文本編輯器或 IDEVSCode 即可。Cesium 庫文件可以用 CDN 引入也可以使用 npm 安裝。一個可用的 glTF/glb 三維模型文件。版本方面需要說明一下Cesium 的 API 在持續(xù)演進(jìn)不同版本的Model、Entity相關(guān)屬性可能有細(xì)微差別。本文示例以 Cesium 1.103 版本為基礎(chǔ)編寫實際項目中請根據(jù)自己使用的版本調(diào)整。2.2 引入 Cesium最簡單的方式是使用 CDN 引入!DOCTYPE html html langzh-CN head meta charsetUTF-8 titleCesium 三維模型拖拽變換/title style html, body, #cesiumContainer { width: 100%; height: 100%; margin: 0; padding: 0; overflow: hidden; } /style link hrefhttps://cdn.jsdelivr.net/npm/cesium1.103/Build/Cesium/Widgets/widgets.css relstylesheet script srchttps://cdn.jsdelivr.net/npm/cesium1.103/Build/Cesium/Cesium.js/script /head body div idcesiumContainer/div /body /html如果你使用的是 Vue、React 等框架也可以通過 npm 安裝npm install cesium1.103然后在框架里使用import * as Cesium from cesium引入?？蚣芗傻臅r候注意 Cesium 的靜態(tài)資源路徑配置例如CESIUM_BASE_URL的設(shè)置否則會出現(xiàn)加載不到資源的問題。2.3 示例項目結(jié)構(gòu)本文的完整示例最終只用一個 HTML 文件 一個模型文件不需要額外的后端服務(wù)model-drag-demo/ ├── index.html └── model/ └── demo.glb如果你本地沒有 glb 模型可以先下載 Cesium 官方示例模型或者使用市場上任何一個 glTF 格式模型調(diào)試。需要提醒的是商用項目請確保模型素材的來源和授權(quán)本文重點在交互實現(xiàn)不對模型內(nèi)容展開。3. 拖拽變換的核心原理3.1 屏幕坐標(biāo)與三維坐標(biāo)的轉(zhuǎn)換實現(xiàn)拖拽第一個要搞明白的是鼠標(biāo)在屏幕上只有 x、y 兩個坐標(biāo)像素坐標(biāo)而三維世界中的模型位置是 x、y、z 三個坐標(biāo)世界坐標(biāo)。鼠標(biāo)拖動時系統(tǒng)需要知道“鼠標(biāo)當(dāng)前位置對應(yīng)三維空間中的哪個點”。Cesium 提供了一系列坐標(biāo)轉(zhuǎn)換方法Cesium.Cartesian2屏幕坐標(biāo)像素坐標(biāo)例如鼠標(biāo)位置。Cesium.Cartesian3三維笛卡爾坐標(biāo)包含 x、y、z。Cesium.Cartographic地理坐標(biāo)經(jīng)度、緯度、高度。viewer.camera.pickEllipsoid(windowPosition)把屏幕坐標(biāo)投影到橢球體表面返回對應(yīng)的Cartesian3世界坐標(biāo)。pickEllipsoid是實現(xiàn)拖拽平移的關(guān)鍵方法。它的原理可以理解為從相機(jī)位置發(fā)射一條射線穿過鼠標(biāo)所在的屏幕像素點與地球橢球體求交得到交點坐標(biāo)。當(dāng)模型在地球表面附近時這個交點就是拖拽時模型應(yīng)該跟隨的目標(biāo)點。3.2 拖拽的數(shù)學(xué)思路平移拖拽的基本邏輯可以拆成三步鼠標(biāo)按下時記錄當(dāng)前屏幕坐標(biāo)和模型當(dāng)前世界坐標(biāo)。鼠標(biāo)移動時通過pickEllipsoid獲取當(dāng)前屏幕坐標(biāo)對應(yīng)的世界坐標(biāo)。根據(jù)鼠標(biāo)移動產(chǎn)生的世界坐標(biāo)偏移量更新模型的位置。這里的偏移量計算有兩種常見思路直接賦值法鼠標(biāo)移動時把pickEllipsoid返回的世界坐標(biāo)直接設(shè)置為模型位置。這種方式操作簡單但模型會“跳”到鼠標(biāo)指向的地球表面點初始點擊的位置和模型中心之間可能有偏差拖拽時模型容易出現(xiàn)突然跳動。增量移動法鼠標(biāo)按下時記錄點擊點的世界坐標(biāo)和模型的世界坐標(biāo)之間的差值鼠標(biāo)移動時用當(dāng)前點的世界坐標(biāo)加上這個差值作為模型新位置。這種方式模型與鼠標(biāo)的相對位置保持不變體驗更好也是本文推薦的方式。旋轉(zhuǎn)和縮放則相對獨立旋轉(zhuǎn)通過修改entity.orientation使用四元數(shù)Quaternion表示模型的姿態(tài)。縮放通過修改entity.model.scale這是一個數(shù)值類型直接改變模型縮放倍數(shù)。3.3 操作模式設(shè)計在三維場景中鼠標(biāo)左鍵默認(rèn)是旋轉(zhuǎn)相機(jī)的操作如果直接讓左鍵拖拽模型會與相機(jī)操作沖突。項目里常用的方案有幾種方案操作方式適用場景左鍵拖拽模型左鍵按住模型拖動相機(jī)鎖定或交互模式切換藍(lán)圖式多按鍵左鍵平移右鍵旋轉(zhuǎn)滾輪縮放模型編輯、場景編輯器熱鍵切換按住 Shift 或 Ctrl 切換拖拽模式避免與相機(jī)操作沖突本文示例采用“選中模式 操作模式”的思路點擊模型后選中鼠標(biāo)在模型上時顯示提示左側(cè)執(zhí)行平移右鍵執(zhí)行旋轉(zhuǎn)滾輪控制縮放。這樣既能保證體驗也方便你理解每一種變換的核心代碼。4. 手寫模型平移拖拽4.1 初始化 Viewer 并加載模型一切從創(chuàng)建一個Viewer開始。為了方便調(diào)試可以關(guān)閉一些默認(rèn)自帶的效果讓場景更干凈const viewer new Cesium.Viewer(cesiumContainer, { animation: false, timeline: false, baseLayerPicker: false, geocoder: false, homeButton: false, sceneModePicker: false, navigationHelpButton: false, infoBox: false, selectionIndicator: false });然后加載模型。為了后面操作方便我們用一個全局變量currentEntity保存當(dāng)前操作的模型let currentEntity null; function loadModel() { const position Cesium.Cartesian3.fromDegrees(116.391, 39.907, 0); currentEntity viewer.entities.add({ position: position, model: { uri: model/demo.glb, scale: 1, minimumPixelSize: 128, maximumScale: 2000 } }); viewer.zoomTo(currentEntity); }minimumPixelSize的作用是保證模型在距離較遠(yuǎn)時也有最小像素尺寸不會被縮得太小導(dǎo)致看不見maximumScale則相反限制模型的最大縮放倍率。這兩個參數(shù)在模型交互時很有用能讓模型始終處于可見和可點擊的狀態(tài)。4.2 拾取模型在 Cesium 中拾取模型有兩種常用方式。第一種是通過viewer.pick方法它返回屏幕坐標(biāo)下被點擊的對象。const handler new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas); handler.setInputAction(function (movement) { const picked viewer.scene.pick(movement.position); if (Cesium.defined(picked) picked.id picked.id currentEntity) { console.log(模型被選中); } }, Cesium.ScreenSpaceEventType.LEFT_CLICK);需要注意viewer.scene.pick返回的對象中id屬性是 primitive 或 entity 的引用。如果是Entity的模型這個id就是該實體本身。第二種拾取方式是viewer.scene.drillPick它可以拾取同一個位置上的多個對象返回一個數(shù)組。當(dāng)場景中模型密集、存在遮擋時drillPick會更靈活。不過對大多數(shù)場景來說pick已經(jīng)夠用。4.3 實現(xiàn)左鍵拖拽平移接下來是重頭戲?qū)崿F(xiàn)鼠標(biāo)左鍵按住模型拖動?；臼录鞒虨長EFT_DOWN鼠標(biāo)左鍵按下判斷是否選中了模型。如果選中進(jìn)入拖拽狀態(tài)并記錄偏移量。MOUSE_MOVE鼠標(biāo)移動如果當(dāng)前處于拖拽狀態(tài)則更新模型位置。LEFT_UP鼠標(biāo)左鍵抬起退出拖拽狀態(tài)。我們需要幾個局部變量來記錄狀態(tài)let isDragging false; let dragOffset new Cesium.Cartesian3(); // 鼠標(biāo)與模型位置的偏移量 let pickedModel null;然后綁定事件。LEFT_DOWN 事件handler.setInputAction(function (movement) { const picked viewer.scene.pick(movement.position); if (!Cesium.defined(picked)) { return; } const pickedEntity picked.id; if (pickedEntity pickedEntity currentEntity) { isDragging true; pickedModel currentEntity; // 獲取點擊位置對應(yīng)的世界坐標(biāo) const cartesian viewer.camera.pickEllipsoid(movement.position, viewer.scene.globe.ellipsoid); if (cartesian) { // 計算點擊點和模型位置之間的偏移 dragOffset Cesium.Cartesian3.subtract( pickedModel.position.getValue(Cesium.JulianDate.now()), cartesian, new Cesium.Cartesian3() ); } } }, Cesium.ScreenSpaceEventType.LEFT_DOWN);這里的關(guān)鍵是dragOffset。它的含義是“模型位置相對于鼠標(biāo)點擊點在地球上的位置”的偏移量。在后續(xù)移動時我們用“當(dāng)前鼠標(biāo)位置對應(yīng)的地球坐標(biāo) dragOffset”作為模型的新位置這樣模型就能始終跟隨鼠標(biāo)并且不會發(fā)生突然跳動。MOUSE_MOVE 事件handler.setInputAction(function (movement) { if (!isDragging || !pickedModel) { return; } const cartesian viewer.camera.pickEllipsoid(movement.endPosition, viewer.scene.globe.ellipsoid); if (!cartesian) { return; } // 用當(dāng)前點 偏移量 作為模型新位置 const newPosition Cesium.Cartesian3.add(cartesian, dragOffset, new Cesium.Cartesian3()); pickedModel.position newPosition; }, Cesium.ScreenSpaceEventType.MOUSE_MOVE);注意movement.endPosition是鼠標(biāo)移動事件結(jié)束時的屏幕坐標(biāo)。使用movement.position在某些場景下也能工作但endPosition是標(biāo)準(zhǔn)寫法。LEFT_UP 事件handler.setInputAction(function () { isDragging false; pickedModel null; }, Cesium.ScreenSpaceEventType.LEFT_UP);到這里一個最基礎(chǔ)的三維模型拖拽平移功能就完成了。有一點特別提醒在拖拽過程中屏幕空間相機(jī)控制器可能也在響應(yīng)鼠標(biāo)操作導(dǎo)致你拖動模型時相機(jī)同時旋轉(zhuǎn)。要解決這個問題可以在拖拽開始后禁用相機(jī)操作拖拽結(jié)束后恢復(fù)// 禁用相機(jī) viewer.scene.screenSpaceCameraController.enableRotate false; viewer.scene.screenSpaceCameraController.enableTranslate false; // 恢復(fù)相機(jī) viewer.scene.screenSpaceCameraController.enableRotate true; viewer.scene.screenSpaceCameraController.enableTranslate true;這在操作體驗上非常重要不處理的話模型拖拽會非常別扭。4.4 為什么使用 pickEllipsoid 而不是拾取地形可能有讀者會問為什么拖拽時不直接使用viewer.scene.pickPosition或者viewer.scene.globe.pick這里簡要說明一下viewer.scene.pickPosition依賴于深度緩沖區(qū)需要場景支持scene.pickPositionSupported在某些設(shè)置下會返回 undefined。viewer.scene.globe.pick只能拾取地球表面的點無法處理建筑物、模型遮擋等情況。viewer.camera.pickEllipsoid是把射線與橢球體求交只要相機(jī)姿勢正?；径紩祷赜行е颠m合做“地面拖拽”操作。如果你的模型不是貼在地面上而是懸浮在空中或者你想要“模型沿某個平面拖動”的效果那就需要自己定義一個平面例如通過Cesium.Plane來做射線求交或者使用Cesium.IntersectionTests系列方法。本文先不展開但知道pickEllipsoid的局限性對后續(xù)深入很有幫助。5. 實現(xiàn)旋轉(zhuǎn)與縮放5.1 旋轉(zhuǎn)模型修改 Orientation在 Cesium 中一個實體的朝向由orientation屬性控制它是四元數(shù)表示的。我們可以通過Cesium.Transforms.headingPitchRollQuaternion方法來生成四元數(shù)。HeadingPitchRoll三個參數(shù)的含義heading航向角繞 Z 軸旋轉(zhuǎn)范圍是 [-PI, PI]簡單理解就是“模型臉朝哪個方向”。pitch俯仰角繞 Y 軸旋轉(zhuǎn)可以理解為“模型抬頭低頭”。roll翻滾角繞 X 軸旋轉(zhuǎn)表示“模型左右翻滾”。一個常用的交互方式是“右鍵拖動旋轉(zhuǎn)”。我們希望在鼠標(biāo)水平移動時改變模型的 heading鼠標(biāo)垂直移動時改變模型的 pitch。實現(xiàn)思路是右鍵按下時記錄當(dāng)前模型的headingPitchRoll和鼠標(biāo)起始位置。右鍵拖動時根據(jù)鼠標(biāo)橫向和縱向的像素位移計算 heading 和 pitch 的變化量。用新的 heading、pitch、roll 生成四元數(shù)并賦值給entity.orientation。代碼片段如下let isRotating false; let lastHeading 0; let lastPitch 0; let lastRoll 0; let lastMouseX 0; let lastMouseY 0; // 右鍵按下 handler.setInputAction(function (movement) { const picked viewer.scene.pick(movement.position); if (!Cesium.defined(picked) || picked.id ! currentEntity) { return; } isRotating true; const hpr getEntityHPR(currentEntity); lastHeading hpr.heading; lastPitch hpr.pitch; lastRoll hpr.roll; lastMouseX movement.position.x; lastMouseY movement.position.y; }, Cesium.ScreenSpaceEventType.RIGHT_DOWN); // 鼠標(biāo)移動 handler.setInputAction(function (movement) { if (!isRotating) { return; } const deltaX movement.endPosition.x - lastMouseX; const deltaY movement.endPosition.y - lastMouseY; const newHeading lastHeading deltaX * 0.01; const newPitch lastPitch deltaY * 0.01; const hpr new Cesium.HeadingPitchRoll(newHeading, newPitch, lastRoll); const orientation Cesium.Transforms.headingPitchRollQuaternion( currentEntity.position.getValue(Cesium.JulianDate.now()), hpr ); currentEntity.orientation orientation; }, Cesium.ScreenSpaceEventType.MOUSE_MOVE); // 右鍵抬起 handler.setInputAction(function () { isRotating false; }, Cesium.ScreenSpaceEventType.RIGHT_UP);輔助函數(shù)getEntityHPR可以在旋轉(zhuǎn)開始前讀取當(dāng)前模型的姿態(tài)角function getEntityHPR(entity) { const position entity.position.getValue(Cesium.JulianDate.now()); const orientation entity.orientation.getValue(Cesium.JulianDate.now()); // 如果 orientation 為空默認(rèn)朝向正北方 if (!Cesium.defined(orientation)) { return new Cesium.HeadingPitchRoll(0, 0, 0); } // 使用 Transforms 的四元數(shù)轉(zhuǎn) HPR const hpr Cesium.Transforms.headingPitchRollQuaternion(position, new Cesium.HeadingPitchRoll(0, 0, 0)); // 這里簡化處理如果希望精確還原 HPR需要計算矩陣 // 實際項目中建議在保存模型狀態(tài)時直接記錄 HPR而不是從四元數(shù)反推 return new Cesium.HeadingPitchRoll(0, 0, 0); }這里需要誠實說明一個實際開發(fā)中的問題Cesium 原生 API 沒有直接提供從四元數(shù)反推 HPR 的簡便方法雖然可以通過矩陣運算實現(xiàn)但代碼相對復(fù)雜。更穩(wěn)妥的做法是在模型初始加載時保存一個currentHPR對象之后每次旋轉(zhuǎn)操作都基于這個對象更新。這樣既保證可控性也簡化了代碼。所以在實際項目中更推薦維護(hù)一份模型狀態(tài)let currentHPR new Cesium.HeadingPitchRoll(0, 0, 0); // 旋轉(zhuǎn)開始時 currentHPR.heading 0; currentHPR.pitch 0; currentHPR.roll 0; // 旋轉(zhuǎn)移動時 const newHPR new Cesium.HeadingPitchRoll( currentHPR.heading deltaX * 0.01, currentHPR.pitch deltaY * 0.01, currentHPR.roll ); const orientation Cesium.Transforms.headingPitchRollQuaternion( currentEntity.position.getValue(Cesium.JulianDate.now()), newHPR ); currentEntity.orientation orientation;這種“狀態(tài)模型”的方式在模型編輯類項目中很重要因為你不只是需要顯示效果還需要在某個時刻“確定”模型的新姿態(tài)并把它保存下來。5.2 縮放模型修改 Model.scale縮放相對簡單直接監(jiān)聽鼠標(biāo)滾輪事件handler.setInputAction(function (movement) { const picked viewer.scene.pick(movement.position); if (!Cesium.defined(picked) || picked.id ! currentEntity) { return; } const scale currentEntity.model.scale.getValue(); const newScale movement.endPosition ? scale * 1.1 : scale * 0.9; currentEntity.model.scale newScale; }, Cesium.ScreenSpaceEventType.WHEEL);movement對象中包含startPosition和endPosition在滾輪事件里用來判斷滾動方向。這里我們簡單把它處理為滾輪向上放大 10%向下縮小 10%。需要注意currentEntity.model.scale在 Cesium 中是一個Property在某些版本中需要用.getValue()讀取當(dāng)前值用賦值方式寫入新值。如果你的 Cesium 版本較老可能需要改為currentEntity.model.scale newScale直接賦值建議以實際版本為準(zhǔn)。5.3 組合操作與模式提示為了讓用戶知道當(dāng)前模型處于“可編輯”狀態(tài)可以在選中模型時改變一個提示區(qū)域的內(nèi)容#tips { position: absolute; top: 20px; left: 50%; transform: translateX(-50%); padding: 8px 20px; background: rgba(0, 0, 0, 0.7); color: #fff; border-radius: 6px; font-size: 14px; pointer-events: none; z-index: 999; }div idtips左鍵拖拽移動模型 | 右鍵拖拽旋轉(zhuǎn)模型 | 滾輪縮放模型/div選中模型時把提示內(nèi)容更新為“當(dāng)前選中模型”未選中時保持默認(rèn)提示。這樣用戶就能清楚地知道當(dāng)前操作模式。6. 完整示例代碼為了方便你直接運行把上面所有內(nèi)容整合成一個完整的 HTML 頁面。你只需要準(zhǔn)備一個 glb 模型文件并修改MODEL_URL即可。!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleCesium 三維模型拖拽變換完整示例/title style html, body, #cesiumContainer { width: 100%; height: 100%; margin: 0; padding: 0; overflow: hidden; font-family: Microsoft YaHei, sans-serif; } #tips { position: absolute; top: 20px; left: 50%; transform: translateX(-50%); padding: 8px 20px; background: rgba(0, 0, 0, 0.75); color: #fff; border-radius: 6px; font-size: 14px; pointer-events: none; z-index: 999; white-space: nowrap; } #status { position: absolute; bottom: 20px; left: 20px; padding: 6px 12px; background: rgba(0, 0, 0, 0.6); color: #ddd; border-radius: 4px; font-size: 12px; z-index: 999; pointer-events: none; } /style link hrefhttps://cdn.jsdelivr.net/npm/cesium1.103/Build/Cesium/Widgets/widgets.css relstylesheet script srchttps://cdn.jsdelivr.net/npm/cesium1.103/Build/Cesium/Cesium.js/script /head body div idcesiumContainer/div div idtips左鍵拖拽模型移動 · 右鍵拖拽旋轉(zhuǎn) · 滾輪縮放/div div idstatus未選中模型/div script // 你的模型地址替換為實際路徑 const MODEL_URL model/demo.glb; const viewer new Cesium.Viewer(cesiumContainer, { animation: false, timeline: false, baseLayerPicker: false, geocoder: false, homeButton: false, sceneModePicker: false, navigationHelpButton: false, infoBox: false, selectionIndicator: false, shouldAnimate: true }); // 視野定位到北京 viewer.camera.flyTo({ destination: Cesium.Cartesian3.fromDegrees(116.391, 39.907, 500), orientation: { heading: 0, pitch: Cesium.Math.toRadians(-30), roll: 0 } }); let currentEntity null; // 加載模型 function loadModel() { const position Cesium.Cartesian3.fromDegrees(116.391, 39.907, 30); currentEntity viewer.entities.add({ position: position, orientation: Cesium.Transforms.headingPitchRollQuaternion( position, new Cesium.HeadingPitchRoll(0, 0, 0) ), model: { uri: MODEL_URL, scale: 1, minimumPixelSize: 64, maximumScale: 5000 } }); viewer.zoomTo(currentEntity, new Cesium.HeadingPitchRange(0, Cesium.Math.toRadians(-35), 200)); } // 拖拽狀態(tài)管理 let isDragging false; let isRotating false; let dragOffset new Cesium.Cartesian3(); let pickedModel null; let currentHPR new Cesium.HeadingPitchRoll(0, 0, 0); let lastMouseX 0; let lastMouseY 0; const handler new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas); // 左鍵拖拽平移 handler.setInputAction(function (movement) { const picked viewer.scene.pick(movement.position); if (!Cesium.defined(picked) || picked.id ! currentEntity) { return; } isDragging true; pickedModel currentEntity; document.getElementById(status).textContent 拖拽移動中...; // 拖拽時禁用相機(jī)操作避免沖突 viewer.scene.screenSpaceCameraController.enableRotate false; viewer.scene.screenSpaceCameraController.enableTranslate false; const cartesian viewer.camera.pickEllipsoid(movement.position, viewer.scene.globe.ellipsoid); if (cartesian) { const currentPosition currentEntity.position.getValue(Cesium.JulianDate.now()); dragOffset Cesium.Cartesian3.subtract( currentPosition, cartesian, new Cesium.Cartesian3() ); } }, Cesium.ScreenSpaceEventType.LEFT_DOWN); handler.setInputAction(function (movement) { if (!isDragging || !pickedModel) { return; } const cartesian viewer.camera.pickEllipsoid(movement.endPosition, viewer.scene.globe.ellipsoid); if (!cartesian) { return; } const newPosition Cesium.Cartesian3.add(cartesian, dragOffset, new Cesium.Cartesian3()); pickedModel.position newPosition; }, Cesium.ScreenSpaceEventType.MOUSE_MOVE); handler.setInputAction(function () { if (isDragging) { isDragging false; pickedModel null; document.getElementById(status).textContent 已選中模型; // 恢復(fù)相機(jī)操作 viewer.scene.screenSpaceCameraController.enableRotate true; viewer.scene.screenSpaceCameraController.enableTranslate true; } }, Cesium.ScreenSpaceEventType.LEFT_UP); // 右鍵旋轉(zhuǎn)模型 handler.setInputAction(function (movement) { const picked viewer.scene.pick(movement.position); if (!Cesium.defined(picked) || picked.id ! currentEntity) { return; } isRotating true; document.getElementById(status).textContent 旋轉(zhuǎn)模型中...; // 從當(dāng)前狀態(tài)讀取 HPR這里使用我們維護(hù)的 currentHPR // 實際項目中可以從模型屬性中讀取或統(tǒng)一存儲 lastMouseX movement.position.x; lastMouseY movement.position.y; }, Cesium.ScreenSpaceEventType.RIGHT_DOWN); handler.setInputAction(function (movement) { if (!isRotating || !currentEntity) { return; } const deltaX movement.endPosition.x - lastMouseX; const deltaY movement.endPosition.y - lastMouseY; currentHPR.heading deltaX * 0.01; currentHPR.pitch deltaY * 0.01; const position currentEntity.position.getValue(Cesium.JulianDate.now()); const orientation Cesium.Transforms.headingPitchRollQuaternion(position, currentHPR); currentEntity.orientation orientation; lastMouseX movement.endPosition.x; lastMouseY movement.endPosition.y; }, Cesium.ScreenSpaceEventType.MOUSE_MOVE); handler.setInputAction(function () { if (isRotating) { isRotating false; document.getElementById(status).textContent 已選中模型; } }, Cesium.ScreenSpaceEventType.RIGHT_UP); // 滾輪縮放模型 handler.setInputAction(function (movement) { const picked viewer.scene.pick(movement.position); if (!Cesium.defined(picked) || picked.id ! currentEntity) { return; } const currentScale currentEntity.model.scale.getValue(); let newScale; if (movement.endPosition) { // 滾輪向上放大 newScale currentScale * 1.1; } else { // 滾輪向下縮小 newScale currentScale * 0.9; } newScale Math.max(0.1, Math.min(100, newScale)); currentEntity.model.scale newScale; document.getElementById(status).textContent 當(dāng)前縮放 newScale.toFixed(2); }, Cesium.ScreenSpaceEventType.WHEEL); // 初始化 loadModel(); /script /body /html這個示例基本覆蓋了 90% 的常規(guī)需求。直接打開頁面加載自己的 glb 模型后就能按住鼠標(biāo)左鍵移動模型右鍵拖動旋轉(zhuǎn)滾動滾輪縮放模型。7. 常見問題與排查思路在實際開發(fā)中拖拽交互經(jīng)常遇到各種“奇怪”的問題。下面把高頻問題的排查思路整理成一個清單方便你在項目里對照檢查。問題現(xiàn)象常見原因解決思路點擊模型時沒有拾取到實體模型在場景中被其他對象遮擋或者屏幕坐標(biāo)系有偏差檢查相機(jī)位置使用console.log(picked)輸出拾取結(jié)果或改用drillPick查看是否拾取到了其他對象拖拽時模型跳動明顯沒有使用增量移動直接賦值導(dǎo)致模型位置跳變使用本文的dragOffset方案計算偏移量再更新位置拖拽時相機(jī)跟著旋轉(zhuǎn)沒有在拖拽期間禁用相機(jī)控制器在拖拽開始/結(jié)束時設(shè)置screenSpaceCameraController.enableRotate和enableTranslate模型拖不動鼠標(biāo)沒有真正拾取到模型或者模型沒有minimumPixelSize設(shè)置minimumPixelSize: 64避免模型像素過小難以點選檢查模型加載是否成功旋轉(zhuǎn)時模型翻轉(zhuǎn)異常heading、pitch、roll 累加時沒有統(tǒng)一處理邊界對角度做歸一化處理例如限制 heading 在 [-PI, PI] 范圍縮放時模型直接消失scale 設(shè)置得過大或過小加入范圍限制例如Math.max(0.1, Math.min(100, newScale))Entity 拾取不到但模型正常顯示Entity 的show狀態(tài)或模型未加載完成在viewer.clock或tileLoad事件后延遲綁定交互使用 Vue/React 時Cesium 報錯找不到資源CESIUM_BASE_URL 配置錯誤npm 方式引用時需要把 Cesium 的靜態(tài)資源目錄復(fù)制到項目并設(shè)置全局window.CESIUM_BASE_URL滾輪事件同時觸發(fā)了頁面滾動頁面高度超出視口在容器樣式上使用overflow: hidden或監(jiān)聽事件時調(diào)用preventDefault除了表格里的問題還有兩個比較隱蔽的坑值得單獨拿出來說?？右皇叭〉氖?primitive不是 entity如果你的項目中同時存在PrimitiveAPI 加載的模型和EntityAPI 加載的模型scene.pick返回的id類型可能不一樣。很多人在初始化時沒有區(qū)分導(dǎo)致判斷條件不成立。建議在代碼里統(tǒng)一做判斷if (picked.id instanceof Cesium.Entity) { // entity 方式 }坑二模型加載完成前無法點擊如果你的模型是異步加載的在模型資源還沒有完全加載完成時點擊scene.pick可能返回 undefined。這種情況在本地局域網(wǎng)部署時幾乎不會出現(xiàn)但在網(wǎng)絡(luò)較差的演示環(huán)境里經(jīng)常遇到。建議監(jiān)聽模型加載完成事件例如viewer.scene.clippingPlanes或者直接使用tileLoad事件也可以簡化處理模型加載后延時 1 秒再允許交互。8. 最佳實踐與工程建議8.1 狀態(tài)管理與數(shù)據(jù)保存拖拽變換不僅是“視覺上動了”更重要的是業(yè)務(wù)上要保得住。實際項目中不要直接去操作viewer.entities而是建議維護(hù)一份獨立的模型狀態(tài)對象例如const modelState { id: model_001, position: { longitude: 116.391, latitude: 39.907, height: 30 }, heading: 0, pitch: 0, roll: 0, scale: 1 };每次拖拽、旋轉(zhuǎn)、縮放結(jié)束時同步更新modelState再把最終數(shù)據(jù)提交給后端。這樣做有幾個好處程序運行期間不依賴 Cesium 對象就能獲取模型狀態(tài)。保存到數(shù)據(jù)庫時只需要轉(zhuǎn)換一次坐標(biāo)格式。支持多視圖同步、撤銷恢復(fù)等復(fù)雜功能。設(shè)計交互模式時建議區(qū)分“臨時調(diào)整”和“確定修改”?？梢杂秒p擊模型確認(rèn)變更用 Esc 鍵取消當(dāng)前操作。真正做生產(chǎn)項目時模型編輯往往會有“保存”“取消”按鈕而不是每次操作都立刻寫入數(shù)據(jù)庫。8.2 性能優(yōu)化單個模型的拖拽通常不會造成性能瓶頸但如果你在編輯一個很大的場景包含幾十上百個模型就需要考慮一些性能策略拖拽過程中不要頻繁調(diào)用viewer.scene.renderCesium 默認(rèn)的渲染循環(huán)已經(jīng)足夠。不要每次移動都去查詢某個 Primitive 的矩陣盡量在內(nèi)存中維護(hù)好當(dāng)前值。如果模型中包含大量動畫節(jié)點拖拽過程中可以臨時關(guān)閉動畫更新減少 CPU 開銷。大批量模型編輯時優(yōu)先考慮PrimitiveAPI 或者EntityCluster避免創(chuàng)建過多 Entity 對象。8.3 交互體驗細(xì)節(jié)項目上線后用戶反饋最多的往往不是功能是否實現(xiàn)而是“好不好用”。下面幾個細(xì)節(jié)可以明顯提升體驗選中高亮模型被選中時可以給模型添加輪廓線或修改模型顏色讓用戶明確知道當(dāng)前操作對象。拖拽吸附在規(guī)劃類項目中拖拽模型時可以增加網(wǎng)格吸附、角度吸附功能幫助用戶更精確地擺放模型。操作回顯拖拽過程中實時顯示坐標(biāo)、朝向、縮放數(shù)據(jù)方便微調(diào)。右鍵菜單在模型上提供右鍵菜單放置“復(fù)制”“刪除”“屬性”等功能入口減少用戶的記憶成本。8.4 代碼結(jié)構(gòu)建議如果你要在大型項目中落地建議不要把所有代碼堆在一個文件里。可以按職責(zé)拆分src/ ├── viewer/ # Viewer 初始化 ├── entity/ # 模型加載與狀態(tài)管理 ├── interaction/ # 鼠標(biāo)事件綁定 │ ├── drag.js # 平移拖拽 │ ├── rotate.js # 旋轉(zhuǎn) │ └── scale.js # 縮放 └── utils/ └── coordinate.js # 坐標(biāo)轉(zhuǎn)換這樣拆分之后每個模塊職責(zé)單一調(diào)試和測試都會輕松很多。拖拽、旋轉(zhuǎn)、縮放這三個交互未來如果需要支持觸屏設(shè)備或多用戶協(xié)同也能更快地替換和擴(kuò)展。最后想說的是三維場景的模型交互往往沒有“唯一標(biāo)準(zhǔn)答案”。不同業(yè)務(wù)場景對操作方式的需求差異很大有的需要模型貼地拖拽有的需要模型在垂直面上移動有的需要模型沿指定路徑滑動。理解了坐標(biāo)轉(zhuǎn)換、射線求交和狀態(tài)管理這三個核心點其他各種變體其實都能自己寫出來。希望這篇文章能幫你跨過 Cesium 模型交互的第一道門檻少走一些彎路。