当前位置：首页 > news >正文

JSAPIThree 标签使用学习笔记：在地图上添加文字和图标

news 2026/5/11 19:23:31

作为一个刚开始学习 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,});
});