首页 / Leaflet / API 文档

Popup

先看结论

锚定在地图坐标上的浮动面板，带指向箭头，同一时间通常只显示一个。

最后验证 2026-11-03 · Leaflet 1.9.4 · 更新 2026-10-27 · 引用本文

L.popup(options?, latlng?, content?) → Popup

构造参数

参数	默认	说明
`maxWidth`	300	最大宽度（像素），超出自动换行
`minWidth`	50	最小宽度
`maxHeight`	null	最大高度，超出出现滚动条
`autoPan`	true	弹窗超出视野时自动平移地图
`autoPanPadding`	[5, 5]	自动平移时保留的边距
`keepInView`	false	用户拖动地图时保持弹窗可见
`closeButton`	true	右上角关闭按钮
`closeOnClick`	false	点击地图其他位置时关闭
`closeOnEscapeKey`	true	Esc 关闭
`autoClose`	true	打开新弹窗时关闭旧弹窗
`offset`	[0, 7]	相对锚点的像素偏移
`className`	''	附加类名，用于自定义外观
`pane`	'popupPane'	渲染 pane

方法

方法	说明
`setLatLng(latlng)`	修改锚点
`getLatLng()`	读取锚点
`setContent(html \| node)`	替换内容，字符串按 HTML 解析
`getContent()`	读取当前内容
`openOn(map)`	在地图上打开
`close()`	关闭
`isOpen()`	是否处于打开状态
`getElement()`	返回容器 DOM，可继续挂事件
`update()`	位置或内容变化后重算布局

事件

事件	触发对象	`e` 中的字段
`popupopen`	地图	`popup`、`layer`（绑定的图层，独立弹窗为 undefined）
`popupclose`	地图	`popup`、`layer`

var map = L.map('map', { center: [39.907359, 116.391263], zoom: 13 });

L.marker([39.907359, 116.391263])
  .bindPopup('<b>天安门</b><br>39.907359, 116.391263', {
    maxWidth: 240,
    closeOnClick: true
  })
  .addTo(map);

/* 独立弹窗，不依赖图层 */
var popup = L.popup()
  .setLatLng([39.92, 116.42])
  .setContent('独立弹窗')
  .openOn(map);

map.on('popupopen', function (e) {
  console.log('已打开', e.popup.getLatLng());
});

内容按 HTML 解析，不要直接拼接用户输入。名称、备注这类字段来自接口时，先转义 &、<、> 再拼接；或者用 DOM 节点作为内容，天然避免注入。

图层绑定与独立弹窗

layer.bindPopup() 让弹窗跟随图层位置，图层移动时弹窗自动跟随，点击图层可配置为开合。独立 L.popup 需要手动 openOn，适合「点击地图任意位置显示坐标」这类没有对应要素的场景。

autoClose 默认会在打开新弹窗时关闭旧弹窗。需要同时展示多个独立弹窗时，给每个都设置 autoClose: false，并自行管理它们的生命周期。

内容更新

弹窗打开期间数据变化，调 setContent 后必须再调 update()，否则尺寸和箭头位置仍按旧内容计算。如果只是文字长度变化，可以先判断 isOpen()，避免对关闭状态的弹窗做无谓布局。

样式定制

className 会加到弹窗容器上，配合全局 CSS 修改圆角、阴影、背景。修改 .leaflet-popup-content-wrapper 会影响全站所有弹窗，只想改一个弹窗时务必使用自定义类名限定范围。

引用本文

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