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

原创已于 2026-06-12 12:31:00 修改 · 330 阅读

5 ·

CC 4.0 BY-SA版权

文章标签：

#GIS #Mapbox #Maplibre GL JS #可视化

于 2026-06-12 12:24:36 首次发布

MapLibre GL JS教程专栏收录该内容

54 篇文章

订阅专栏

📌 学习目标

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

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

🎯 核心概念

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

💻 完整代码

代码示例

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);
});

代码示例

<!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元素

const el = document.createElement('div');
el.className = 'marker';
el.style.backgroundImage = `url(https://picsum.photos/%3C/span%3E%3Cspan%20class=%22token%20interpolation%22%3E%3Cspan%20class=%22token%20interpolation-punctuation%20punctuation%22%3E$%7B%3C!--%20--%3E%3C/span%3Emarker%3Cspan%20class=%22token%20punctuation%22%3E.%3C/span%3Eproperties%3Cspan%20class=%22token%20punctuation%22%3E.%3C/span%3EiconSize%3Cspan%20class=%22token%20punctuation%22%3E.%3C/span%3E%3Cspan%20class=%22token%20function%22%3Ejoin%3C/span%3E%3Cspan%20class=%22token%20punctuation%22%3E(%3C/span%3E%3Cspan%20class=%22token%20string%22%3E'/'%3C/span%3E%3Cspan%20class=%22token%20punctuation%22%3E)}/)`;
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到地图

new maplibregl.Marker({element: el})
    .setLngLat(marker.geometry.coordinates)
    .addTo(map);

Marker 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 参数：

new maplibregl.Marker({element: el, anchor: 'bottom'})

Q3: 如何移除 Marker？
A: 调用 Marker 实例的 remove() 方法：

const marker = new maplibregl.Marker({element: el}).addTo(map);
marker.remove();

Q4: 可以给 Marker 添加弹窗吗？
A: 可以，使用 setPopup() 方法：

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

📝 练习任务

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

🌟 最佳实践

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

🔗 延伸阅读

Map API文档
MapLibre GL JS 官方文档
[下一课预告]：将继续学习地图图层的基础知识

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

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

📌 学习目标

🎯 核心概念

💻 完 整 代 码

代码示例

代码示例

🔍 代码解析

初始化地图

关键配置项

创建自定义DOM元素

添加Marker到地图

Marker CSS样式

⚙️ 参数说明

Marker 构造参数

Marker 方法

🎨 效果说明

💡 常 见 问 题

📝 练习任务

🌟 最佳实践

🔗 延伸阅读

💻 完整代码

💡 常见问题