---
title: "MapboxVideoLayer"
description: "视频覆盖图层，把视频按四角经纬度贴合到地图，暴露播放控制。"
seo_title: "MapboxVideoLayer Component"
seo_description: "MapboxVideoLayer overlays a georeferenced video onto the map by four corner coordinates and exposes play, pause and the underlying video element."
canonical_url: "https://mapbox.mhaibaraai.cn/docs/layers/video"
---
# MapboxVideoLayer

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

## 简介

`MapboxVideoLayer` 把视频按四角经纬度贴合到地图（多格式 `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]
]

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">
    <MapboxMap :options="{ style: 'mapbox://styles/mapbox/satellite-streets-v12', 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>
      <MapboxVideoLayer ref="videoLayer" :urls="urls" :coordinates="coordinates" />
    </MapboxMap>
  </div>
</template>
```

## API

### Props

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

### Expose

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

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

## Changelog

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


## Sitemap

See the full [sitemap](/sitemap.md) for all pages.