首页 / OpenLayers / API 文档

Overlay

先看结论

覆盖层。把一段普通 DOM 绑定到地图坐标上，随视图平移缩放自动跟随，用来放弹窗、标注和图例。

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

new ol.Overlay(options)

构造参数

参数	说明
`element`	DOM 元素或元素 id，必填
`position`	锚定的地图坐标，省略时覆盖层不显示
`positioning`	锚点方位，默认 `'top-left'`
`offset`	像素偏移 `[x, y]`，默认 `[0, 0]`，y 向下为正
`stopEvent`	是否拦截覆盖层内的鼠标事件，默认 true
`insertFirst`	是否插到覆盖层容器首位，默认 true
`autoPan`	超出视口时自动平移地图，默认 false
`autoPanMargin`	自动平移保留的边距像素，默认 20
`className`	容器类名，默认 `'ol-overlay-container ol-selectable'`

常用方法

方法	返回	说明
`setPosition(coord)`	void	设置锚点，传 undefined 可隐藏
`getPosition()`	Coordinate	取当前锚点坐标
`setElement(el)`	void	替换内容元素
`setOffset(offset)`	void	调整像素偏移
`setPositioning(pos)`	void	调整锚点方位
`panIntoView()`	void	把覆盖层平移进可视区域

var el = document.createElement('div');
el.className = 'popup';

var popup = new ol.Overlay({
  element: el,
  positioning: 'bottom-center',
  offset: [0, -14],
  autoPan: true,
  autoPanMargin: 24,
  stopEvent: true
});
map.addOverlay(popup);

map.on('singleclick', function (evt) {
  el.innerHTML = '<b>点位</b><br>' +
    ol.coordinate.toStringXY(ol.proj.toLonLat(evt.coordinate), 5);
  popup.setPosition(evt.coordinate);
});

注意事项

position 为空时覆盖层保持在 DOM 中但不渲染，隐藏用 setPosition(undefined) 比直接改 CSS 更稳妥。
stopEvent 为 true 时覆盖层内的点击、滚轮不会传给地图；需要在地图上继续响应事件就设为 false。
offset 的 y 轴向下为正，做气泡尖端对齐时要给负值才能把元素抬到坐标上方。
元素只有在 addOverlay 之后才会进入地图容器，构造前设置尺寸或测量宽高会拿到 0。

引用本文

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