Marker、Popup 与 Symbol

掌握 Marker、Popup 和 Symbol Layer 的用法,并根据数据规模选择 DOM 或地图图层。

🎯 引言

学完本文,你能为少量位置添加自定义 Marker 与 Popup,也能用 Symbol Layer 高效显示大量图标和文字。

本文会依次讲清 Marker、Popup 和 Symbol Layer 的写法,最后用一个地图组件对照它们的显示效果。


🧱 Marker 是地图上的 DOM 元素

Marker 不是普通 Layer,它把 HTML 元素定位到经纬度,适合少量、需要复杂 HTML 或独立交互的对象。

const element = document.createElement('button')
element.className = 'map-marker'
element.textContent = 'A'
element.setAttribute('aria-label', '查看站点 A')

const marker = new mapboxgl.Marker({ element })
    .setLngLat([116.397, 39.909])
    .addTo(map)

marker.setLngLat([116.407, 39.919])

function removeMarker() {
    marker.remove()
}

自定义 Marker 样式写在页面 CSS 中。大量 DOM Marker 会增加布局、绘制和事件处理成本,因此不适合成百上千个业务点。


💬 Marker 与 Popup 联动

const popup = new mapboxgl.Popup({ offset: 20 })
    .setText('站点 A')

const marker = new mapboxgl.Marker()
    .setLngLat([116.397, 39.909])
    .setPopup(popup)
    .addTo(map)

popup.setText('站点 A:在线')

function closePopup() {
    popup.remove()
}

setPopup 会让用户点击 Marker 时打开或关闭 Popup。需要由前端框架渲染复杂详情时,可创建 DOM 容器后使用 setDOMContent;页面或组件销毁时,还要同时销毁挂载内容、Marker 和 Popup。


🏷 Symbol Layer 显示图标和文字

map.loadImage('/images/place.png', (error, image) => {
    if (error || !image) return

    if (!map.hasImage('place-icon')) {
        map.addImage('place-icon', image)
    }

    map.addLayer({
        id: 'place-symbols',
        type: 'symbol',
        source: 'places',
        layout: {
            'icon-image': 'place-icon',
            'icon-size': 0.6,
            'text-field': ['get', 'name'],
            'text-offset': [0, 1.2],
            'text-size': 12,
        },
        paint: {
            'text-color': '#1f2937',
            'text-halo-color': '#ffffff',
            'text-halo-width': 1,
        },
    })
})

icon-image 指向已加入 Style 的图片名称,text-field 决定标签内容。Symbol Layer 由 WebGL 统一绘制,适合大量图标和标签,还会处理符号碰撞与隐藏。

下面是以上示例在地图中的实际效果:左侧红色圆点是 DOM Marker,上方气泡是与它绑定的 Popup;右侧两个紫色点和文字分别由 Circle Layer 与 Symbol Layer 绘制。


⚖️ Marker 还是 Symbol Layer

需求建议
少量可拖拽位置Marker
少量复杂 HTML 控件Marker
大量业务点和文字Symbol Layer
需要筛选、表达式和聚合Symbol/Circle Layer
单个临时提示Popup

常见项目会混合使用:大量业务对象使用 Layer,当前选中的一个对象再用 Popup 或少量 DOM 控件补充交互。


🧾 小节总结

  • Marker 是跟随地图位置移动的 DOM 元素。
  • Popup 支持打开、关闭和更新内容,也能与 Marker 绑定。
  • Symbol Layer 使用 icon-image 和 text-field 显示图标与文字。
  • 大量点优先使用地图 Layer,不要创建大量 DOM Marker。
  • 少量复杂控件和大量业务对象可以采用不同方案。

❓ 知识问答

Q1:Marker 能使用 Mapbox 表达式吗?

不能直接使用。Marker 样式由 DOM 和 CSS 控制,表达式属于 Style Layer。

Q2:为什么 Symbol 文字没有全部显示?

Mapbox 默认隐藏发生碰撞的符号。应先优化文字长度、偏移和缩放级别,不要立即关闭碰撞检测。

Q3:Popup 内容来自接口时能直接用 setHTML 吗?

不建议。未清理的 HTML 可能带来安全问题,普通文本用 setText。


🧪 小练习

  1. 创建一个带无障碍名称的按钮 Marker,并绑定 Popup。
  2. 为点 Source 添加同时显示图标和名称的 Symbol Layer。
// 请在这里编写代码

🎉 恭喜你已经掌握 Marker、Popup 与 Symbol 的选择和使用啦!