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

作为刚接触 mapvthree 的新手,今天我专门学习了 UI 控件模块。这里整理出最常用的控件和实用技巧,帮助和我一样的初学者快速上手。

控件管理入口:engine.widgets

mapvthree 中的控件由 EngineWidgets 管理,实例化后可以通过 engine.widgets 访问。控件分两种启用方式:

  1. 初始化时配置 :在 new Engine() 时,通过 widgets 字段设置 enabled
  2. 运行时控制 :引擎创建完成后,直接修改 engine.widgets.xxx.enabled
js 复制代码
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 回调会在开关时触发,可用于添加/移除物体等自定义逻辑。

js 复制代码
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,还需要在对应地图实例初始化时开启同名参数。

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

使用建议

  • 按需启用:控件越多越不一定好,按场景需求启用即可
  • 统一风格:若有自定义 UI,尽量与内置控件保持视觉一致
  • 与业务逻辑配合:控件只是入口,核心业务逻辑仍需自行实现(如定位、截图结果保存等)
  • 运行时控制:可以根据场景状态动态开启/关闭控件,例如进入播放模式时隐藏所有按钮

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

相关推荐
曲径海盗5 天前
【Python 学习第 58 天】列表方法
python·学习笔记·编程入门
曲径海盗7 天前
【Python 学习第 55 天】列表基础
python·学习笔记·编程入门
曲径海盗10 天前
【Python 学习第 53 天】列表基础
python·学习笔记·编程入门
程序员沉梦听雨14 天前
【搜索引擎】Kibana使用指南
java·后端·学习笔记
死磕音视频15 天前
Gemini Notebook 入门:把公开 YouTube 教程变成可提问的学习笔记
学习笔记·youtube·gemini·notebooklm
宇宙无敌暴龙战士66616 天前
MySQL 8 库表操作学习笔记:SQL 基础、库表管理、约束与用户授权全流程
数据库·sql·mysql·学习笔记·后端开发
2601_9679801120 天前
Python 初学者必备的常用内置函数
python·编程语言·内置函数·初学者·常用函数
曲径海盗21 天前
【Python 学习第 41 天】for 循环
python·学习笔记·编程入门
曲径海盗22 天前
【Python 学习第 38 天】for 循环
python·学习笔记·编程入门
曲径海盗22 天前
【Python 学习第 40 天】for 循环
python·学习笔记·编程入门