---
name: "native-video"
mode: "component"
versionRequirements:
  - { name: "基础库", version: "2.10.0" }
title: "native-video - 视频"
---

## native-video

> [VERSION] 基础库 >= 2.10.0

### 描述

原生视频播放组件，渲染层由客户端实现，仅支持原生环境。

### 属性

| 属性 | 类型 | 必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `hidden` | `boolean` | 否 | - | 是否隐藏组件 |
| `src` | `string` | 否 | - | 视频资源地址 |
| `poster` | `string` | 否 | - | 视频封面图地址 |
| `controls` | `boolean` | 否 | - | 是否显示默认播放控件 |
| `duration` | `number` | 否 | `0` | 指定视频时长 |
| `autoplay` | `boolean` | 否 | - | 是否自动播放 |
| `loop` | `boolean` | 否 | - | 是否循环播放 |
| `muted` | `boolean` | 否 | - | 是否静音播放 |
| `initial-time` | `number` | 否 | `0` | 指定视频初始播放位置，单位秒 |
| `object-fit` | `string` | 否 | `"contain"` | 视频的裁剪模式，可选值：contain 包含，fill 填充，cover 覆盖 |
| `show-fullscreen-btn` | `boolean` | 否 | - | 是否显示全屏按钮 |
| `show-play-btn` | `boolean` | 否 | - | 是否显示播放按钮 |
| `show-mute-btn` | `boolean` | 否 | - | 是否显示静音按钮 |
| `show-center-play-btn` | `boolean` | 否 | - | 是否显示视频中间的播放按钮 |
| `auto-pause` | `boolean` | 否 | - | 当跳转到其他页面时，是否自动暂停本页面的视频 |
| `background-color` | `string` | 否 | `"#ffffff"` | 背景颜色，必须为十六进制颜色值 |
| `border-width` | `number` | 否 | `0` | 边框宽度，单位 px |
| `border-style` | `string` | 否 | `"solid"` | 边框样式 |
| `border-color` | `string` | 否 | `"#ffffff"` | 边框颜色，必须为十六进制颜色值 |
| `border-radius` | `number` | 否 | `0` | 统一设置四角圆角半径，单位 px |
| `border-radius-top-left` | `number` | 否 | - | 左上角圆角半径，单位 px，-1 表示使用 border-radius |
| `border-radius-top-right` | `number` | 否 | - | 右上角圆角半径，单位 px，-1 表示使用 border-radius |
| `border-radius-bottom-left` | `number` | 否 | - | 左下角圆角半径，单位 px，-1 表示使用 border-radius |
| `border-radius-bottom-right` | `number` | 否 | - | 右下角圆角半径，单位 px，-1 表示使用 border-radius |

#### 事件

| 事件名 | 类型 | 描述 |
| --- | --- | --- |
| `play` | `(event: Object) => void` | 开始/继续播放时触发 |
| `pause` | `(event: Object) => void` | 暂停播放时触发 |
| `ended` | `(event: Object) => void` | 播放到末尾时触发 |
| `timeupdate` | `(event: NativeVideoTimeupdateEvent) => void` | 播放进度变化时触发 |
| `fullscreenchange` | `(event: NativeVideoFullscreenchangeEvent) => void` | 视频进入和退出全屏时触发 |
| `waiting` | `(event: Object) => void` | 视频出现缓冲时触发 |
| `error` | `(event: NativeVideoErrorEvent) => void` | 视频播放出错时触发 |
| `progress` | `(event: NativeVideoProgressEvent) => void` | 加载进度变化时触发 |
| `loadedmetadata` | `(event: NativeVideoLoadedmetadataEvent) => void` | 视频元数据加载完成时触发 |
| `controlstoggle` | `(event: NativeVideoControlstoggleEvent) => void` | 切换 controls 显示隐藏时触发 |
| `seekcomplete` | `(event: NativeVideoSeekcompleteEvent) => void` | seek 完成时触发 |

**play 的回调参数对象**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"play"` |  |

**pause 的回调参数对象**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"pause"` |  |

**ended 的回调参数对象**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"ended"` |  |

**NativeVideoTimeupdateEvent**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"timeupdate"` | 事件类型 |
| `detail` | `NativeVideoTimeupdateDetail` | 事件数据 |

**NativeVideoFullscreenchangeEvent**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"fullscreenchange"` | 事件类型 |
| `detail` | `NativeVideoFullscreenchangeDetail` | 事件数据 |

**waiting 的回调参数对象**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"waiting"` |  |

**NativeVideoErrorEvent**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"error"` | 事件类型 |
| `detail` | `NativeVideoErrorDetail` | 事件数据 |

**NativeVideoProgressEvent**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"progress"` | 事件类型 |
| `detail` | `NativeVideoProgressDetail` | 事件数据 |

**NativeVideoLoadedmetadataEvent**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"loadedmetadata"` | 事件类型 |
| `detail` | `NativeVideoLoadedmetadataDetail` | 事件数据 |

**NativeVideoControlstoggleEvent**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"controlstoggle"` | 事件类型 |
| `detail` | `NativeVideoControlstoggleDetail` | 事件数据 |

**NativeVideoSeekcompleteEvent**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"seekcomplete"` | 事件类型 |
| `detail` | `NativeVideoSeekcompleteDetail` | 事件数据 |

### 示例代码

#### 基础用法

*index.tyml*

```xml
<native-video
  src="{{videoSrc}}"
  controls="{{true}}"
  class="video"
  bindplay="onPlay"
  bindpause="onPause"
  bindended="onEnded"
/>
```

*index.tyss*

```css
.video {
  width: 100%;
  height: 400rpx;
}
```

*index.js*

```javascript
Page({
  data: {
    videoSrc: 'https://images.tuyacn.com/rms-static/602542e0-48f8-11f1-95db-cfd3b8132c07-1778036702734.mp4',
  },
  onPlay() {
    console.log('开始播放');
  },
  onPause() {
    console.log('暂停播放');
  },
  onEnded() {
    console.log('播放结束');
  },
});
```

#### 播放配置与封面

*index.tyml*

```xml
<native-video
  src="{{videoSrc}}"
  poster="{{posterUrl}}"
  controls="{{true}}"
  autoplay="{{false}}"
  loop="{{true}}"
  muted="{{true}}"
  initial-time="{{3}}"
  object-fit="cover"
  show-fullscreen-btn="{{true}}"
  show-play-btn="{{true}}"
  show-center-play-btn="{{false}}"
  show-mute-btn="{{true}}"
  class="video"
  binderror="onError"
  bindwaiting="onWaiting"
/>
```

*index.tyss*

```css
.video {
  width: 100%;
  height: 400rpx;
}
```

*index.js*

```javascript
Page({
  data: {
    videoSrc: 'https://images.tuyacn.com/rms-static/602542e0-48f8-11f1-95db-cfd3b8132c07-1778036702734.mp4',
    posterUrl: 'https://vjs.zencdn.net/v/oceans.png',
  },
  onError(e) {
    console.log('播放错误:', e.detail.errMsg);
  },
  onWaiting() {
    console.log('缓冲中');
  },
});
```

#### 静音自动播放

*index.tyml*

```xml
<native-video
  src="{{videoSrc}}"
  autoplay="{{true}}"
  muted="{{true}}"
  loop="{{true}}"
  controls="{{false}}"
  show-center-play-btn="{{false}}"
  auto-pause="{{true}}"
  class="video"
/>
```

*index.tyss*

```css
.video {
  width: 100%;
  height: 400rpx;
  border-radius: 16rpx;
}
```

*index.js*

```javascript
Page({
  data: {
    videoSrc: 'https://images.tuyacn.com/rms-static/602542e0-48f8-11f1-95db-cfd3b8132c07-1778036702734.mp4',
  },
});
```


### 相关文档

- 相关 API：[ty.createNativeVideoContext](/cn/miniapp/develop/miniapp/api/media/native-video/createNativeVideoContext)
- 这是基于异层渲染的原生组件，请注意 [原生组件使用限制](/cn/miniapp/develop/miniapp/component/native-component/native-component)

### 常见问题

1. `native-video` 默认宽度 300px、高度 225px，可通过 tyss 设置宽高。
2. `native-video` 支持视频格式：MP4（MPEG 4 文件使用 H264 视频编解码器和 AAC 音频编解码器）。