Marker、Popup 与 Symbol
🎯 引言
学完本文,你能为少量位置添加自定义 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。
🧪 小练习
- 创建一个带无障碍名称的按钮 Marker,并绑定 Popup。
- 为点 Source 添加同时显示图标和名称的 Symbol Layer。
// 请在这里编写代码
🎉 恭喜你已经掌握 Marker、Popup 与 Symbol 的选择和使用啦!
