JSAPIThree UI 控件学习笔记：用内置控件提升交互
作为刚接触 mapvthree 的新手，今天我专门学习了 UI 控件模块。这里整理出最常用的控件和实用技巧，帮助和我一样的初学者快速上手。
控件管理入口：engine.widgets
mapvthree 中的控件由 EngineWidgets 管理，实例化后可以通过 engine.widgets 访问。控件分两种启用方式：
初始化时配置：在 new Engine() 时，通过 widgets 字段设置 enabled
运行时控制：引擎创建完成后，直接修改 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，尽量与内置控件保持视觉一致
与业务逻辑配合：控件只是入口，核心业务逻辑仍需自行实现（如定位、截图结果保存等）
运行时控制：可以根据场景状态动态开启/关闭控件，例如进入播放模式时隐藏所有按钮
学习笔记就到这里啦！内置控件用起来并不复杂，关键是理解“初始化配置 + 运行时控制”这两种方式，然后按需组合即可。希望这份笔记能帮你快速把控件用好！