JSAPIThree UI 控件学习笔记：用内置控件提升交互

作为刚接触 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，否则截图会是空白。

常用控件一览

控件	作用	使用建议
zoom	显示缩放按钮	与鼠标滚轮配合，易用性更高
compass	显示方向和倾角	适合 3D 场景，便于用户恢复默认视角
fullscreen	全屏切换	适合大屏展示或需要沉浸体验的场景
geoLocate	定位按钮	搭配获取定位的业务逻辑使用
exportImage	导出当前场景为图片	需开启 preserveDrawingBuffer
mapInfo	显示当前地理坐标	对需要精确定位的业务很有帮助
drawer	自定义控件容器（如工具面板）	可以挂自定义按钮或操作

深入配置：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，尽量与内置控件保持视觉一致
• 与业务逻辑配合：控件只是入口，核心业务逻辑仍需自行实现（如定位、截图结果保存等）
• 运行时控制：可以根据场景状态动态开启/关闭控件，例如进入播放模式时隐藏所有按钮

---

学习笔记就到这里啦！内置控件用起来并不复杂，关键是理解“初始化配置 + 运行时控制”这两种方式，然后按需组合即可。希望这份笔记能帮你快速把控件用好！