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