首页 / MapLibre / API 文档

Popup

先看结论

锚定在经纬度上的信息浮层，点击地图或图层要素时最常使用。

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

new maplibregl.Popup(options) → Popup

构造参数

参数	默认	说明
`closeButton`	true	是否显示关闭按钮
`closeOnClick`	true	点击地图其他位置自动关闭
`closeOnMove`	false	地图移动时关闭
`anchor`	自动	相对坐标点的方位，如 `top`、`bottom-left`
`offset`	0	像素偏移，避免遮住图标
`maxWidth`	240px	内容最大宽度，超出换行
`className`	—	附加类名，用于自定义外观

内容与位置

方法	说明
`setLngLat(lngLat)`	设置锚点
`setHTML(html)`	按 HTML 渲染内容
`setText(text)`	按纯文本渲染，自动转义
`setDOMContent(node)`	传入 DOM 节点，便于绑定事件
`addTo(map)`	打开弹窗
`remove()`	关闭并移除
`isOpen()`	是否处于打开状态

示例

var popup = new maplibregl.Popup({ offset: 20, closeOnClick: true })
  .setLngLat([116.391263, 39.907359])
  .setHTML('<b>天安门</b><br>经度 116.3913<br>纬度 39.9074')
  .addTo(map);

/* 点击地图，在点击处打开一个新弹窗 */
map.on('click', function (e) {
  popup.setLngLat(e.lngLat).setText(e.lngLat.toString()).addTo(map);
});

点击要素时弹窗

图层上的点击事件会带上 features，通常同时更新锚点与内容：

map.on('click', 'station-dots', function (e) {
  var f = e.features[0];
  new maplibregl.Popup()
    .setLngLat(f.geometry.coordinates.slice())
    .setHTML('<b>' + f.properties.name + '</b>')
    .addTo(map);
});

geometry.coordinates 是数组引用，直接传给弹窗后再被其他地方修改，弹窗位置会跟着变。用 slice() 复制一份是低成本的保险。

内容安全

setHTML 会把字符串当 HTML 插入 DOM。属性值来自用户输入时，攻击者可以注入脚本或伪造界面。不可信数据一律用 setText，需要结构时用 setDOMContent 自己创建节点、设置 textContent。

弹窗不是图层。它始终浮在最上层，不受图层顺序影响；数量多时 DOM 开销明显高于 symbol 图层的文本标注。同时只保留一个弹窗，是最简单也最省资源的做法。

引用本文

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