JSAPIThree 标签使用学习笔记：在地图上添加文字和图标
<blockquote><p>作为一个刚开始学习 mapvthree 的小白，今天要学习标签功能了！听说这个功能可以在地图上添加文字和图标，用来显示地点名称、数值信息等！想想就实用！</p>
</blockquote>
<h2 id="第一次听说标签功能">第一次听说标签功能</h2>
<p>今天在文档里看到了"标签"这个词，一开始我还以为是 HTML 的标签，结果查了一下才知道，原来这是在地图上显示文字和图标的功能！</p>
<p>文档说标签可以：</p>
<ul>
<li>展示地点名称</li>
<li>显示数值信息</li>
<li>显示状态提示</li>
<li>添加图标和文字组合</li>
</ul>
<p><strong>我的理解</strong>：简单说就是在地图上"贴标签"，就像给地图上的位置加个说明一样！</p>
<h2 id="第一步发现标签管理器">第一步：发现标签管理器</h2>
<p>文档说 <code>engine.rendering.label</code> 就是标签管理器，引擎创建后自动实例化，不需要手动创建。</p>
<pre><code class="language-js">import * as mapvthree from '@baidumap/mapv-three';
const container = document.getElementById('container');
const engine = new mapvthree.Engine(container);
// 标签管理器已经自动创建了
console.log(engine.rendering.label);
</code></pre>
<p><strong>我的理解</strong>：<code>engine.rendering.label</code> 适合添加少量的、独立的、需要精确控制的标签，不需要配置数据源。</p>
<h2 id="第二步添加文字标签">第二步：添加文字标签</h2>
<p>使用 <code>engine.rendering.label.addLabel()</code> 添加标签，最简单的就是添加文字：</p>
<pre><code class="language-js">import * as mapvthree from '@baidumap/mapv-three';
const container = document.getElementById('container');
const engine = new mapvthree.Engine(container, {
map: {
center: ,
range: 2000,
},
rendering: {
enableAnimationLoop: true,
},
});
// 添加文字标签
const label = engine.rendering.label.addLabel({
text: '北京',
position: , // [经度, 纬度]
});
</code></pre>
<p><strong>我的发现</strong>：地图上出现了文字标签！就几行代码，很简单！</p>
<h2 id="第三步配置标签样式">第三步：配置标签样式</h2>
<p>可以设置文字大小、颜色、描边等样式：</p>
<pre><code class="language-js">const label = engine.rendering.label.addLabel({
text: '北京',
position: ,
textSize: 16, // 文字大小（像素）
textFillStyle: '#000000',// 文字颜色
textStrokeStyle: '#ff0000', // 文字描边颜色
textStrokeWidth: 1, // 文字描边宽度
});
</code></pre>
<p><strong>我的发现</strong>：可以自定义文字样式，让标签更清晰、更美观！</p>
<h2 id="第四步设置文字锚点">第四步：设置文字锚点</h2>
<p>通过 <code>textAnchor</code> 控制文字相对于位置点的位置：</p>
<pre><code class="language-js">// 文字在位置点下方
const label1 = engine.rendering.label.addLabel({
text: '北京',
position: ,
textAnchor: 'bottom',
});
// 文字在位置点左侧
const label2 = engine.rendering.label.addLabel({
text: '上海',
position: ,
textAnchor: 'left',
});
</code></pre>
<p><strong>我的理解</strong>：<code>textAnchor</code> 可以控制文字相对于位置点或图标的位置，适合图标和文字组合使用。</p>
<h2 id="第五步添加图标标签">第五步：添加图标标签</h2>
<p>使用 <code>mapSrc</code> 设置图标 URL，可以添加纯图标标签：</p>
<pre><code class="language-js">const iconLabel = engine.rendering.label.addLabel({
position: ,
mapSrc: 'assets/images/marker/library.png',
width: 32, // 图标宽度（像素）
height: 32,// 图标高度（像素）
});
</code></pre>
<p><strong>我的发现</strong>：可以添加图标标签，适合做 POI 展示！</p>
<h2 id="第六步图标和文字组合">第六步：图标和文字组合</h2>
<p>同时设置 <code>mapSrc</code> 和 <code>text</code>，可以显示图标和文字组合：</p>
<pre><code class="language-js">const label = engine.rendering.label.addLabel({
text: '故宫博物院',
position: ,
mapSrc: 'assets/images/marker/library.png',
textSize: 14,
textFillStyle: '#000000',
textStrokeStyle: '#ff0000',
textStrokeWidth: 1,
textAnchor: 'left', // 文字在图标左侧
width: 24,
height: 24,
});
</code></pre>
<p><strong>我的发现</strong>：可以同时显示图标和文字，看起来更专业！</p>
<h2 id="第七步开启碰撞检测">第七步：开启碰撞检测</h2>
<p>设置 <code>collision: true</code> 开启碰撞检测，标签会自动避免重叠：</p>
<pre><code class="language-js">const label = engine.rendering.label.addLabel({
text: '北京',
position: ,
collision: true, // 开启碰撞检测
group: 'label', // 可选：碰撞分组
});
</code></pre>
<p><strong>我的理解</strong>：开启碰撞检测后，标签会自动调整位置避免重叠。可以通过 <code>group</code> 设置碰撞分组，不同分组之间不会碰撞。</p>
<h2 id="第八步设置标签高度和贴地">第八步：设置标签高度和贴地</h2>
<p>通过 <code>position</code> 的第三个参数设置高度（米），通过 <code>flat</code> 控制是否贴地：</p>
<pre><code class="language-js">// 标签在地面上
const label1 = engine.rendering.label.addLabel({
text: '地面',
position: ,
flat: true, // 贴地
});
// 标签在空中 100 米
const label2 = engine.rendering.label.addLabel({
text: '空中',
position: ,
flat: false, // 不贴地（默认）
});
</code></pre>
<p><strong>我的理解</strong>：<code>flat: true</code> 表示标签始终贴地，不会因视角变化而倾斜；<code>flat: false</code> 标签会跟随视角变化。</p>
<h2 id="第九步删除标签">第九步：删除标签</h2>
<p><code>addLabel()</code> 返回一个 <code>DataItem</code> 对象，调用 <code>dispose()</code> 可以删除标签：</p>
<pre><code class="language-js">// 添加标签
const label = engine.rendering.label.addLabel({
text: '临时标签',
position: ,
});
// 删除标签
label.dispose();
</code></pre>
<h2 id="第十步完整示例">第十步：完整示例</h2>
<p>下面是一个完整的示例，展示不同类型的标签：</p>
<pre><code class="language-js">import * as mapvthree from '@baidumap/mapv-three';
const container = document.getElementById('container');
const engine = new mapvthree.Engine(container, {
map: {
center: ,
range: 2000,
},
rendering: {
enableAnimationLoop: true,
},
});
// 纯文字标签
const textLabel = engine.rendering.label.addLabel({
text: '北京',
position: ,
textSize: 16,
textFillStyle: '#000000',
textStrokeStyle: '#ff0000',
textStrokeWidth: 1,
collision: true,
});
// 图标和文字组合标签
const iconTextLabel = engine.rendering.label.addLabel({
text: '故宫博物院',
position: ,
mapSrc: 'assets/images/marker/library.png',
textSize: 14,
textFillStyle: '#000000',
textStrokeStyle: '#ff0000',
textStrokeWidth: 1,
textAnchor: 'left',
width: 24,
height: 24,
collision: true,
});
// 纯图标标签
const iconLabel = engine.rendering.label.addLabel({
position: ,
mapSrc: 'assets/images/marker/library.png',
width: 32,
height: 32,
});
</code></pre>
<h2 id="第十一步实际应用场景">第十一步：实际应用场景</h2>
<h3 id="场景-1地点标注">场景 1：地点标注</h3>
<pre><code class="language-js">const spots = [
{ name: '天安门', position: },
{ name: '故宫', position: },
{ name: '天坛', position: },
];
spots.forEach(spot => {
engine.rendering.label.addLabel({
text: spot.name,
position: spot.position,
textSize: 14,
textFillStyle: '#333333',
collision: true,
});
});
</code></pre>
<h3 id="场景-2数据展示">场景 2：数据展示</h3>
<pre><code class="language-js">const dataPoints = [
{ value: 100, position: },
{ value: 200, position: },
];
dataPoints.forEach(point => {
engine.rendering.label.addLabel({
text: point.value.toString(),
position: point.position,
textSize: 16,
textFillStyle: '#ff0000',
textStrokeStyle: '#ffffff',
textStrokeWidth: 2,
});
});
</code></pre>
<h3 id="场景-3poi-展示">场景 3：POI 展示</h3>
<pre><code class="language-js">const pois = [
{ name: '图书馆', type: 'library', position: },
{ name: '餐厅', type: 'restaurant', position: },
];
const iconMap = {
library: 'assets/images/marker/library.png',
restaurant: 'assets/images/marker/restaurant.png',
};
pois.forEach(poi => {
engine.rendering.label.addLabel({
text: poi.name,
position: poi.position,
mapSrc: iconMap,
textAnchor: 'left',
width: 24,
height: 24,
collision: true,
});
});
</code></pre>
<h2 id="第十二步踩过的坑">第十二步：踩过的坑</h2>
<h3 id="坑-1标签不显示">坑 1：标签不显示</h3>
<p><strong>原因</strong>：位置坐标格式错误，或没有开启循环渲染。</p>
<p><strong>解决</strong>：确保坐标格式是 <code>[经度, 纬度]</code> 或 <code>[经度, 纬度, 高度]</code>，并开启 <code>enableAnimationLoop</code>。</p>
<h3 id="坑-2图标不显示">坑 2：图标不显示</h3>
<p><strong>原因</strong>：图标路径错误或文件不存在。</p>
<p><strong>解决</strong>：检查图标路径是否正确。</p>
<h3 id="坑-3文字样式不生效">坑 3：文字样式不生效</h3>
<p><strong>原因</strong>：属性名写错，如 <code>textSize</code> 写成了 <code>fontSize</code>。</p>
<p><strong>解决</strong>：使用正确的属性名：<code>textSize</code>、<code>textFillStyle</code>、<code>textStrokeStyle</code>、<code>textStrokeWidth</code>。</p>
<h3 id="坑-4碰撞检测不工作">坑 4：碰撞检测不工作</h3>
<p><strong>原因</strong>：没有设置 <code>collision: true</code>。</p>
<p><strong>解决</strong>：明确设置 <code>collision: true</code>。</p>
<h3 id="坑-5标签位置不对">坑 5：标签位置不对</h3>
<p><strong>原因</strong>：经纬度顺序写反。</p>
<p><strong>解决</strong>：确保坐标格式是 <code>[经度, 纬度, 高度]</code>，经度在前。</p>
<h2 id="我的学习总结">我的学习总结</h2>
<p>经过这一天的学习，我掌握了：</p>
<ol>
<li><strong>如何添加标签</strong>：通过 <code>engine.rendering.label.addLabel()</code> 添加</li>
<li><strong>文字标签</strong>：设置 <code>text</code> 属性</li>
<li><strong>图标标签</strong>：设置 <code>mapSrc</code> 属性</li>
<li><strong>组合标签</strong>：同时设置 <code>text</code> 和 <code>mapSrc</code></li>
<li><strong>标签样式</strong>：通过 <code>textSize</code>、<code>textFillStyle</code>、<code>textStrokeStyle</code>、<code>textStrokeWidth</code> 配置</li>
<li><strong>文字锚点</strong>：通过 <code>textAnchor</code> 控制文字位置</li>
<li><strong>碰撞检测</strong>：通过 <code>collision: true</code> 开启，避免标签重叠</li>
<li><strong>标签高度</strong>：通过 <code>position</code> 的第三个参数设置</li>
<li><strong>标签贴地</strong>：通过 <code>flat</code> 参数控制</li>
<li><strong>图标大小</strong>：通过 <code>width</code> 和 <code>height</code> 控制</li>
</ol>
<p><strong>我的感受</strong>：标签功能很实用！虽然参数很多，但是用起来不难。关键是要理解每个参数的作用，然后根据需求合理配置！</p>
<hr>
<blockquote>
<p>学习笔记就到这里啦！作为一个初学者，我觉得标签功能虽然参数很多，但是用起来其实不难。关键是要理解每个参数的作用，然后根据需求合理配置！希望我的笔记能帮到其他初学者！大家一起加油！</p>
</blockquote><br><br>
来源：https://www.cnblogs.com/map-3d-vis/p/19267205
頁:
[1]