首页 / Leaflet / API 文档
ImageOverlay
先看结论
把一张普通图片按地理范围铺在地图上，随缩放一起变形。
L.imageOverlay(imageUrl, bounds, options) → ImageOverlay
参数
| 参数 | 类型 | 说明 |
|---|---|---|
imageUrl | String | 图片地址，可为相对路径、data URL 或 HTMLImageElement |
bounds | LatLngBounds | 图片四边对应的地理范围，[[南, 西], [北, 东]] |
options | Object | 透明度、层级与跨域选项，见下表 |
选项
| 选项 | 默认值 | 说明 |
|---|---|---|
opacity | 1 | 整体不透明度 |
alt | '' | 图片的替代文本 |
interactive | false | 是否响应点击等鼠标事件 |
crossOrigin | false | 是否带 crossorigin 请求；要在 canvas 里合成时必须开 |
errorOverlayUrl | '' | 图片加载失败时替换的地址 |
zIndex | 1 | 同一 pane 内的层级 |
className | '' | 附加 class，用于 CSS 滤镜等 |
pane | 'overlayPane' | 所在 pane，改用自定义 pane 可控制压盖关系 |
成员
| 成员 | 返回值 | 说明 |
|---|---|---|
setUrl(url) | this | 替换图片地址，保留当前范围与样式 |
setBounds(bounds) | this | 重新设定图片覆盖范围 |
getBounds() | LatLngBounds | 当前范围 |
setOpacity(opacity) | this | 改透明度，值域 0–1 |
setStyle({ opacity }) | this | Firefox 下等价于 setOpacity |
setZIndex(zIndex) | this | 调整叠放层级 |
bringToFront() / bringToBack() | this | 置于同 pane 图层的前/后 |
getElement() | HTMLImageElement | 取到底层 img，可读 naturalWidth |
var bounds = [[39.880, 116.360], [39.940, 116.450]];
var overlay = L.imageOverlay(
'https://example.com/radar/2026-10-28-08.png',
bounds,
{ opacity: 0.55, crossOrigin: true, zIndex: 2 }
).addTo(map);
/* 逐帧切换，用 setUrl 而不是重建图层，避免闪烁 */
var frames = ['08.png', '09.png', '10.png'];
var i = 0;
setInterval(function () {
i = (i + 1) % frames.length;
overlay.setUrl('/radar/' + frames[i]);
}, 1200);
/* 放在 canvas 里合成导出时，范围要从图片自身尺寸推算 */
var b = overlay.getBounds();
console.log(b.getSouth(), b.getWest(), b.getNorth(), b.getEast());图片必须是等距圆柱投影的矩形。bounds 的四边会分别贴到
图片的四边，Leaflet 不会做透视或裁剪。带投影参数的产品图（比如 NC 文件渲染出的
等经纬度栅格）才能直接用；墨卡托投影的 GeoTIFF 需要先重投影成 3857 或切片成瓦片。
跨域图片加 crossOrigin: true 时，服务器必须返回
Access-Control-Allow-Origin，否则图片不显示。若只是展示，
保持默认 false 更稳；要读像素或导出 canvas 才开启。
经纬志（2026）。《ImageOverlay》。https://www.jingweizhi.com/leaflet/api/image-overlay.html（访问日期 2026-11-03）。