博客 / 詳情

返回

JSAPIThree 標籤使用學習筆記：在地圖上添加文字和圖標

作為一個剛開始學習 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：標籤位置不對

原因：經緯度順序寫反。

解決：確保座標格式是 [經度, 緯度, 高度]，經度在前。

我的學習總結

經過這一天的學習，我掌握了：

  1. 如何添加標籤：通過 engine.rendering.label.addLabel() 添加
  2. 文字標籤：設置 text 屬性
  3. 圖標標籤：設置 mapSrc 屬性
  4. 組合標籤：同時設置 text 和 mapSrc
  5. 標籤樣式：通過 textSize、textFillStyle、textStrokeStyle、textStrokeWidth 配置
  6. 文字錨點：通過 textAnchor 控制文字位置
  7. 碰撞檢測：通過 collision: true 開啓，避免標籤重疊
  8. 標籤高度：通過 position 的第三個參數設置
  9. 標籤貼地：通過 flat 參數控制
  10. 圖標大小：通過 width 和 height 控制

我的感受：標籤功能很實用！雖然參數很多，但是用起來不難。關鍵是要理解每個參數的作用，然後根據需求合理配置！

學習筆記就到這裏啦！作為一個初學者，我覺得標籤功能雖然參數很多，但是用起來其實不難。關鍵是要理解每個參數的作用，然後根據需求合理配置！希望我的筆記能幫到其他初學者！大家一起加油！

前端
user avatar
0 位用戶收藏了這個故事！

發佈 評論

Some HTML is okay.