首页 / MapLibre / API 文档

Marker

先看结论

DOM 元素形式的标记，不参与 WebGL 绘制，适合少量需要交互的图标。

最后验证 2026-11-03 · MapLibre GL JS 4.x · 更新 2026-10-27 · 引用本文

new maplibregl.Marker(options) → Marker

构造参数

参数	默认	说明
`element`	自动生成	自定义 DOM 元素，传入后 `color` 失效
`anchor`	center	锚点位置，如 `bottom`、`top-left`
`color`	#3FB1CE	默认图钉颜色
`draggable`	false	是否允许拖动
`rotation`	0	图标旋转角度，顺时针为正
`scale`	1	图标缩放
`offset`	[0, 0]	相对坐标点的像素偏移
`pitchAlignment`	auto	俯仰时是否跟随地图倾斜

常用方法

方法	说明
`setLngLat(lngLat)`	设置位置，接受数组、对象或 `LngLat`
`getLngLat()`	返回当前 `LngLat`
`addTo(map)`	添加到地图，返回自身，可链式调用
`remove()`	从地图移除
`setPopup(popup)`	点击标记时打开弹窗
`togglePopup()`	手动开关弹窗
`setDraggable(flag)`	运行时切换可拖拽
`getElement()`	取回标记的 DOM 元素，可绑定事件

示例

var popup = new maplibregl.Popup({ offset: 22 })
  .setHTML('<b>天安门</b><br>39.9074, 116.3913');

var marker = new maplibregl.Marker({ color: '#1f5fd0' })
  .setLngLat([116.391263, 39.907359])
  .setPopup(popup)
  .addTo(map);

/* 拖拽结束后读取新位置 */
marker.on('dragend', function () {
  var p = marker.getLngLat();
  console.log(p.lng, p.lat);
});

自定义 DOM 标记

默认图钉是 SVG。需要圆点、数字徽标或业务图标时，自己造一个元素：

var el = document.createElement('div');
el.className = 'my-pin';
el.textContent = '3';
el.addEventListener('click', function () {
  console.log('点了标记');
});

new maplibregl.Marker({ element: el, anchor: 'bottom' })
  .setLngLat([116.42, 39.91])
  .addTo(map);

自定义元素必须自己写样式，包括宽高与定位。没有设置尺寸的 div 宽高为 0，标记会看不见。

性能边界

每个 Marker 都是一个真实 DOM 节点，浏览器要为它布局、合成。几十个没问题，几百个开始卡顿，上千个会明显拖慢拖动。大批量点位改用 circle 或 symbol 图层，它们在 WebGL 里批量绘制，开销与数量几乎无关。

标记不会随地图倾斜而贴地。需要贴地的符号用图层，需要复杂 HTML 交互（按钮、输入框）才用 Marker。

引用本文

经纬志（2026）。《Marker》。https://www.jingweizhi.com/maplibre/api/marker.html（访问日期 2026-11-03）。