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