---
title: "MaplibreVideoLayer"
description: "视频覆盖图层，把视频按四角经纬度贴合到地图，暴露播放控制。"
canonical_url: "https://maplibre.mhaibaraai.cn/docs/layers/video"
---
# MaplibreVideoLayer

> 视频覆盖图层，把视频按四角经纬度贴合到地图，暴露播放控制。

## 简介

`MaplibreVideoLayer` 把视频按四角经纬度贴合到地图（多格式 `urls` 回退），内部以 `video` 源 + `raster` 图层实现，并经 `defineExpose` 暴露 `play` / `pause` / `video` 供编程控制。

## 用法

叠加无人机航拍视频，按钮控制播放：

```vue [VideoLayerExample.vue]
<script setup lang="ts">
const videoLayer = useTemplateRef('videoLayer')

// 四角经纬度：左上 / 右上 / 右下 / 左下
const coordinates: [[number, number], [number, number], [number, number], [number, number]] = [
  [-122.51596391201019, 37.56238816766053],
  [-122.51467645168304, 37.56410183312965],
  [-122.51309394836426, 37.563391708549425],
  [-122.51423120498657, 37.56161849366671]
]

// Esri World Imagery 栅格影像，无需 key
const imagery = ['https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}']

const urls = [
  'https://static-assets.mapbox.com/mapbox-gl-js/drone.mp4',
  'https://static-assets.mapbox.com/mapbox-gl-js/drone.webm'
]
</script>

<template>
  <div class="h-115 w-full overflow-hidden rounded-(--ui-radius) border border-default">
    <MaplibreMap :options="{ center: [-122.514, 37.563], zoom: 17, bearing: -96 }">
      <div class="absolute left-3 top-3 z-10 flex gap-2">
        <UButton size="xs" color="neutral" variant="solid" @click="videoLayer?.play()">
          Play
        </UButton>
        <UButton size="xs" color="neutral" variant="solid" @click="videoLayer?.pause()">
          Pause
        </UButton>
      </div>
      <MaplibreRasterLayer :tiles="imagery" :tile-size="256" attribution="Tiles © Esri" />
      <MaplibreVideoLayer ref="videoLayer" :urls="urls" :coordinates="coordinates" />
    </MaplibreMap>
  </div>
</template>
```

## API

### Props

```ts
/**
 * Props for the MaplibreVideoLayer component
 */
interface MaplibreVideoLayerProps {
  /**
   * 视频地址列表（多格式回退）
   */
  urls: string[];
  /**
   * 四角经纬度：左上/右上/右下/左下
   */
  coordinates: [[number, number], [number, number], [number, number], [number, number]];
  /**
   * 图层 id；省略时自动生成，变更需配合 `:key` 重建
   */
  layerId?: string | undefined;
  /**
   * 不透明度
   * @default 1
   */
  opacity?: number | undefined;
  /**
   * 插入到该图层之前
   */
  beforeId?: string | undefined;
}
```

### Expose

通过 [`useTemplateRef`](https://vuejs.org/api/composition-api-helpers.html#usetemplateref) 访问组件实例。

| Name | Type |
| --- | --- |
| `play` | `() => void` <br> 播放视频 |
| `pause` | `() => void` <br> 暂停视频 |
| `video` | `() => HTMLVideoElement \| undefined` <br> 底层 video 元素 |

## Changelog

See commit history for [src/runtime/components/layers/VideoLayer.vue](https://github.com/mhaibaraai/movk-maplibre/commits/main/src/runtime/components/layers/VideoLayer.vue).


## Sitemap

See the full [sitemap](https://maplibre.mhaibaraai.cn/sitemap.md) for all pages.