首页 / MapLibre / API 文档

Popup 选项

先看结论

浮在地图上的信息窗，构造选项决定关闭方式、最大宽度与锚点方位。

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

new maplibregl.Popup({ closeButton: false, maxWidth: '320px', offset: 12 })

选项

字段	默认	说明
`closeButton`	true	右上角关闭按钮
`closeOnClick`	true	点击地图任意位置时关闭
`closeOnMove`	false	地图移动时关闭
`focusAfterOpen`	true	打开后把焦点移入弹窗，便于键盘操作
`anchor`	未设	气泡相对坐标的方位，如 `'top'`、`'bottom-left'`
`offset`	未设	像素偏移，数字或 `[x, y]`，构造后不可改
`className`	`''`	追加到容器上的类名，用于自定义外观
`maxWidth`	`'240px'`	CSS 长度，需带单位
`subpixelPositioning`	false	按小数像素定位，减少移动时的抖动
`locationOccludedOpacity`	未设	被地形遮挡时的不透明度
`padding`	未设	与地图内边距配合，避免被控件盖住

成员

成员	说明
`setLngLat(lnglat)` / `getLngLat()`	设置或读取锚点坐标
`addTo(map)`	挂到地图上并显示
`remove()` / `isOpen()`	关闭、查询状态
`setText(text)`	纯文本内容，自动转义
`setHTML(html)`	HTML 字符串，来源可信时使用
`setDOMContent(node)`	直接挂 DOM 节点，可绑定事件
`setMaxWidth(width)` / `getMaxWidth()`	读写最大宽度
`trackPointer()`	跟随鼠标位置移动
`toggleClassName(name)`	切换样式类
`open` / `close` 事件	打开与关闭时触发

示例

var card = document.createElement('div');
card.className = 'poi-card';
card.innerHTML = '滨江观测站水位 4.2 m，更新于 08:00';

var popup = new maplibregl.Popup({
  closeButton: false,
  closeOnClick: false,
  maxWidth: '320px',
  anchor: 'bottom',
  offset: 14,
  className: 'poi-popup'
})
  .setLngLat([120.16, 30.28])
  .setDOMContent(card)
  .addTo(map);

map.on('click', 'stations', function (e) {
  var f = e.features[0];
  popup
    .setLngLat(f.geometry.coordinates)
    .setText(f.properties.name + ' · ' + f.properties.value)
    .addTo(map);
});

注意事项

offset 只在构造时生效，没有对应的 setter。需要动态偏移时，销毁旧弹窗重新创建，或给内容套一层带 margin 的容器。

maxWidth 写数字不带单位时样式无效，弹窗会被内容撑到很长一行。统一写 '240px'、 '20rem' 这类完整长度。

内容来源决定用哪个 setter。setText 会转义，适合用户输入；setHTML 直接插入标签，只用于自有模板；复杂交互一律用 setDOMContent。

引用本文

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