首页 / Leaflet / API 文档

VideoOverlay

先看结论

把视频铺在指定的地理范围上播放，接口与图片叠加一致。

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

L.videoOverlay(video, bounds, options) → VideoOverlay

参数

参数	类型	说明
`video`	String / String[] / HTMLVideoElement	视频地址、多格式地址数组，或已创建的视频节点
`bounds`	LatLngBounds	视频画面四边对应的地理范围
`options`	Object	继承 ImageOverlay，另加播放选项

选项

选项	默认值	说明
`autoplay`	true	加载后自动播放
`loop`	true	循环播放
`keepAspectRatio`	true	按原始比例铺放，避免画面拉伸
`muted`	false	静音播放；浏览器自动播放通常要求为 true
`playsInline`	true	移动端原地播放，不跳系统全屏播放器
`opacity`	1	整体不透明度
`alt`	''	替代文本
`interactive`	false	视频节点是否响应鼠标事件
`crossOrigin`	false	跨域请求标记
`errorOverlayUrl`	''	加载失败时的替代图片
`zIndex`	1	同 pane 内层级
`className`	''	附加 class
`pane`	'overlayPane'	所在 pane

成员

成员	返回值	说明
`getElement()`	HTMLVideoElement	取到视频节点，用原生 API 控制播放
`getBounds()`	LatLngBounds	当前覆盖范围
`setBounds(bounds)`	this	重新定位画面
`setOpacity(opacity)`	this	调整透明度
`setUrl(url)`	this	换片源并重新加载
`setZIndex(zIndex)`	this	调整层级
`bringToFront()` / `bringToBack()`	this	叠放顺序

var bounds = [[39.895, 116.378], [39.920, 116.405]];

var video = L.videoOverlay(
  ['/media/flow.webm', '/media/flow.mp4'],
  bounds,
  { opacity: 0.75, autoplay: true, loop: true, muted: true }
).addTo(map);

/* 浏览器允许静音自动播放，带声音的 autoplay 会被拦截 */
var el = video.getElement();
el.muted = true;
el.play().catch(function () {
  console.warn('自动播放被拦截，等待用户交互');
});

document.getElementById('toggle').addEventListener('click', function () {
  el.paused ? el.play() : el.pause();
});

播放失败多数不是 Leaflet 的问题。桌面浏览器只放行静音或用户交互后的有声播放，移动端还要求节点带 playsinline，否则会跳到系统全屏播放器。通过 getElement() 拿到节点后补上 muted、 playsinline，再调用 play() 更可靠。

视频按 bounds 拉伸，宽高比与视频原始比例不一致时会变形。先把 bounds 的经纬跨度调成与视频像素比一致，或接受轻微拉伸。视频作为叠加层会盖住矢量，需要矢量压在视频上时把视频放到自定义的低层级 pane。

直接传入 HTMLVideoElement 时，autoplay、loop、 muted 这些选项不会被应用到该节点，源码在这种情况下会提前返回。需要自动播放就自己给节点设置属性并调用 play()。

引用本文

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