首页 / MapLibre / API 文档

Marker 选项

先看结论

基于 DOM 的标记，位置随地图变换，样式与交互完全交给页面控制。

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

new maplibregl.Marker({ color: '#e8590c', scale: 1.2, draggable: true })

选项

字段	默认	说明
`element`	自动生成	自定义 DOM 元素，传了就忽略内置图标
`anchor`	`'center'`	标记与坐标的对齐点
`offset`	`[0, 0]`	像素偏移，可用 `setOffset` 修改
`color`	`'#3FB1CE'`	内置水滴图标颜色
`scale`	1	图标整体缩放
`draggable`	false	是否允许拖动
`clickTolerance`	0	判定为点击的像素位移容差
`rotation`	0	图标旋转角度，度
`rotationAlignment`	`'auto'`	相对地图还是屏幕旋转
`pitchAlignment`	`'auto'`	倾斜时是否随地面变形
`opacity`	1	不透明度
`opacityWhenCovered`	0.2	被地形遮挡时的不透明度
`subpixelPositioning`	false	按小数像素定位，移动更平滑

成员

成员	说明
`setLngLat(lnglat)` / `getLngLat()`	设置或读取坐标
`addTo(map)` / `remove()`	挂载与移除
`getElement()`	取回 DOM 节点，可继续改内容
`setPopup(popup)` / `togglePopup()`	绑定点击弹出的信息窗
`setDraggable(bool)` / `isDraggable()`	开关拖动
`setOffset(offset)` / `getOffset()`	运行时调整偏移
`setRotation(deg)` / `getRotation()`	旋转图标
`setRotationAlignment(a)` / `setPitchAlignment(a)`	切换对齐方式
`setOpacity(o, oCovered)`	调整普通与遮挡状态下的不透明度
`dragstart` / `drag` / `dragend`	拖动过程事件，`dragend` 适合回写坐标

示例

var el = document.createElement('div');
el.className = 'pin';
el.textContent = '观测站';

var marker = new maplibregl.Marker({
  element: el,
  anchor: 'bottom',
  draggable: true
})
  .setLngLat([120.16, 30.28])
  .addTo(map);

marker.on('dragend', function () {
  var p = marker.getLngLat();
  fetch('/api/station/position', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ lng: p.lng, lat: p.lat })
  });
});

/* 内置图标，改颜色与大小 */
new maplibregl.Marker({ color: '#e8590c', scale: 1.3 })
  .setLngLat([121.47, 31.23])
  .addTo(map);

注意事项

每个 Marker 都是一个 DOM 节点，几百个还能接受，上千个会明显拖慢拖动与缩放。密集点位改用 symbol 图层，绘制在 WebGL 里，性能量级完全不同。

anchor 决定标记的哪个点对准坐标。自定义元素默认居中，底部带尖角的气泡图需要设 'bottom'，否则尖端会浮在坐标上方。

拖出地图边界。拖动时不限制范围，标记可以落到地图外。需要约束时在 dragend 里检查 map.getBounds().contains(p)，不满足就把 setLngLat 设回边界内。

引用本文

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