MapLibre GL JS第46课：用Markers添加自定义图标

丷丩2026-06-13 14:21

📌 学习目标

  • 掌握用Markers添加自定义图标的实现方法
  • 理解相关API的使用
  • 能够独立完成类似功能开发

⭕️👉课程完整目录⬅️⭕️

🎯 核心概念

使用Markers向地图添加自定义图标。

💻 完 整 代 码

代码示例

js 复制代码 
const geojson = {
    'type': 'FeatureCollection',
    'features': [
        {
            'type': 'Feature',
            'properties': {
                'message': 'Foo',
                'iconSize': [60, 60]
            },
            'geometry': {
                'type': 'Point',
                'coordinates': [-66.324462890625, -16.024695711685304]
            }
        },
        {
            'type': 'Feature',
            'properties': {
                'message': 'Bar',
                'iconSize': [50, 50]
            },
            'geometry': {
                'type': 'Point',
                'coordinates': [-61.2158203125, -15.97189158092897]
            }
        },
        {
            'type': 'Feature',
            'properties': {
                'message': 'Baz',
                'iconSize': [40, 40]
            },
            'geometry': {
                'type': 'Point',
                'coordinates': [-63.29223632812499, -18.28151823530889]
            }
        }
    ]
};

const map = new maplibregl.Map({
    container: 'map',
    style: 'https://demotiles.maplibre.org/style.json',
    center: [-65.017, -16.457],
    zoom: 5
});

// 向地图添加Markers图标
geojson.features.forEach((marker) => {
    // 创建Markers图标DOM元素
    const el = document.createElement('div');
    el.className = 'marker';
    el.style.backgroundImage =
        `url(https://picsum.photos/${
            marker.properties.iconSize.join('/')
        }/)`;
    el.style.width = `${marker.properties.iconSize[0]}px`;
    el.style.height = `${marker.properties.iconSize[1]}px`;

    el.addEventListener('click', () => {
        window.alert(marker.properties.message);
    });

    // 向地图添加Markers图标
    new maplibregl.Marker({element: el})
        .setLngLat(marker.geometry.coordinates)
        .addTo(map);
});

代码示例

html 复制代码 
<!DOCTYPE html>
<html lang="en">
<head>
    <title>Add custom icons with Markers</title>
    <meta property="og:description" content="向地图添加自定义标记图标。" />
    <meta property="og:created" content="2025-06-25" />
    <meta charset='utf-8'>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel='stylesheet' href='https://unpkg.com/maplibre-gl@5.24.0/dist/maplibre-gl.css' />
    <script src='https://unpkg.com/maplibre-gl@5.24.0/dist/maplibre-gl.js'></script>
    <style>
        body { margin: 0; padding: 0; }
        html, body, #map { height: 100%; }
    </style>
</head>
<body>
<style>
    .marker {
        display: block;
        border: none;
        border-radius: 50%;
        cursor: pointer;
        padding: 0;
    }
</style>

<div id="map"></div>

<script>
    const geojson = {
        'type': 'FeatureCollection',
        'features': [
            {
                'type': 'Feature',
                'properties': {
                    'message': 'Foo',
                    'iconSize': [60, 60]
                },
                'geometry': {
                    'type': 'Point',
                    'coordinates': [-66.324462890625, -16.024695711685304]
                }
            },
            {
                'type': 'Feature',
                'properties': {
                    'message': 'Bar',
                    'iconSize': [50, 50]
                },
                'geometry': {
                    'type': 'Point',
                    'coordinates': [-61.2158203125, -15.97189158092897]
                }
            },
            {
                'type': 'Feature',
                'properties': {
                    'message': 'Baz',
                    'iconSize': [40, 40]
                },
                'geometry': {
                    'type': 'Point',
                    'coordinates': [-63.29223632812499, -18.28151823530889]
                }
            }
        ]
    };

    const map = new maplibregl.Map({
        container: 'map',
        style: 'https://demotiles.maplibre.org/style.json',
        center: [-65.017, -16.457],
        zoom: 5
    });

    // 向地图添加标记
    geojson.features.forEach((marker) => {
        // 为标记创建一个DOM元素
        const el = document.createElement('div');
        el.className = 'marker';
        el.style.backgroundImage =
            `url(https://picsum.photos/${
                marker.properties.iconSize.join('/')
            }/)`;
        el.style.width = `${marker.properties.iconSize[0]}px`;
        el.style.height = `${marker.properties.iconSize[1]}px`;

        el.addEventListener('click', () => {
            window.alert(marker.properties.message);
        });

        // 将标记添加到地图
        new maplibregl.Marker({element: el})
            .setLngLat(marker.geometry.coordinates)
            .addTo(map);
    });
</script>
</body>
</html>

🔍 代码解析

初始化地图

使用 new maplibregl.Map() 创建地图实例，配置基本参数。本示例的核心特色是展示如何使用 maplibregl.Marker 添加自定义DOM元素作为地图标记。

关键配置项

  • container: 地图容器的 DOM 元素 ID
  • style : 使用 MapLibre 官方样式 https://demotiles.maplibre.org/style.json
  • center : 地图初始中心点 [-65.017, -16.457]（南美洲区域）
  • zoom: 初始缩放级别为 5，显示区域级别视图

创建自定义DOM元素

javascript 复制代码 
const el = document.createElement('div');
el.className = 'marker';
el.style.backgroundImage = `url(https://picsum.photos/${marker.properties.iconSize.join('/')}/)`;
el.style.width = `${marker.properties.iconSize[0]}px`;
el.style.height = `${marker.properties.iconSize[1]}px`;

el.addEventListener('click', () => {
    window.alert(marker.properties.message);
});

添加Marker到地图

javascript 复制代码 
new maplibregl.Marker({element: el})
    .setLngLat(marker.geometry.coordinates)
    .addTo(map);

Marker CSS样式

css 复制代码 
.marker {
    display: block;
    border: none;
    border-radius: 50%;
    cursor: pointer;
    padding: 0;
}

⚙️ 参数说明

参数 类型 必填 默认值 说明
container string 是 - 地图容器元素的 ID
style string/object 是 - 地图样式 URL 或内联样式对象
center number, number 否 [0, 0] 初始中心点坐标
zoom number 否 0 初始缩放级别

Marker 构造参数

参数 类型 必填 说明
element HTMLElement 否 自定义 DOM 元素，不提供则使用默认标记
anchor string 否 锚点位置，默认 center

Marker 方法

方法 说明
setLngLat(lnglat) 设置标记位置
addTo(map) 将标记添加到地图
remove() 从地图移除标记

🎨 效果说明

运行代码后，地图上会显示三个圆形图标标记：

  • Foo : 坐标 [-66.32, -16.02]，图标大小 60x60 像素
  • Bar : 坐标 [-61.22, -15.97]，图标大小 50x50 像素
  • Baz : 坐标 [-63.29, -18.28]，图标大小 40x40 像素

交互功能:

  • 点击图标会弹出对应的消息（Foo、Bar 或 Baz）
  • 图标显示为圆形（通过 border-radius: 50%）
  • 支持鼠标拖拽、滚轮缩放等标准地图交互

💡 常 见 问 题

Q1: Marker 和符号图层有什么区别？

A: Marker 是 DOM 元素，适合少量标记和复杂交互；符号图层是 WebGL 渲染，适合大量标记和高性能场景。

Q2: 如何调整 Marker 的锚点位置？

A: 在创建 Marker 时传入 anchor 参数：

javascript 复制代码 
new maplibregl.Marker({element: el, anchor: 'bottom'})

Q3: 如何移除 Marker？

A: 调用 Marker 实例的 remove() 方法：

javascript 复制代码 
const marker = new maplibregl.Marker({element: el}).addTo(map);
marker.remove();

Q4: 可以给 Marker 添加弹窗吗？

A: 可以，使用 setPopup() 方法：

javascript 复制代码 
new maplibregl.Marker({element: el})
    .setPopup(new maplibregl.Popup().setHTML('<h3>标题</h3>'))
    .addTo(map);

📝 练习任务

  1. 基础练习：修改图标的大小和形状，观察效果
  2. 进阶挑战：为每个 Marker 添加不同颜色的边框
  3. 拓展思考：如何实现 Marker 的拖拽功能？

🌟 最佳实践

  1. 性能考虑: 大量标记（>100）建议使用符号图层而非 Marker
  2. 样式统一: 使用 CSS class 而非内联样式管理 Marker 外观
  3. 事件委托: 对于多个 Marker，考虑使用事件委托优化性能
  4. 响应式设计 : 使用 position:absolute 和 transform 确保 Marker 定位准确
  5. 清理资源: 在地图销毁时移除所有 Marker
  6. 可访问性: 为 Marker 添加适当的 ARIA 属性和 tabindex

🔗 延伸阅读

本文是MapLibre GL JS实践课程系列的一部分，欢迎关注收藏

相关推荐
duansamve3 小时前
使用Python生成带20W有色立方体的矢量瓦片 MVT用于在Mapbox中加载的完整流程
mapbox
王小王-1236 小时前
基于机器学习的重庆主城的二手房价格影响因素分析与预测分析
机器学习·可视化·二手房价格预测·重庆二手房·成都二手房
丷丩1 天前
MapLibre GL JS第44课：生成并添加缺失图标
前端·javascript·gis·mapblibre gl js
搞科研的小刘选手2 天前
【智能计算方向专题研讨会】第三届智能计算与数据分析国际学术会议（ICDA 2026）
大数据·算法·机器学习·数据挖掘·数据分析·可视化·计算
杨超越luckly3 天前
Agent应用指南：利用GET请求获取赛力斯汽车门店位置信息
python·html·汽车·可视化·门店
杨超越luckly3 天前
Agent应用指南：利用GET请求获取理想汽车门店位置信息
前端·python·html·汽车·可视化
丷丩4 天前
MapLibre GL JS第41课：向地图添加图标
前端·javascript·mapbox·maplibre gl js
GISBox4 天前
告别DEM数值枯燥：GISBox如何用颜色和等高线“翻译”地形
gis·等高线·地形·gisbox·geotiff·高度着色·地形高程可视化
丷丩6 天前
12. 渲染：MapLibre GL JS 集成与多源瓦片联动
javascript·矢量瓦片·maplibre gl js·地图服务器
热门推荐
01HTTP 与 HTTPS 的区别：从原理到实战详解02《置身钉内》原文-可播放阅读03【AI】2026 年具身智能模型和世界模型总结042026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？05Claude Code、Codex、Cursor三分天下：2026年AI编程Agent生态全景剖析06AI科技热点日报 | 2026年6月1日072026年6月AI行业全景：从百模大战到Agent元年，这30天发生了什么？08GitHub 镜像站点09AI一周事件 · 2026-06-03 至 2026-06-09102026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf