作為剛接觸 mapvthree 的新手，今天我專門學習了 UI 控件模塊。這裏整理出最常用的控件和實用技巧，幫助和我一樣的初學者快速上手。

控件管理入口：engine.widgets

mapvthree 中的控件由 EngineWidgets 管理，實例化後可以通過 engine.widgets 訪問。控件分兩種啓用方式：

1. 初始化時配置：在 new Engine() 時，通過 widgets 字段設置 enabled
2. 運行時控制：引擎創建完成後，直接修改 engine.widgets.xxx.enabled

const engine = new mapvthree.Engine(container, {
    map: { center: [106.515, 29.639], range: 500 },
    rendering: {
        // 導出圖片需要開啓
        preserveDrawingBuffer: true,
    },
    widgets: {
        zoom: { enabled: true },        // 縮放控件
        fullscreen: { enabled: true },  // 全屏控件
        geoLocate: { enabled: true },   // 定位控件
        exportImage: { enabled: true }, // 導出圖片控件
        compass: { enabled: true },     // 指南針
        mapInfo: { enabled: true },     // 顯示地理座標
    },
});

// 運行時開啓比例尺與 logo
engine.widgets.scale.enabled = true;
engine.widgets.logo.enabled = true;

小貼士：exportImage 必須搭配 rendering.preserveDrawingBuffer = true，否則截圖會是空白。

常用控件一覽

深入配置：mapInfo、drawer 與 accessors

除了 enabled，部分控件還提供更細的參數：

• mapInfo

  • template：字符串由 C（中心點）、R（視野距離）、H（heading）、P（pitch）等佔位符組成，默認 CR
  • separator：字段之間的分隔符，默認 ' | '
  • 例如：mapInfo: { enabled: true, template: 'CHP', separator: ', ' }

• drawer

  • draws 數組描述每個工具項：name、defaultChecked、data、onChange
  • onChange(checked, data, engine) 在開關時觸發，可用於添加/移除對象

• 訪問器（accessor）

  • 每個控件都有對應的 getter，例如 engine.widgets.zoom、engine.widgets.scale
  • 獲取到的是控件實例，可以直接讀寫屬性：engine.widgets.mapInfo.template = 'CRH'

自定義 Drawer 控件

drawer 類似一個工具抽屜，可以配置多個“工具項”。每個工具項的 onChange 回調會在開關時觸發，可用於添加/移除物體等自定義邏輯。

const engine = new mapvthree.Engine(container, {
    ...,
    widgets: {
        drawer: {
            enabled: true,
            draws: [
                {
                    name: '添加綠盒子',
                    data: { mesh: null },
                    onChange: (checked, data, engine) => {
                        if (!data.mesh) {
                            const position = engine.map.projectArrayCoordinate([106.515, 29.639]);
                            const geometry = new THREE.BoxGeometry(100, 100, 100);
                            const material = new THREE.MeshBasicMaterial({color: 0x00ff00});
                            const mesh = new THREE.Mesh(geometry, material);
                            mesh.position.set(position[0], position[1], position[2]);
                            data.mesh = mesh;
                        }
                        checked ? engine.add(data.mesh) : engine.remove(data.mesh);
                    },
                },
            ],
        },
    },
});

截圖功能：別忘了 preserveDrawingBuffer

exportImage 控件其實是一個“導出當前畫面”的按鈕，但要正常截圖必須開啓 rendering.preserveDrawingBuffer = true。在純引擎場景下只用設置這一項；如果疊加 BMapGL 或 mapbox，還需要在對應地圖實例初始化時開啓同名參數。

const engine = new mapvthree.Engine(container, {
    rendering: {
        preserveDrawingBuffer: true,
    },
    widgets: {
        exportImage: { enabled: true },
    },
});

使用建議

• 按需啓用：控件越多越不一定好，按場景需求啓用即可
• 統一風格：若有自定義 UI，儘量與內置控件保持視覺一致
• 與業務邏輯配合：控件只是入口，核心業務邏輯仍需自行實現（如定位、截圖結果保存等）
• 運行時控制：可以根據場景狀態動態開啓/關閉控件，例如進入播放模式時隱藏所有按鈕

學習筆記就到這裏啦！內置控件用起來並不複雜，關鍵是理解“初始化配置 + 運行時控制”這兩種方式，然後按需組合即可。希望這份筆記能幫你快速把控件用好！