# @capgo/capacitor-video-player 中文文档

规范地址：https://npmcn.com/package/%40capgo/capacitor-video-player/

版本：8\.3\.0
npm 元数据更新时间：2026-11-04T13:48:56.778Z
中文译文更新时间：2026-11-09T03:33:23.072Z
软件包许可：MPL-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40capgo/capacitor-video-player
原文对照：https://npmcn.com/package/%40capgo/capacitor-video-player/?lang=original
项目主页：https://capgo.app/docs/plugins/video-player/
源码仓库：https://github.com/Cap-go/capacitor-video-player

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：873 kB，96 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：hls\.js ^1\.4\.0，@capacitor/core \>=8\.0\.0
- 首次发布：2025-10-09T16:37:49.826Z
- 最新版本发布：2026-11-04T13:48:56.410Z
- 近 30 天下载量：47235（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：83（近 12 个月 66 个）

## 中文简介

用本地播放器播放视频的电容插件

## 安装

```sh
npm install @capgo/capacitor-video-player
```

也可以使用：`pnpm add @capgo/capacitor-video-player`、`yarn add @capgo/capacitor-video-player`、`bun add @capgo/capacitor-video-player`

## README

# @ capgo/ 电容- 视频播放器

在您 Capacitor app 的本地全屏播放器中播放视频,并配有字幕,图片和Chromecast支持.

[![Capgo - Build Capacitor apps with AI, ship updates instantly](https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-video-player)](https://capgo.app/?ref=plugin_video_player)

**队长**:在几分钟内将修正推给您的 Capacitor 用户,在没有Mac的情况下构建已签名的iOS和Android apps,并在一击中回滚.

## [\*免费开始\*](https://capgo.app/register/?ref=plugin_video_player)

14天无限自由审判. 不需要信用卡

> 🤖 **建筑与AI编码代理?** 安装 [Capgo 技能](https://capgo.app/skills/?ref=plugin_video_player) 所以克劳德代码,代码,光标,副驾驶,或双子座CLI知道如何安装和使用 `@capgo/capacitor-video-player` 在您的电容应用程序中: `npx skills add Cap-go/capgo-skills`。然后问你的经纪人: _添加@capgo/capor-video-player到我的Capacitor应用程序上,并把它接上"_ [代理设置指南](https://capgo.app/agents/?ref=plugin_video_player) • 妇女 [主机磁共振](https://capgo.app/docs/ai/mcp/?ref=plugin_video_player)

![@capgo/capacitor-video-player for Capacitor apps](https://raw.githubusercontent.com/Cap-go/capacitor-video-player/main/assets/github-social-preview.png)

## 主要特点

-   **玩家**数字 : `initPlayer()` 为 URL 创建播放器,使用 `play()`, (中文(简体) ), `pause()` 财务报告和审定财务报表 `stopAllPlayers()`。 。 。 .
-   **播放控件**数字 : `setCurrentTime()`, (中文(简体) ), `setVolume()`, (中文(简体) ), `setMuted()` 财务报告和审定财务报表 `setRate()`与匹配的获取器.
-   **字幕**: 一个或多个带有语言选项的字幕音轨.
-   **本地额外项目**:图片中的图片,背景模式,末端的回路和Chromecast铸造.
-   **主计长**数字 : `showController()` 财务报告和审定财务报表 `isControllerIsFullyVisible()` 对本地控制.
-   **平台**: iOS,Android和Web. 互联网档案馆的存檔,存档日期2013-12-02. Web还支持嵌入式玩家模式.

## 文档

这里有最完整的医生: [https://capgo.app/docs/plugins/video-player/ 互联网档案馆的存檔,存档日期2014-12-22](https://capgo.app/docs/plugins/video-player/)

## 兼容性

| 插件版本 | 电容兼容性 | 维护 |
| --- | --- | --- |
| 联合国 | 联合国 | ✅ |
| 页:1 | 页:1 | 应要求 |
| 页:1 | 页:1 | ❌ |
| 页:1 | 页:1 | ❌ |

> **说明:** 此插件的主要版本沿用了Capacitor的主要版本. 使用匹配您的 Capacitor 安装的版本( 如 Capacitor 8 的插件 v8) 。 只有最新的主要版本得到积极维护.

## 安装

您可以使用我们的 AI 辅助设置安装插件 。 使用以下命令将 Capgo 技能添加到您的 AI 工具 :

```bash
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
```

然后使用下列提示:

```text
Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-video-player` plugin in my project.
```

如果您更喜欢手动设置,请通过运行以下命令来安装插件,并遵循下面的平台特定指令:

```bash
bun add @capgo/capacitor-video-player
bunx cap sync
```

## iOS Chromecast 设置

iOS Chromecast使用Google Cast SDK默认媒体接收器. 何时 `chromecast` 启用时,插件会在全屏iOS播放器上添加一个 Cast 按钮,在选定的接收器上加载当前媒体,并保持插件播放/暂停/seek/批量呼叫指向正在运行的 Cast 会话.

对于在iOS上的 Cast 发现, 请在您的应用程序中添加本地网络密钥 `Info.plist`。 。 。 .

```xml
<key>NSBonjourServices</key>
<array>
  <string>_googlecast._tcp</string>
  <string>_CC1AD845._googlecast._tcp</string>
</array>
<key>NSLocalNetworkUsageDescription</key>
<string>$(PRODUCT_NAME) uses the local network to discover Cast-enabled devices on your WiFi network.</string>
```

```ts
await VideoPlayer.initPlayer({
  playerId: 'fullscreen',
  mode: 'fullscreen',
  url: 'https://example.com/video.mp4',
  title: 'Video title',
  smallTitle: 'Video subtitle',
  artwork: 'https://example.com/poster.jpg',
  chromecast: true,
});
```

## 支持的特性

| 特性 | iOS系统 | 机器人 | 网页 |
| --- | --- | --- | --- |
| 全屏本地视频播放器 | ✅ | ✅ | ❌ |
| 嵌入式网络视频播放器 | ❌ | ❌ | ✅ |
| 图片中的图片 | ✅ | ✅ | ❌ |
| 字幕 | ✅ | ✅ | ✅ |
| DRM 保护回放 | ✅ | ✅ | ❌ |
| 重播 Chromecast 发送者 | ❌ | ✅ | ❌ |

## Chromecast (Android) (英语)

Chromecast在Android上以全屏模式支持. 启用它与 `chromecast` 选项。 当一个 Cast 会话开始时,插件会在接收器上加载相同的媒体URL,保持当前回放位置,并通过 Cast会话播放,暂停,寻求,以及时间表控制.

```ts
await VideoPlayer.initPlayer({
  mode: 'fullscreen',
  playerId: 'main-player',
  url: 'https://example.com/video.m3u8',
  title: 'Video title',
  smallTitle: 'Optional subtitle',
  artwork: 'https://example.com/artwork.jpg',
  chromecast: true,
  showControls: true,
});
```

### Chromecast 选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `chromecast` | `boolean` | `true` | 显示Android Cast按钮并允许发送者回放. |
| `title` | `string` | `""` | 在发件人控件和接收器元数据中显示标题 . |
| `smallTitle` | `string` | `""` | 在发件人控件和元数据中显示字幕. |
| `artwork` | `string` | `""` | 用于 Cast 元数据及发送者 Cast 艺术品的图像 URL. |

### 所需资源和说明

-   媒体URL必须能够被Chromecast设备所达到,而不仅仅是Android应用.
-   铸作支持依赖于接收器的应用和装置媒体支持. MP4,HLS,DASH,和平滑结构流被插件映射为Cast相容的MIME类型.
-   Widevine DRM元数据被传送到Cast媒体项目. 受 DRM 保护的流可能仍然需要一个支持您的许可证服务器和 DRM 流量的接收器 .
-   Android本地玩家使用的请求头无法自动为Chromecast接收器提供. 使用公开的 URL, 签名的 URL, 由您的接收器支持的 cookie, 或安全媒体的自定义接收器 .

## 图片中的 Android 图片

Android上的图片需要您的应用活动来声明 PiP 支持 `android/app/src/main/AndroidManifest.xml`数字 :

```xml
<activity
  android:name=".MainActivity"
  android:supportsPictureInPicture="true"
  android:launchMode="singleTask"
  android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode|navigation|density"
  ...>
</activity>
```

`launchMode="singleTask"` 编辑 `configChanges` 旗子防止玩家在进入或离开PiP时的活动被重新创建.

## 图片和背景音频中的 iOS 图片

在 iOS 上, 本地玩家配置 `AVAudioSession` 用于 Pip 和背景播放 `pipEnabled` 或者说 `bkmodeEnabled` 真实( 都默认为真实) 。 您的应用程序还需要正确的列表和能力条目 :

1.  在 Xcode 中,添加 **背景模式** 能力与能力 **音频、 AirPlay 和图片**。 。 。 .
2.  单位 `ios/App/App/Info.plist`,包括音频背景模式 :

```xml
<key>UIBackgroundModes</key>
<array>
  <string>audio</string>
</array>
```

在物理 iPhone 上测试 PiP(模拟器不支持图片中的图片). 设置 `audioCategory: 'ambient'` 尊重无声开关, 但是在屏幕锁上保持沉默音频; 让它未设定或使用 `playback` 用于播放音响背景.

## API 密码

-   [`initPlayer(...)`](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-initplayer)
-   [`isPlaying(...)`](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-isplaying)
-   [`play(...)`](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-play)
-   [`pause(...)`](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-pause)
-   [`getDuration(...)`](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-getduration)
-   [`getCurrentTime(...)`](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-getcurrenttime)
-   [`setCurrentTime(...)`](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-setcurrenttime)
-   [`getVolume(...)`](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-getvolume)
-   [`setVolume(...)`](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-setvolume)
-   [`getMuted(...)`](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-getmuted)
-   [`setMuted(...)`](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-setmuted)
-   [`setRate(...)`](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-setrate)
-   [`getRate(...)`](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-getrate)
-   [`stopAllPlayers()`](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-stopallplayers)
-   [`showController()`](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-showcontroller)
-   [`isControllerIsFullyVisible()`](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-iscontrollerisfullyvisible)
-   [`exitPlayer()`](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-exitplayer)
-   [`hidePlayer()`](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-hideplayer)
-   [`showPlayer()`](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-showplayer)
-   [`getPluginVersion()`](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-getpluginversion)
-   [接口](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-interfaces)

### 内置 Player (...)

```typescript
initPlayer(options: capVideoPlayerOptions) => Promise<capVideoPlayerResult>
```

初始化视频播放器

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[capVideoPlayerOptions](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideoplayeroptions)` |

**回返情况:** `Promise<[capVideoPlayerResult](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideoplayerresult)>`

* * *

### 正在播放(...)

```typescript
isPlaying(options: capVideoPlayerIdOptions) => Promise<capVideoPlayerResult>
```

如果给定的播放器正在播放, 返回

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[capVideoPlayerIdOptions](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideoplayeridoptions)` |

**回返情况:** `Promise<[capVideoPlayerResult](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideoplayerresult)>`

* * *

### 播放(...)

```typescript
play(options: capVideoPlayerIdOptions) => Promise<capVideoPlayerResult>
```

播放给定播放器的当前视频Id

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[capVideoPlayerIdOptions](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideoplayeridoptions)` |

**回返情况:** `Promise<[capVideoPlayerResult](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideoplayerresult)>`

* * *

### 暂停(...)

```typescript
pause(options: capVideoPlayerIdOptions) => Promise<capVideoPlayerResult>
```

暂停给定播放器的当前视频Id

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[capVideoPlayerIdOptions](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideoplayeridoptions)` |

**回返情况:** `Promise<[capVideoPlayerResult](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideoplayerresult)>`

* * *

### 获取期限(...)

```typescript
getDuration(options: capVideoPlayerIdOptions) => Promise<capVideoPlayerResult>
```

从给定的播放器ID获取当前视频的持续时间

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[capVideoPlayerIdOptions](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideoplayeridoptions)` |

**回返情况:** `Promise<[capVideoPlayerResult](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideoplayerresult)>`

* * *

### 获取当前时间(...)

```typescript
getCurrentTime(options: capVideoPlayerIdOptions) => Promise<capVideoPlayerResult>
```

从给定的播放器ID获取当前视频的时间

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[capVideoPlayerIdOptions](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideoplayeridoptions)` |

**回返情况:** `Promise<[capVideoPlayerResult](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideoplayerresult)>`

* * *

### 设置当前时间(...)

```typescript
setCurrentTime(options: capVideoTimeOptions) => Promise<capVideoPlayerResult>
```

设定当前从给定的 playerId 中查找当前视频的时间

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[capVideoTimeOptions](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideotimeoptions)` |

**回返情况:** `Promise<[capVideoPlayerResult](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideoplayerresult)>`

* * *

### 获取Volume (...)

```typescript
getVolume(options: capVideoPlayerIdOptions) => Promise<capVideoPlayerResult>
```

从给定的播放器ID获取当前视频的音量

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[capVideoPlayerIdOptions](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideoplayeridoptions)` |

**回返情况:** `Promise<[capVideoPlayerResult](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideoplayerresult)>`

* * *

### 设置卷 (...)

```typescript
setVolume(options: capVideoVolumeOptions) => Promise<capVideoPlayerResult>
```

将当前视频的音量设定为给定的播放器ID

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[capVideoVolumeOptions](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideovolumeoptions)` |

**回返情况:** `Promise<[capVideoPlayerResult](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideoplayerresult)>`

* * *

### 获取Muted (...)

```typescript
getMuted(options: capVideoPlayerIdOptions) => Promise<capVideoPlayerResult>
```

从给定的播放器ID中获取当前视频的哑音

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[capVideoPlayerIdOptions](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideoplayeridoptions)` |

**回返情况:** `Promise<[capVideoPlayerResult](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideoplayerresult)>`

* * *

### 设置已挂载(...)

```typescript
setMuted(options: capVideoMutedOptions) => Promise<capVideoPlayerResult>
```

将当前视频的变音设定为给定播放器ID

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[capVideoMutedOptions](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideomutedoptions)` |

**回返情况:** `Promise<[capVideoPlayerResult](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideoplayerresult)>`

* * *

### 设置Rate(...)

```typescript
setRate(options: capVideoRateOptions) => Promise<capVideoPlayerResult>
```

设定当前视频从给定播放器ID 的速率

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[capVideoRateOptions](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideorateoptions)` |

**回返情况:** `Promise<[capVideoPlayerResult](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideoplayerresult)>`

* * *

### 获取Rate(...)

```typescript
getRate(options: capVideoPlayerIdOptions) => Promise<capVideoPlayerResult>
```

从给定的播放器ID获取当前视频的速率

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[capVideoPlayerIdOptions](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideoplayeridoptions)` |

**回返情况:** `Promise<[capVideoPlayerResult](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideoplayerresult)>`

* * *

### 停止所有 Players ()

```typescript
stopAllPlayers() => Promise<capVideoPlayerResult>
```

停止所有玩家的游戏

**回返情况:** `Promise<[capVideoPlayerResult](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideoplayerresult)>`

* * *

### 显示控制器 ()

```typescript
showController() => Promise<capVideoPlayerResult>
```

显示控制器

**回返情况:** `Promise<[capVideoPlayerResult](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideoplayerresult)>`

* * *

### 是 CaptainIs Fully Visible () () 翻译

```typescript
isControllerIsFullyVisible() => Promise<capVideoPlayerResult>
```

控制器易见

**回返情况:** `Promise<[capVideoPlayerResult](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideoplayerresult)>`

* * *

### 退出 Player ()

```typescript
exitPlayer() => Promise<capVideoPlayerResult>
```

退出玩家

**回返情况:** `Promise<[capVideoPlayerResult](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideoplayerresult)>`

* * *

### 隐藏layer ()

```typescript
hidePlayer() => Promise<capVideoPlayerResult>
```

隐藏当前呈现的播放器 UI 不停止播放( 本地全屏) .

打电话 `showPlayer()` 以再次显示.

**回返情况:** `Promise<[capVideoPlayerResult](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideoplayerresult)>`

* * *

### 显示layer ()

```typescript
showPlayer() => Promise<capVideoPlayerResult>
```

再次显示先前隐藏的玩家 UI( 本地全屏) .

**回返情况:** `Promise<[capVideoPlayerResult](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-capvideoplayerresult)>`

* * *

### 获取 PluginVersion ()

```typescript
getPluginVersion() => Promise<{ version: string; }>
```

获取本地 Capacitor 插件版本 . 在网络上, 执行返回 `"web"`。 。 。 .

**回返情况:** `Promise<{ version: string; }>`

* * *

### 接口

#### 图像显示器

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`result`** | `boolean` | 当成功时结果被设定为真实 |
| **`method`** | `string` | 方法名称 |
| **`value`** | `any` | 返回的数值 |
| **`message`** | `string` | 信件字符串 |

#### 图像显示器选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`mode`** | `string` | 玩家模式-"全屏"-"被嵌入"(只有Web) |
| **`url`** | `string` | 要播放的视频url |
| **`chromecastUrl`** | `string` | 用于Chromecast(iOS,Android)的可选覆盖URL. 这使得您可以投放一个可替代的递解/功能(例如MPEG-DASH + Widevine),同时保持了可调取回放的URL不变(例如HLS + FairPlay在iOS上). |
| **`subtitle`** | `string` | 与视频相关的字幕url Prefer `subtitles` 当提供多个音轨时。 用于向后兼容 . |
| **`language`** | `string` | 字幕语言见 [https://github.com/libyal/libfwnt/wiki/Language-Code-identifers (中文(简体) )](https://github.com/libyal/libfwnt/wiki/Language-Code-identifiers) 偏爱 `subtitles` 当提供多个音轨时。 用于向后兼容 . |
| **`subtitles`** | `VideoSubtitle[]` | 多个字幕音轨(iOS,Android). 提供时,优先于 `subtitle` 编号 : `language`。 。 。 . |
| **`chapters`** | `VideoChapter[]` | 长式内容的分章标记(iOS,Android). 在本地全屏播放器中显示为章节列表; 选择一章 `startTime`。 。 。 . |
| **`subtitleOptions`** | `[SubTitleOptions](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-subtitleoptions)` | 子标题选项 |
| **`playerId`** | `string` | 玩家的 DIV 元素父代码 |
| **`rate`** | `number` | 初始播放率 |
| **`exitOnEnd`** | `boolean` | 在视频端( iOS, Android) 默认退出: true |
| **`loopOnEnd`** | `boolean` | 退出时循环视频 End 假(iOS, Android)默认:假 |
| **`pipEnabled`** | `boolean` | 图片启用中的图片( iOS, Android) 默认: 真 |
| **`bkmodeEnabled`** | `boolean` | 背景模式 启用( iOS, Android) 默认: 真 |
| **`audioCategory`** | `'ambient' | 'playback' | 'moviePlayback'` | iOS音频会话分类行为(iOS). –"环境":尊重iPhone无声开关-"回放":忽略了iPhone无声开关-"moviePlayback":为视频和长形AirPlay优化了回放. 在省略时, 插件从其他选项中解决该类 : `"playback"` 若为 `pipEnabled` 或者说 `bkmodeEnabled` 真实( 默认为真实) , 否则 `"ambient"`。 。 。 . |
| **`showControls`** | `boolean` | 显示控件启用( iOS, Android) 默认: 真 |
| **`displayMode`** | `string` | 显示模式 \["全","相","地景"\] (iOS, Android) 默认:"全" |
| **`componentTag`** | `string` | 组件标记或 DOM 元素标记( React app) |
| **`width`** | `number` | 玩家 Width( 模式"只嵌入") |
| **`height`** | `number` | 玩家身高( 仅“ 嵌入” 模式) |
| **`headers`** | `{ [key: string]: string; }` | 曼努埃尔·加西亚·马林(英语:Manuel García Marín (iOS, Android))的请求信头[https://github.com/PhantomPainX 页面存档备份,存于互联网档案馆](https://github.com/PhantomPainX)(中文(简体) ) |
| **`title`** | `string` | 玩家和Chromecast元数据(iOS, Android)中显示的标题由曼努埃尔·加西亚·马林(英语:Manuel García Marín (film))所出[https://github.com/PhantomPainX 页面存档备份,存于互联网档案馆](https://github.com/PhantomPainX)(中文(简体) ) |
| **`smallTitle`** | `string` | 在玩家和Chromecast元数据(iOS,Android)中标题下显示的子标题由Manuel García Marín([https://github.com/PhantomPainX 页面存档备份,存于互联网档案馆](https://github.com/PhantomPainX)(中文(简体) ) |
| **`accentColor`** | `string` | ExoPlayer 进步条和斯宾纳颜色(Android)由曼努埃尔·加西亚·马林(英语:Manuel García Marín (film))所出[https://github.com/PhantomPainX 页面存档备份,存于互联网档案馆](https://github.com/PhantomPainX)) 必须是有效的十六进制颜色代码默认值 : #FFFFFF |
| **`chromecast`** | `boolean` | Chromecast 启用/失效(iOS,Android)iOS需要Google Cast SDK设置和本地网络 Info.plist密钥. 曼努埃尔·加西亚·马林(签名)[https://github.com/PhantomPainX 页面存档备份,存于互联网档案馆](https://github.com/PhantomPainX)默认:真实 |
| **`artwork`** | `string` | 由曼努埃尔·加西亚·马林(英语:Manuel García Marín (film))在Chromecast播放器(iOS, Android)上映的艺术工作url(英语:[https://github.com/PhantomPainX 页面存档备份,存于互联网档案馆](https://github.com/PhantomPainX)默认: "" |
| **`drm`** | `[DrmOptions](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-drmoptions)` | 被保护内容的 DRM 配置( iOS: FairPlay, Android: Widevine) 铸造时 威德文 `certificateUrl` (许可证 URL) 也转发给 Chromecast 接收器作为 `media.customData.laurl`。 。 。 . |

#### 视频字幕

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`subtitle`** | `string` | 字幕文件的url(vtt, srt, |
| **`language`** | `string` | 字幕的语言见 [https://github.com/libyal/libfwnt/wiki/Language-Code-identifers (中文(简体) )](https://github.com/libyal/libfwnt/wiki/Language-Code-identifiers) |

#### 视频章节

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`title`** | `string` | 章节列表中显示的章节标题 |
| **`startTime`** | `number` | 以秒计的起始时间 |
| **`endTime`** | `number` | 结束时间为秒( 可选) 。 存储用于未来时间标; 章节跳转使用 `startTime` 只有在这个释放. |

#### 字幕选项

屏幕字幕的可选风格.

在iOS上,颜色和字体大小通过 `AVPlayerItem` `textStyleRules`,只有WebVTT的苹果文档。 IMSC1和其他数据 无法通过此 API 来样式化 . 内置的WebVTT提示样式可以优先于等同类型 `subtitleOptions` 值; 插件将文本样式规则设置为平台 倒置, 无法保证默认作者的提示样式 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`foregroundColor`** | `string` | RGBA中的前景色. 在Android上,当插件应用字幕样式时,省略的值会回到 `rgba(255,255,255,1)`时 `subtitleOptions` 不存在 媒体的嵌入式提示颜色可以覆盖后退 在iOS上,省略的颜色不是由插件设置;平台使用取景器的字幕外观设置,而不是固定的插件默认. |
| **`backgroundColor`** | `string` | RGBA中的背景颜色. 在Android上,当插件在全屏中应用字幕样式时,省略的值会回到 `rgba(0,0,0,1)`在图片中,当插件应用其标题样式(例如侧车字幕或非空)时,省略的值会回到透明状态 `subtitleOptions` 包括颜色覆盖。 一个空的 `subtitleOptions` 对象本身并不选择倒置。 在只有字体大小的选项下,嵌入的提示样式会保持被启用,因此作者的提示背景可以在PiP中保持可见. 何时 `subtitleOptions` 不存在,媒体的嵌入式提示颜色可以覆盖倒计时。 在iOS上,省略的颜色不是由插件设置;平台使用取景器的字幕外观设置,而不是固定的插件默认. |
| **`fontSize`** | `number` | CSS 像素中的字体大小 。 在Android上,提供的值在应用前被四舍五入到最接近的整数. 在没有侧车字幕URI的嵌入道被省略后,Android使用 `SubtitleView.setUserDefaultTextSize()` (用户的系统标题大小),而非固定的16 px大小. 当此属性被省略时, Sidecar 字幕仍然使用固定的默认大小 。 在iOS上,数值映射到AVFoundation相对大小,其中16等同系统默认(100%). |

#### 选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`fairplay`** | `[FairPlayDrmOptions](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-fairplaydrmoptions)` | FairPlay DRM 配置( iOS) |
| **`playready`** | `[PlayreadyDrmOptions](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-playreadydrmoptions)` | 播放 Ready DRM 配置 |
| **`widevine`** | `[WidevineDrmOptions](https://npmcn.com/package/%40capgo/capacitor-video-player/#readme-widevinedrmoptions)` | Widevine DRM 配置 (Android) |

#### FairPlayDrm 选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`certificateUrl`** | `string` | 获取 FairPlay 证书的 URL |
| **`contentKeySpcUrl`** | `string` | 发送 SPC 并获得 CKC 许可证的 URL (FairPlay 许可证服务器 URL) |
| **`assetId`** | `string` | 生成 SPC 时使用的可选 FairPlay 资产标识符 。 默认 `skd://` 关键请求中的内容标识符. |

#### 播放已准备

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`certificateUrl`** | `string` | 获取 PlayReady 许可证的 URL |

#### 宽度选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`certificateUrl`** | `string` | 获取 Widevine 许可证的 URL |

#### capVideoPlayer 选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`playerId`** | `string` | 玩家的 DIV 元素父代码 |

#### 视频时间选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`playerId`** | `string` | 玩家的 DIV 元素父代码 |
| **`seektime`** | `number` | 视频时间值 |

#### 图像卷选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`playerId`** | `string` | 玩家的 DIV 元素父代码 |
| **`volume`** | `number` | \[0-1\]之间的量值 |

#### 图像混合选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`playerId`** | `string` | 玩家的 DIV 元素父代码 |
| **`muted`** | `boolean` | 输入数值为真或假 |

#### 超视距选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`playerId`** | `string` | 玩家的 DIV 元素父代码 |
| **`rate`** | `number` | 利率值 |

## 常见问题

### @capgo/capacitor-video-player 是什么？

用本地播放器播放视频的电容插件

### 如何安装 @capgo/capacitor-video-player？

在项目目录运行 npm install @capgo/capacitor-video-player，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：hls\.js（^1\.4\.0）、@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @capgo/capacitor-video-player 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @capgo/capacitor-video-player 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @capgo/capacitor-video-player 可以商用吗？

@capgo/capacitor-video-player 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。

### @capgo/capacitor-video-player 的下载量有多少？

根据 npm 官方下载统计，@capgo/capacitor-video-player 在 2026/10/09 – 2026/11/07 这 30 天内被下载 47,235 次，日均约 1,575 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @capgo/capacitor-video-player 还在维护吗？

最新版本 8\.3\.0 发布于 2026/11/04（4 天前）；至今共发布 83 个版本，其中过去 12 个月发布了 66 个；首次发布于 2025/10/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。