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

作为一个刚开始学习 mapvthree 的小白，今天要学习标签功能了！听说这个功能可以在地图上添加文字和图标，用来显示地点名称、数值信息等！想想就实用！

第一次听说标签功能

今天在文档里看到了"标签"这个词，一开始我还以为是 HTML 的标签，结果查了一下才知道，原来这是在地图上显示文字和图标的功能！

文档说标签可以：

展示地点名称
显示数值信息
显示状态提示
添加图标和文字组合

我的理解：简单说就是在地图上"贴标签"，就像给地图上的位置加个说明一样！

第一步：发现标签管理器

文档说 engine.rendering.label 就是标签管理器，引擎创建后自动实例化，不需要手动创建。

js 复制代码

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() 添加标签，最简单的就是添加文字：

js 复制代码

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], // [经度, 纬度]
});

我的发现：地图上出现了文字标签！就几行代码，很简单！

第三步：配置标签样式

可以设置文字大小、颜色、描边等样式：

js 复制代码

const label = engine.rendering.label.addLabel({
    text: '北京',
    position: [116.404, 39.915],
    textSize: 16,              // 文字大小（像素）
    textFillStyle: '#000000',  // 文字颜色
    textStrokeStyle: '#ff0000', // 文字描边颜色
    textStrokeWidth: 1,        // 文字描边宽度
});

我的发现：可以自定义文字样式，让标签更清晰、更美观！

第四步：设置文字锚点

通过 textAnchor 控制文字相对于位置点的位置：

js 复制代码

// 文字在位置点下方
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，可以添加纯图标标签：

js 复制代码

const iconLabel = engine.rendering.label.addLabel({
    position: [116.404, 39.915],
    mapSrc: 'assets/images/marker/library.png',
    width: 32,   // 图标宽度（像素）
    height: 32,  // 图标高度（像素）
});

我的发现：可以添加图标标签，适合做 POI 展示！

第六步：图标和文字组合

同时设置 mapSrc 和 text，可以显示图标和文字组合：

js 复制代码

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 开启碰撞检测，标签会自动避免重叠：

js 复制代码

const label = engine.rendering.label.addLabel({
    text: '北京',
    position: [116.404, 39.915],
    collision: true, // 开启碰撞检测
    group: 'label', // 可选：碰撞分组
});

我的理解 ：开启碰撞检测后，标签会自动调整位置避免重叠。可以通过 group 设置碰撞分组，不同分组之间不会碰撞。

第八步：设置标签高度和贴地

通过 position 的第三个参数设置高度（米），通过 flat 控制是否贴地：

js 复制代码

// 标签在地面上
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() 可以删除标签：

js 复制代码

// 添加标签
const label = engine.rendering.label.addLabel({
    text: '临时标签',
    position: [116.404, 39.915],
});

// 删除标签
label.dispose();

第十步：完整示例

下面是一个完整的示例，展示不同类型的标签：

js 复制代码

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：地点标注

js 复制代码

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：数据展示

js 复制代码

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 展示

js 复制代码

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 控制

我的感受：标签功能很实用！虽然参数很多，但是用起来不难。关键是要理解每个参数的作用，然后根据需求合理配置！

学习笔记就到这里啦！作为一个初学者，我觉得标签功能虽然参数很多，但是用起来其实不难。关键是要理解每个参数的作用，然后根据需求合理配置！希望我的笔记能帮到其他初学者！大家一起加油！