首页 / MapLibre / API 文档

VideoSource

先看结论

把视频作为栅格图层铺在指定经纬度范围内，常用于监控画面、流场演示与动态云图。

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

map.addSource(id, { type: 'video', urls: [...], coordinates: [四点] })

参数

字段	默认	说明
`urls`	—	视频地址数组，必填；按顺序尝试，可给 mp4 与 webm 各一份
`coordinates`	—	左上、右上、右下、左下四角经纬度

源加载成功后会自动创建一个 <video> 元素，设置 loop 并尝试播放。浏览器对带声音的自动播放有拦截，被拦下时画面停在第一帧，需要在用户点击后调用 play()。

成员

成员	说明
`play()`	开始或继续播放
`pause()`	暂停在当前帧
`seek(seconds)`	跳到指定秒数
`getVideo()`	取回内部 video 元素，可读时长、调音量
`setCoordinates(coordinates)`	移动视频覆盖范围
`data` 事件	元数据就绪，可以读取时长
`error` 事件	编解码不支持或跨域被拦

示例

map.addSource('clip', {
  type: 'video',
  urls: [
    'https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4'
  ],
  coordinates: [
    [110.0, 35.0],
    [115.0, 35.0],
    [115.0, 30.0],
    [110.0, 30.0]
  ]
});

map.addLayer({
  id: 'clip',
  type: 'raster',
  source: 'clip',
  paint: {
    'raster-opacity': 0.9,
    'raster-fade-duration': 0
  }
});

/* 播放控制挂在按钮上，避开自动播放限制 */
document.getElementById('play').addEventListener('click', function () {
  map.getSource('clip').play();
});

注意事项

raster-fade-duration 默认会让视频在开始播放、暂停恢复、坐标变更时淡入一次，看起来像闪一下。视频图层把它设成 0，画面切换才是即时的。

视频纹理的清晰度取决于视频分辨率与覆盖面积的比值。把 640×360 的视频铺到整个省份范围，放大后必然模糊，这不是渲染问题，而是源分辨率不足。

跨域与编码。视频服务器需要返回 CORS 头，否则纹理无法上传。编码上优先 H.264 的 mp4，部分环境不支持 webm；同时给出两种格式， urls 会按顺序回退。

引用本文

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