JSAPIThree UI 控件学习笔记：用内置控件提升交互
<blockquote><p>作为刚接触 mapvthree 的新手，今天我专门学习了 UI 控件模块。这里整理出最常用的控件和实用技巧，帮助和我一样的初学者快速上手。</p>
</blockquote>
<h2 id="控件管理入口enginewidgets">控件管理入口：engine.widgets</h2>
<p>mapvthree 中的控件由 <code>EngineWidgets</code> 管理，实例化后可以通过 <code>engine.widgets</code> 访问。控件分两种启用方式：</p>
<ol>
<li><strong>初始化时配置</strong>：在 <code>new Engine()</code> 时，通过 <code>widgets</code> 字段设置 <code>enabled</code></li>
<li><strong>运行时控制</strong>：引擎创建完成后，直接修改 <code>engine.widgets.xxx.enabled</code></li>
</ol>
<pre><code class="language-js">const engine = new mapvthree.Engine(container, {
map: { center: , 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;
</code></pre>
<blockquote>
<p>小贴士：<code>exportImage</code> 必须搭配 <code>rendering.preserveDrawingBuffer = true</code>，否则截图会是空白。</p>
</blockquote>
<h2 id="常用控件一览">常用控件一览</h2>
<table>
<thead>
<tr>
<th>控件</th>
<th>作用</th>
<th>使用建议</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>zoom</code></td>
<td>显示缩放按钮</td>
<td>与鼠标滚轮配合，易用性更高</td>
</tr>
<tr>
<td><code>compass</code></td>
<td>显示方向和倾角</td>
<td>适合 3D 场景，便于用户恢复默认视角</td>
</tr>
<tr>
<td><code>fullscreen</code></td>
<td>全屏切换</td>
<td>适合大屏展示或需要沉浸体验的场景</td>
</tr>
<tr>
<td><code>geoLocate</code></td>
<td>定位按钮</td>
<td>搭配获取定位的业务逻辑使用</td>
</tr>
<tr>
<td><code>exportImage</code></td>
<td>导出当前场景为图片</td>
<td>需开启 <code>preserveDrawingBuffer</code></td>
</tr>
<tr>
<td><code>mapInfo</code></td>
<td>显示当前地理坐标</td>
<td>对需要精确定位的业务很有帮助</td>
</tr>
<tr>
<td><code>drawer</code></td>
<td>自定义控件容器（如工具面板）</td>
<td>可以挂自定义按钮或操作</td>
</tr>
</tbody>
</table>
<h2 id="深入配置mapinfodrawer-与-accessors">深入配置：mapInfo、drawer 与 accessors</h2>
<p>除了 <code>enabled</code>，部分控件还提供更细的参数：</p>
<ul>
<li><strong>mapInfo</strong>
<ul>
<li><code>template</code>：字符串由 <code>C</code>（中心点）、<code>R</code>（视野距离）、<code>H</code>（heading）、<code>P</code>（pitch）等占位符组成，默认 <code>CR</code></li>
<li><code>separator</code>：字段之间的分隔符，默认 <code>' | '</code></li>
<li>例如：<code>mapInfo: { enabled: true, template: 'CHP', separator: ', ' }</code></li>
</ul>
</li>
<li><strong>drawer</strong>
<ul>
<li><code>draws</code> 数组描述每个工具项：<code>name</code>、<code>defaultChecked</code>、<code>data</code>、<code>onChange</code></li>
<li><code>onChange(checked, data, engine)</code> 在开关时触发，可用于添加/移除对象</li>
</ul>
</li>
<li><strong>访问器（accessor）</strong>
<ul>
<li>每个控件都有对应的 getter，例如 <code>engine.widgets.zoom</code>、<code>engine.widgets.scale</code></li>
<li>获取到的是控件实例，可以直接读写属性：<code>engine.widgets.mapInfo.template = 'CRH'</code></li>
</ul>
</li>
</ul>
<h2 id="自定义-drawer-控件">自定义 Drawer 控件</h2>
<p><code>drawer</code> 类似一个工具抽屉，可以配置多个“工具项”。每个工具项的 <code>onChange</code> 回调会在开关时触发，可用于添加/移除物体等自定义逻辑。</p>
<pre><code class="language-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();
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, position, position);
data.mesh = mesh;
}
checked ? engine.add(data.mesh) : engine.remove(data.mesh);
},
},
],
},
},
});
</code></pre>
<h2 id="截图功能别忘了-preservedrawingbuffer">截图功能：别忘了 preserveDrawingBuffer</h2>
<p><code>exportImage</code> 控件其实是一个“导出当前画面”的按钮，但要正常截图必须开启 <code>rendering.preserveDrawingBuffer = true</code>。在纯引擎场景下只用设置这一项；如果叠加 BMapGL 或 mapbox，还需要在对应地图实例初始化时开启同名参数。</p>
<pre><code class="language-js">const engine = new mapvthree.Engine(container, {
rendering: {
preserveDrawingBuffer: true,
},
widgets: {
exportImage: { enabled: true },
},
});
</code></pre>
<h2 id="使用建议">使用建议</h2>
<ul>
<li><strong>按需启用</strong>：控件越多越不一定好，按场景需求启用即可</li>
<li><strong>统一风格</strong>：若有自定义 UI，尽量与内置控件保持视觉一致</li>
<li><strong>与业务逻辑配合</strong>：控件只是入口，核心业务逻辑仍需自行实现（如定位、截图结果保存等）</li>
<li><strong>运行时控制</strong>：可以根据场景状态动态开启/关闭控件，例如进入播放模式时隐藏所有按钮</li>
</ul>
<hr>
<blockquote>
<p>学习笔记就到这里啦！内置控件用起来并不复杂，关键是理解“初始化配置 + 运行时控制”这两种方式，然后按需组合即可。希望这份笔记能帮你快速把控件用好！</p>
</blockquote><br><br>
来源：https://www.cnblogs.com/map-3d-vis/p/19277414
頁:
[1]