建鳥瞰視角地圖相機控制的完整實踐)
three.js MapControls 指南構(gòu)建鳥瞰視角地圖相機控制的完整實踐【免費下載鏈接】three.jsJavaScript 3D Library.項目地址: https://gitcode.com/GitHub_Trending/th/three.jsMapControls 是 three.js 中專門用于鳥瞰birds eye視角地圖相機操控的控制器它繼承了 OrbitControls 的全部軌道控制能力但通過一套「左鍵平移、右鍵/雙鍵旋轉(zhuǎn)、滾輪縮放」的預(yù)設(shè)交互映射并默認關(guān)閉屏幕空間平移使相機在保持垂直俯視的同時沿世界水平面自由移動。本文將從 API 文檔出發(fā)結(jié)合倉庫源碼與官方示例完整講解 MapControls 的導(dǎo)入、構(gòu)造、交互映射、關(guān)鍵屬性、與 OrbitControls 的差異以及底層平移實現(xiàn)原理幫助你在地圖瀏覽、GIS 可視化、大場景漫游等場景中直接落地使用。MapControls 是什么繼承關(guān)系與設(shè)計目標根據(jù) MapControls.html.md 的說明MapControls 的繼承鏈為EventDispatcher → Controls → OrbitControls → MapControls它「與 OrbitControls 共享實現(xiàn)但使用特定的鼠標/觸摸交互預(yù)設(shè)并默認禁用屏幕空間平移」。核心意圖非常明確在俯視地圖場景中旋轉(zhuǎn)通常只是微調(diào)視角而非環(huán)繞觀察用戶最頻繁的操作是平移與縮放。因此 MapControls 把鼠標左鍵從 OrbitControls 的「旋轉(zhuǎn)」改成了「平移」右鍵仍負責旋轉(zhuǎn)滾輪負責縮放。從源碼 examples/jsm/controls/MapControls.js 可以看到MapControls類繼承OrbitControls構(gòu)造函數(shù)中僅重設(shè)了三個屬性其余軌道、縮放、阻尼、自動旋轉(zhuǎn)等能力全部復(fù)用父類class MapControls extends OrbitControls { constructor( object, domElement ) { super( object, domElement ); this.screenSpacePanning false; this.mouseButtons { LEFT: MOUSE.PAN, MIDDLE: MOUSE.DOLLY, RIGHT: MOUSE.ROTATE }; this.touches { ONE: TOUCH.PAN, TWO: TOUCH.DOLLY_ROTATE }; this._panWorldStart new Vector3(); } // 覆蓋 _handleMouseDownPan / _handleMouseMovePan實現(xiàn)沿世界水平面的精確平移 // ... }由此可見 MapControls 本質(zhì)是「OrbitControls 的配置化子類」這也決定了它可以使用 OrbitControls 的幾乎全部屬性與方法詳見下文。安裝與導(dǎo)入MapControls 屬于 three.js 的addon附加組件需要顯式導(dǎo)入不會包含在核心構(gòu)建產(chǎn)物中。以 ES Module 方式導(dǎo)入import { MapControls } from three/addons/controls/MapControls.js;在官方示例 examples/misc_controls_map.html 中導(dǎo)入方式與 import map 配置保持一致script typeimportmap { imports: { three: ../build/three.module.js, three/addons/: ./jsm/ } } /script script typemodule import * as THREE from three; import { MapControls } from three/addons/controls/MapControls.js; // ... /script如果你的項目通過 npm 安裝 three則使用import { MapControls } from three/addons/controls/MapControls.js即可three/addons/映射到包內(nèi)的examples/jsm/目錄?？焖偕鲜肿钚】蛇\行示例下面整合 examples/misc_controls_map.html 的核心骨架給出一個完整的 MapControls 使用示例import * as THREE from three; import { MapControls } from three/addons/controls/MapControls.js; const scene new THREE.Scene(); const camera new THREE.PerspectiveCamera( 60, window.innerWidth / window.innerHeight, 1, 1000 ); camera.position.set( 0, 200, - 200 ); const renderer new THREE.WebGLRenderer( { antialias: true } ); renderer.setSize( window.innerWidth, window.innerHeight ); document.body.appendChild( renderer.domElement ); // 創(chuàng)建地圖控制器 const controls new MapControls( camera, renderer.domElement ); // 啟用阻尼慣性營造重量感 controls.enableDamping true; controls.dampingFactor 0.05; // 平移保持沿世界水平面MapControls 默認值此處顯式聲明 controls.screenSpacePanning false; // 限制俯仰角防止視角鉆到地圖下方 controls.maxPolarAngle Math.PI / 2; // 限制縮放距離范圍 controls.minDistance 100; controls.maxDistance 500; // 動畫循環(huán)啟用阻尼后必須每幀調(diào)用 update() renderer.setAnimationLoop( animate ); function animate() { controls.update(); renderer.render( scene, camera ); }要點說明構(gòu)造參數(shù)new MapControls( object, domElement )其中object是被控制器管理的相機Object3DdomElement是接收事件監(jiān)聽的 HTML 元素通常為renderer.domElement可省略。update()的調(diào)用時機與 OrbitControls 一致若enableDamping或autoRotate為true必須在動畫循環(huán)中每幀調(diào)用controls.update()若兩者都關(guān)閉則只需在手動修改相機變換后調(diào)用一次見 OrbitControls.html.md 的 Code Example 說明。示例中通過renderer.setAnimationLoop( animate )驅(qū)動渲染同時響應(yīng)窗口縮放事件時需更新camera.aspect與renderer.setSize()。交互映射鼠標、鍵盤與觸摸MapControls 文檔明確規(guī)定的交互預(yù)設(shè)如下操作鼠標觸摸對應(yīng)動作旋轉(zhuǎn)Orbit右鍵或 左鍵 ctrl/meta/shiftKey雙指旋轉(zhuǎn)ROTATE縮放Zoom中鍵或 滾輪雙指捏合/張開DOLLY平移Pan左鍵或 方向鍵單指拖動PAN鼠標映射源碼MapControls 在構(gòu)造函數(shù)中將 src/constants.js 中定義的MOUSE常量MOUSE { LEFT: 0, MIDDLE: 1, RIGHT: 2, ROTATE: 0, DOLLY: 1, PAN: 2 }映射為controls.mouseButtons { LEFT: MOUSE.PAN, // 左鍵平移 MIDDLE: MOUSE.DOLLY, // 中鍵推拉縮放 RIGHT: MOUSE.ROTATE // 右鍵旋轉(zhuǎn) }這與 OrbitControls 的默認映射左鍵旋轉(zhuǎn)、右鍵平移恰好對調(diào)了LEFT與RIGHT的角色。觸摸映射源碼TOUCH常量定義為TOUCH { ROTATE: 0, PAN: 1, DOLLY_PAN: 2, DOLLY_ROTATE: 3 }見 src/constants.jsMapControls 的觸摸預(yù)設(shè)為controls.touches { ONE: TOUCH.PAN, // 單指平移 TWO: TOUCH.DOLLY_ROTATE // 雙指捏合縮放 旋轉(zhuǎn) }與 OrbitControls 默認的ONE: ROTATE, TWO: DOLLY_PAN相比同樣是「單指操作從旋轉(zhuǎn)改為平移」完全貼合地圖應(yīng)用的直覺。注意文檔示例代碼中觸摸塊寫作controls.mouseButtons { ONE: ... , TWO: ... }實為文檔筆誤正確寫法是controls.touches { ONE: ..., TWO: ... }以 MapControls.js 源碼為準。鍵盤平移鍵盤方向鍵平移能力繼承自 OrbitControls 的keys屬性默認ArrowLeft/ArrowUp/ArrowRight/ArrowDown與keyPanSpeed默認7像素/次并需通過controls.listenToKeyEvents( domElement )注冊鍵盤監(jiān)聽推薦傳入window。因此「方向鍵平移」這一交互開箱即用無需額外配置。關(guān)鍵屬性詳解被覆蓋的三個屬性MapControls 只重寫了以下三個屬性這是它與 OrbitControls 的全部差異所在.screenSpacePanning : boolean默認false。當為false時相機在垂直于camera.up的世界平面上平移即沿世界水平面移動與屏幕傾斜無關(guān)當為true時則沿屏幕空間平移。地圖場景中設(shè)置為false可保證平移時不會出現(xiàn)鏡頭沿屏幕法線方向「飄移」的違和感。.mouseButtons : Object{ LEFT: MOUSE.PAN, MIDDLE: MOUSE.DOLLY, RIGHT: MOUSE.ROTATE }見上文交互表。.touches : Object{ ONE: TOUCH.PAN, TWO: TOUCH.DOLLY_ROTATE }見上文交互表。三者均可隨時在運行時修改例如把鼠標右鍵也改為平移controls.mouseButtons.RIGHT THREE.MOUSE.PAN;從 OrbitControls 繼承的常用屬性MapControls 未重寫、但完全可用的父類屬性見 OrbitControls.html.md屬性默認值作用.target : Vector3(0,0,0)相機圍繞的焦點可手動修改以改變聚焦點.enableDampingfalse啟用阻尼/慣性需要循環(huán)調(diào)用update().dampingFactor0.05阻尼系數(shù)越小慣性越大.minDistance/.maxDistance0/Infinity透視相機可推近/拉遠的最小/最大距離.minZoom/.maxZoom0/Infinity正交相機縮放范圍.minPolarAngle/.maxPolarAngle0/Math.PI垂直旋轉(zhuǎn)俯仰角度限制單位弧度.minAzimuthAngle/.maxAzimuthAngle-Infinity/-Infinity水平旋轉(zhuǎn)角度限制子區(qū)間需滿足max - min 2π.enablePan/.enableRotate/.enableZoomtrue分別開關(guān)平移、旋轉(zhuǎn)、縮放.autoRotate/.autoRotateSpeedfalse/2自動圍繞 target 旋轉(zhuǎn)開啟需每幀update().rotateSpeed/.zoomSpeed/.panSpeed1旋轉(zhuǎn)/縮放/平移速度系數(shù).keyPanSpeed7方向鍵每次按下的平移像素量.zoomToCursorfalse置true后縮放以光標位置為中心.cursor(0,0,0)minTargetRadius/maxTargetRadius的焦點.minTargetRadius/.maxTargetRadius0/Infinitytarget 到 cursor 的距離限制官方示例中對這些繼承屬性的典型組合用法examples/misc_controls_map.htmlcontrols.enableDamping true; controls.dampingFactor 0.05; controls.screenSpacePanning false; controls.minDistance 100; controls.maxDistance 500; controls.maxPolarAngle Math.PI / 2; // 限制俯仰角不超過水平面防止視角鉆入地下示例還用 lil-gui 暴露了zoomToCursor與screenSpacePanning兩個開關(guān)方便實時對比地圖模式與自由模式的行為差異。與 OrbitControls 的對比與相互切換維度OrbitControlsMapControls繼承Controls的直接子類OrbitControls的子類左鍵旋轉(zhuǎn)平移右鍵平移旋轉(zhuǎn)單指觸摸旋轉(zhuǎn)平移screenSpacePanningtruefalse適用場景3D 對象環(huán)繞查看俯視地圖/大場景瀏覽由于兩者 API 高度一致你可以在運行時直接替換控制器類或在mouseButtons/touches/screenSpacePanning三個屬性上手動對齊實現(xiàn)「地圖模式 ? 軌道模式」的無縫切換// 從地圖模式切回軌道模式 controls.mouseButtons { LEFT: THREE.MOUSE.ROTATE, MIDDLE: THREE.MOUSE.DOLLY, RIGHT: THREE.MOUSE.PAN }; controls.touches { ONE: THREE.TOUCH.ROTATE, TWO: THREE.TOUCH.DOLLY_PAN }; controls.screenSpacePanning true;源碼級原理為什么screenSpacePanning false能讓平移貼地父類中的兩種平移數(shù)學(xué)OrbitControls 中平移的核心是_panLeft與_panUp兩個私有方法examples/jsm/controls/OrbitControls.js。_panUp根據(jù)screenSpacePanning選擇不同方向向量_panUp( distance, objectMatrix ) { if ( this.screenSpacePanning true ) { _v.setFromMatrixColumn( objectMatrix, 1 ); // 使用相機矩陣的 Y 列屏幕豎直方向 } else { _v.setFromMatrixColumn( objectMatrix, 0 ); // 使用相機矩陣的 X 列 _v.crossVectors( this.object.up, _v ); // 叉乘 camera.up得到水平面內(nèi)的垂直方向 } _v.multiplyScalar( distance ); this._panOffset.add( _v ); }screenSpacePanning true豎直平移向量取相機局部 Y 軸鏡頭傾斜時平移會帶有「前后」分量screenSpacePanning false豎直平移向量為camera.up與相機 X 軸的叉積始終位于camera.up法線平面上即默認camera.up Y時嚴格沿世界水平面。MapControls 的平面求交平移除了屬性默認值MapControls 還覆蓋了平移的兩個事件處理函數(shù)MapControls.js。在screenSpacePanning false時_handleMouseDownPan會構(gòu)造一個以camera.up為法線、過target點的平面并記錄鼠標射線與該平面的首個交點作為起點_plane.setFromNormalAndCoplanarPoint( this.object.up, this.target ); _raycaster.setFromCamera( _mouse, this.object ); _raycaster.ray.intersectPlane( _plane, this._panWorldStart );拖動過程中_handleMouseMovePan每幀重新求交得到當前點與起點求差后取反寫入_panOffset再調(diào)用this.update()if ( _raycaster.ray.intersectPlane( _plane, _panCurrent ) ) { _panCurrent.sub( this._panWorldStart ); this._panOffset.copy( _panCurrent ).negate(); this.update(); }這意味著 MapControls 的鼠標平移不是簡單的像素偏移換算而是把鼠標世界射線與水平面的交點作為錨點——即使相機帶有俯仰角平移量也是地圖平面上的真實位移視覺上表現(xiàn)為「抓住地圖拖動」這正是地圖應(yīng)用需要的體驗。模塊級復(fù)用的_plane、_raycaster、_mouse、_panCurrent均為共享臨時對象避免頻繁分配內(nèi)存。事件與狀態(tài)管理MapControls 從父類繼承三個事件通過EventDispatcher派發(fā)見 OrbitControls.html.md 的 Events 章節(jié)change相機被控制器變換后觸發(fā)start交互開始時觸發(fā)end交互結(jié)束時觸發(fā)。典型用法靜態(tài)場景可借助change事件按需重繪避免持續(xù)渲染controls.addEventListener( change, () renderer.render( scene, camera ) ); controls.addEventListener( start, () console.log( interaction started ) ); controls.addEventListener( end, () console.log( interaction ended ) );狀態(tài)管理方面saveState()記錄當前position0/target0/zoom0reset()恢復(fù)到該狀態(tài)或初始狀態(tài)編程式操作可使用rotateLeft( angle )、rotateUp( angle )、pan( deltaX, deltaY )、dollyIn( scale )、dollyOut( scale )等方法并可用getPolarAngle()、getAzimuthalAngle()、getDistance()讀取當前姿態(tài)。實戰(zhàn)建議務(wù)必限制俯仰角地圖場景中設(shè)置controls.maxPolarAngle Math.PI / 2甚至更小防止用戶把視角轉(zhuǎn)到地面以下或完全水平。設(shè)置縮放距離范圍結(jié)合場景尺寸配置minDistance/maxDistance正交相機用minZoom/maxZoom避免鏡頭穿?；蚶h后丟失目標。阻尼提升手感enableDamping true后平移/縮放帶慣性更符合地圖 App 的操作直覺但切記每幀調(diào)用update()。監(jiān)聽 resize窗口變化時更新camera.aspect與renderer.setSize()參考 examples/misc_controls_map.html 的onWindowResize。按需切換zoomToCursor希望縮放以鼠標位置為錨點類似主流地圖應(yīng)用時將其設(shè)為true。小結(jié)MapControls 通過「繼承 預(yù)設(shè)」的方式把 OrbitControls 一鍵改造成適合鳥瞰地圖場景的控制器左鍵/單指平移、右鍵/雙指旋轉(zhuǎn)、滾輪縮放平移嚴格沿世界水平面進行。它幾乎不引入新 API所有進階能力阻尼、距離限制、角度限制、自動旋轉(zhuǎn)、事件、狀態(tài)保存都來自 OrbitControls因此熟悉 OrbitControls.html.md 的開發(fā)者可以零成本上手。無論是快速搭建 3D 地圖原型還是構(gòu)建成熟的 GIS 可視化應(yīng)用MapControls 都是開箱即用的首選方案。延伸閱讀本文對應(yīng) API 文檔 docs/pages/MapControls.html.md父類文檔 docs/pages/OrbitControls.html.md基類 Controls 定義于 src/extras/Controls.js完整運行示例見 examples/misc_controls_map.htmlMOUSE/TOUCH常量定義見 src/constants.js?！久赓M下載鏈接】three.jsJavaScript 3D Library.項目地址: https://gitcode.com/GitHub_Trending/th/three.js創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 three.js MapControls 指南：構(gòu)建鳥瞰視角地圖相機控制的完整實踐
three.js MapControls 指南構(gòu)建鳥瞰視角地圖相機控制的完整實踐【免費下載鏈接】three.jsJavaScript 3D Library.項目地址: https://gitcode.com/GitHub_Trending/th/three.jsMapControls 是 three.js 中專門用于鳥瞰birds eye視角地圖相機操控的控制器它繼承了 OrbitControls 的全部軌道控制能力但通過一套「左鍵平移、右鍵/雙鍵旋轉(zhuǎn)、滾輪縮放」的預(yù)設(shè)交互映射并默認關(guān)閉屏幕空間平移使相機在保持垂直俯視的同時沿世界水平面自由移動。本文將從 API 文檔出發(fā)結(jié)合倉庫源碼與官方示例完整講解 MapControls 的導(dǎo)入、構(gòu)造、交互映射、關(guān)鍵屬性、與 OrbitControls 的差異以及底層平移實現(xiàn)原理幫助你在地圖瀏覽、GIS 可視化、大場景漫游等場景中直接落地使用。MapControls 是什么繼承關(guān)系與設(shè)計目標根據(jù) MapControls.html.md 的說明MapControls 的繼承鏈為EventDispatcher → Controls → OrbitControls → MapControls它「與 OrbitControls 共享實現(xiàn)但使用特定的鼠標/觸摸交互預(yù)設(shè)并默認禁用屏幕空間平移」。核心意圖非常明確在俯視地圖場景中旋轉(zhuǎn)通常只是微調(diào)視角而非環(huán)繞觀察用戶最頻繁的操作是平移與縮放。因此 MapControls 把鼠標左鍵從 OrbitControls 的「旋轉(zhuǎn)」改成了「平移」右鍵仍負責旋轉(zhuǎn)滾輪負責縮放。從源碼 examples/jsm/controls/MapControls.js 可以看到MapControls類繼承OrbitControls構(gòu)造函數(shù)中僅重設(shè)了三個屬性其余軌道、縮放、阻尼、自動旋轉(zhuǎn)等能力全部復(fù)用父類class MapControls extends OrbitControls { constructor( object, domElement ) { super( object, domElement ); this.screenSpacePanning false; this.mouseButtons { LEFT: MOUSE.PAN, MIDDLE: MOUSE.DOLLY, RIGHT: MOUSE.ROTATE }; this.touches { ONE: TOUCH.PAN, TWO: TOUCH.DOLLY_ROTATE }; this._panWorldStart new Vector3(); } // 覆蓋 _handleMouseDownPan / _handleMouseMovePan實現(xiàn)沿世界水平面的精確平移 // ... }由此可見 MapControls 本質(zhì)是「OrbitControls 的配置化子類」這也決定了它可以使用 OrbitControls 的幾乎全部屬性與方法詳見下文。安裝與導(dǎo)入MapControls 屬于 three.js 的addon附加組件需要顯式導(dǎo)入不會包含在核心構(gòu)建產(chǎn)物中。以 ES Module 方式導(dǎo)入import { MapControls } from three/addons/controls/MapControls.js;在官方示例 examples/misc_controls_map.html 中導(dǎo)入方式與 import map 配置保持一致script typeimportmap { imports: { three: ../build/three.module.js, three/addons/: ./jsm/ } } /script script typemodule import * as THREE from three; import { MapControls } from three/addons/controls/MapControls.js; // ... /script如果你的項目通過 npm 安裝 three則使用import { MapControls } from three/addons/controls/MapControls.js即可three/addons/映射到包內(nèi)的examples/jsm/目錄?？焖偕鲜肿钚】蛇\行示例下面整合 examples/misc_controls_map.html 的核心骨架給出一個完整的 MapControls 使用示例import * as THREE from three; import { MapControls } from three/addons/controls/MapControls.js; const scene new THREE.Scene(); const camera new THREE.PerspectiveCamera( 60, window.innerWidth / window.innerHeight, 1, 1000 ); camera.position.set( 0, 200, - 200 ); const renderer new THREE.WebGLRenderer( { antialias: true } ); renderer.setSize( window.innerWidth, window.innerHeight ); document.body.appendChild( renderer.domElement ); // 創(chuàng)建地圖控制器 const controls new MapControls( camera, renderer.domElement ); // 啟用阻尼慣性營造重量感 controls.enableDamping true; controls.dampingFactor 0.05; // 平移保持沿世界水平面MapControls 默認值此處顯式聲明 controls.screenSpacePanning false; // 限制俯仰角防止視角鉆到地圖下方 controls.maxPolarAngle Math.PI / 2; // 限制縮放距離范圍 controls.minDistance 100; controls.maxDistance 500; // 動畫循環(huán)啟用阻尼后必須每幀調(diào)用 update() renderer.setAnimationLoop( animate ); function animate() { controls.update(); renderer.render( scene, camera ); }要點說明構(gòu)造參數(shù)new MapControls( object, domElement )其中object是被控制器管理的相機Object3DdomElement是接收事件監(jiān)聽的 HTML 元素通常為renderer.domElement可省略。update()的調(diào)用時機與 OrbitControls 一致若enableDamping或autoRotate為true必須在動畫循環(huán)中每幀調(diào)用controls.update()若兩者都關(guān)閉則只需在手動修改相機變換后調(diào)用一次見 OrbitControls.html.md 的 Code Example 說明。示例中通過renderer.setAnimationLoop( animate )驅(qū)動渲染同時響應(yīng)窗口縮放事件時需更新camera.aspect與renderer.setSize()。交互映射鼠標、鍵盤與觸摸MapControls 文檔明確規(guī)定的交互預(yù)設(shè)如下操作鼠標觸摸對應(yīng)動作旋轉(zhuǎn)Orbit右鍵或 左鍵 ctrl/meta/shiftKey雙指旋轉(zhuǎn)ROTATE縮放Zoom中鍵或 滾輪雙指捏合/張開DOLLY平移Pan左鍵或 方向鍵單指拖動PAN鼠標映射源碼MapControls 在構(gòu)造函數(shù)中將 src/constants.js 中定義的MOUSE常量MOUSE { LEFT: 0, MIDDLE: 1, RIGHT: 2, ROTATE: 0, DOLLY: 1, PAN: 2 }映射為controls.mouseButtons { LEFT: MOUSE.PAN, // 左鍵平移 MIDDLE: MOUSE.DOLLY, // 中鍵推拉縮放 RIGHT: MOUSE.ROTATE // 右鍵旋轉(zhuǎn) }這與 OrbitControls 的默認映射左鍵旋轉(zhuǎn)、右鍵平移恰好對調(diào)了LEFT與RIGHT的角色。觸摸映射源碼TOUCH常量定義為TOUCH { ROTATE: 0, PAN: 1, DOLLY_PAN: 2, DOLLY_ROTATE: 3 }見 src/constants.jsMapControls 的觸摸預(yù)設(shè)為controls.touches { ONE: TOUCH.PAN, // 單指平移 TWO: TOUCH.DOLLY_ROTATE // 雙指捏合縮放 旋轉(zhuǎn) }與 OrbitControls 默認的ONE: ROTATE, TWO: DOLLY_PAN相比同樣是「單指操作從旋轉(zhuǎn)改為平移」完全貼合地圖應(yīng)用的直覺。注意文檔示例代碼中觸摸塊寫作controls.mouseButtons { ONE: ... , TWO: ... }實為文檔筆誤正確寫法是controls.touches { ONE: ..., TWO: ... }以 MapControls.js 源碼為準。鍵盤平移鍵盤方向鍵平移能力繼承自 OrbitControls 的keys屬性默認ArrowLeft/ArrowUp/ArrowRight/ArrowDown與keyPanSpeed默認7像素/次并需通過controls.listenToKeyEvents( domElement )注冊鍵盤監(jiān)聽推薦傳入window。因此「方向鍵平移」這一交互開箱即用無需額外配置。關(guān)鍵屬性詳解被覆蓋的三個屬性MapControls 只重寫了以下三個屬性這是它與 OrbitControls 的全部差異所在.screenSpacePanning : boolean默認false。當為false時相機在垂直于camera.up的世界平面上平移即沿世界水平面移動與屏幕傾斜無關(guān)當為true時則沿屏幕空間平移。地圖場景中設(shè)置為false可保證平移時不會出現(xiàn)鏡頭沿屏幕法線方向「飄移」的違和感。.mouseButtons : Object{ LEFT: MOUSE.PAN, MIDDLE: MOUSE.DOLLY, RIGHT: MOUSE.ROTATE }見上文交互表。.touches : Object{ ONE: TOUCH.PAN, TWO: TOUCH.DOLLY_ROTATE }見上文交互表。三者均可隨時在運行時修改例如把鼠標右鍵也改為平移controls.mouseButtons.RIGHT THREE.MOUSE.PAN;從 OrbitControls 繼承的常用屬性MapControls 未重寫、但完全可用的父類屬性見 OrbitControls.html.md屬性默認值作用.target : Vector3(0,0,0)相機圍繞的焦點可手動修改以改變聚焦點.enableDampingfalse啟用阻尼/慣性需要循環(huán)調(diào)用update().dampingFactor0.05阻尼系數(shù)越小慣性越大.minDistance/.maxDistance0/Infinity透視相機可推近/拉遠的最小/最大距離.minZoom/.maxZoom0/Infinity正交相機縮放范圍.minPolarAngle/.maxPolarAngle0/Math.PI垂直旋轉(zhuǎn)俯仰角度限制單位弧度.minAzimuthAngle/.maxAzimuthAngle-Infinity/-Infinity水平旋轉(zhuǎn)角度限制子區(qū)間需滿足max - min 2π.enablePan/.enableRotate/.enableZoomtrue分別開關(guān)平移、旋轉(zhuǎn)、縮放.autoRotate/.autoRotateSpeedfalse/2自動圍繞 target 旋轉(zhuǎn)開啟需每幀update().rotateSpeed/.zoomSpeed/.panSpeed1旋轉(zhuǎn)/縮放/平移速度系數(shù).keyPanSpeed7方向鍵每次按下的平移像素量.zoomToCursorfalse置true后縮放以光標位置為中心.cursor(0,0,0)minTargetRadius/maxTargetRadius的焦點.minTargetRadius/.maxTargetRadius0/Infinitytarget 到 cursor 的距離限制官方示例中對這些繼承屬性的典型組合用法examples/misc_controls_map.htmlcontrols.enableDamping true; controls.dampingFactor 0.05; controls.screenSpacePanning false; controls.minDistance 100; controls.maxDistance 500; controls.maxPolarAngle Math.PI / 2; // 限制俯仰角不超過水平面防止視角鉆入地下示例還用 lil-gui 暴露了zoomToCursor與screenSpacePanning兩個開關(guān)方便實時對比地圖模式與自由模式的行為差異。與 OrbitControls 的對比與相互切換維度OrbitControlsMapControls繼承Controls的直接子類OrbitControls的子類左鍵旋轉(zhuǎn)平移右鍵平移旋轉(zhuǎn)單指觸摸旋轉(zhuǎn)平移screenSpacePanningtruefalse適用場景3D 對象環(huán)繞查看俯視地圖/大場景瀏覽由于兩者 API 高度一致你可以在運行時直接替換控制器類或在mouseButtons/touches/screenSpacePanning三個屬性上手動對齊實現(xiàn)「地圖模式 ? 軌道模式」的無縫切換// 從地圖模式切回軌道模式 controls.mouseButtons { LEFT: THREE.MOUSE.ROTATE, MIDDLE: THREE.MOUSE.DOLLY, RIGHT: THREE.MOUSE.PAN }; controls.touches { ONE: THREE.TOUCH.ROTATE, TWO: THREE.TOUCH.DOLLY_PAN }; controls.screenSpacePanning true;源碼級原理為什么screenSpacePanning false能讓平移貼地父類中的兩種平移數(shù)學(xué)OrbitControls 中平移的核心是_panLeft與_panUp兩個私有方法examples/jsm/controls/OrbitControls.js。_panUp根據(jù)screenSpacePanning選擇不同方向向量_panUp( distance, objectMatrix ) { if ( this.screenSpacePanning true ) { _v.setFromMatrixColumn( objectMatrix, 1 ); // 使用相機矩陣的 Y 列屏幕豎直方向 } else { _v.setFromMatrixColumn( objectMatrix, 0 ); // 使用相機矩陣的 X 列 _v.crossVectors( this.object.up, _v ); // 叉乘 camera.up得到水平面內(nèi)的垂直方向 } _v.multiplyScalar( distance ); this._panOffset.add( _v ); }screenSpacePanning true豎直平移向量取相機局部 Y 軸鏡頭傾斜時平移會帶有「前后」分量screenSpacePanning false豎直平移向量為camera.up與相機 X 軸的叉積始終位于camera.up法線平面上即默認camera.up Y時嚴格沿世界水平面。MapControls 的平面求交平移除了屬性默認值MapControls 還覆蓋了平移的兩個事件處理函數(shù)MapControls.js。在screenSpacePanning false時_handleMouseDownPan會構(gòu)造一個以camera.up為法線、過target點的平面并記錄鼠標射線與該平面的首個交點作為起點_plane.setFromNormalAndCoplanarPoint( this.object.up, this.target ); _raycaster.setFromCamera( _mouse, this.object ); _raycaster.ray.intersectPlane( _plane, this._panWorldStart );拖動過程中_handleMouseMovePan每幀重新求交得到當前點與起點求差后取反寫入_panOffset再調(diào)用this.update()if ( _raycaster.ray.intersectPlane( _plane, _panCurrent ) ) { _panCurrent.sub( this._panWorldStart ); this._panOffset.copy( _panCurrent ).negate(); this.update(); }這意味著 MapControls 的鼠標平移不是簡單的像素偏移換算而是把鼠標世界射線與水平面的交點作為錨點——即使相機帶有俯仰角平移量也是地圖平面上的真實位移視覺上表現(xiàn)為「抓住地圖拖動」這正是地圖應(yīng)用需要的體驗。模塊級復(fù)用的_plane、_raycaster、_mouse、_panCurrent均為共享臨時對象避免頻繁分配內(nèi)存。事件與狀態(tài)管理MapControls 從父類繼承三個事件通過EventDispatcher派發(fā)見 OrbitControls.html.md 的 Events 章節(jié)change相機被控制器變換后觸發(fā)start交互開始時觸發(fā)end交互結(jié)束時觸發(fā)。典型用法靜態(tài)場景可借助change事件按需重繪避免持續(xù)渲染controls.addEventListener( change, () renderer.render( scene, camera ) ); controls.addEventListener( start, () console.log( interaction started ) ); controls.addEventListener( end, () console.log( interaction ended ) );狀態(tài)管理方面saveState()記錄當前position0/target0/zoom0reset()恢復(fù)到該狀態(tài)或初始狀態(tài)編程式操作可使用rotateLeft( angle )、rotateUp( angle )、pan( deltaX, deltaY )、dollyIn( scale )、dollyOut( scale )等方法并可用getPolarAngle()、getAzimuthalAngle()、getDistance()讀取當前姿態(tài)。實戰(zhàn)建議務(wù)必限制俯仰角地圖場景中設(shè)置controls.maxPolarAngle Math.PI / 2甚至更小防止用戶把視角轉(zhuǎn)到地面以下或完全水平。設(shè)置縮放距離范圍結(jié)合場景尺寸配置minDistance/maxDistance正交相機用minZoom/maxZoom避免鏡頭穿?；蚶h后丟失目標。阻尼提升手感enableDamping true后平移/縮放帶慣性更符合地圖 App 的操作直覺但切記每幀調(diào)用update()。監(jiān)聽 resize窗口變化時更新camera.aspect與renderer.setSize()參考 examples/misc_controls_map.html 的onWindowResize。按需切換zoomToCursor希望縮放以鼠標位置為錨點類似主流地圖應(yīng)用時將其設(shè)為true。小結(jié)MapControls 通過「繼承 預(yù)設(shè)」的方式把 OrbitControls 一鍵改造成適合鳥瞰地圖場景的控制器左鍵/單指平移、右鍵/雙指旋轉(zhuǎn)、滾輪縮放平移嚴格沿世界水平面進行。它幾乎不引入新 API所有進階能力阻尼、距離限制、角度限制、自動旋轉(zhuǎn)、事件、狀態(tài)保存都來自 OrbitControls因此熟悉 OrbitControls.html.md 的開發(fā)者可以零成本上手。無論是快速搭建 3D 地圖原型還是構(gòu)建成熟的 GIS 可視化應(yīng)用MapControls 都是開箱即用的首選方案。延伸閱讀本文對應(yīng) API 文檔 docs/pages/MapControls.html.md父類文檔 docs/pages/OrbitControls.html.md基類 Controls 定義于 src/extras/Controls.js完整運行示例見 examples/misc_controls_map.htmlMOUSE/TOUCH常量定義見 src/constants.js?！久赓M下載鏈接】three.jsJavaScript 3D Library.項目地址: https://gitcode.com/GitHub_Trending/th/three.js創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考