# @capawesome/capacitor-youtube-player 中文文档

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

版本：0\.1\.4
npm 元数据更新时间：2026-11-04T08:50:00.296Z
中文译文更新时间：2026-11-09T06:33:44.541Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40capawesome/capacitor-youtube-player
原文对照：https://npmcn.com/package/%40capawesome/capacitor-youtube-player/?lang=original
项目主页：https://capawesome.io/docs/sdks/capacitor/youtube-player/
源码仓库：https://github.com/capawesome-team/capacitor-plugins

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

- 包体积（解压后）：397 kB，90 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2026-07-12T06:54:21.090Z
- 最新版本发布：2026-11-04T08:49:59.916Z
- 近 30 天下载量：4716（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

在Android,iOS,和Web上嵌入并控制YouTube播放器的Capacitor插件.

## 安装

```sh
npm install @capawesome/capacitor-youtube-player
```

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

## README

# 控制器 YouTube 播放器插件

嵌入和控制的非官方电容插件 [YouTube (英语)](https://www.youtube.com/) android、iOS和Web上的玩家。\[^1\]

[![Thousands of teams ship faster with Capawesome Cloud Native Builds and Live Updates](https://capawesome.io/assets/banners/cloud-teams-ship-faster-with-capacitor.png)](https://capawesome.io/)

## 特征

Capacitor YouTube Player插件将YouTube视频嵌入为内线,帧定位于您Capacitor应用程序的玩家. 以下是一些关键特征:

-   🖥️ **跨平台**:支持Android,iOS,和Web.
-   🎞️ **内置回放**:在所有平台上嵌入玩家,包括iOS.
-   🧩 **多种精神**:通过ID同时创建并控制多个玩家.
-   📐 **框架定位**: 使用 CSS 像素帧定位并调整播放器大小, 使其与您的布局同步 .
-   🎛️ **播放控件**:装入,提示,播放,暂停,寻找,哑音,音量,和回放速率.
-   📡 **类型事件**: 听好了,状态,时间,速率,出错,和有打出收听器的全屏事件.
-   📜 **术语**:建于官方YouTube IFrame Player API上,并配有符合TOS的管道(参见 [YouTube 服务条件](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-youtube-terms-of-service)) (中文(简体) ).
-   🤝 **兼容性**: 与 [媒体会议](https://capawesome.io/docs/sdks/capacitor/media-session/) 财务报告和审定财务报表 [屏幕方向](https://capawesome.io/docs/sdks/capacitor/screen-orientation/) 插件 .
-   📦 **可可花和SPM**:支持CocoaPods和Swift软件包管理器用于iOS.
-   🔁 **最新数据**:总是支持最新的Capacitor版本.

缺少一个功能? 刚刚 [打开一个问题](https://github.com/capawesome-team/capacitor-plugins/issues) 我们看看!

## 使用大小写

YouTube Player插件一般用于任何您想要将YouTube视频嵌入您的应用中的地方,例如:

-   **媒体应用程序**:嵌入了预告片,音乐视频,或内容中的插曲.
-   **登入帮助( H)**:在您的应用程序中直接显示教程和视频.
-   **新闻和博客**:Render YouTube嵌入有本土回放表演的文章.
-   **学历**:在一页上搭建多段视频课的课程屏幕.

## 兼容性

| 插件版本 | 电容版本 | 状态 |
| --- | :-: | :-: |
| 0.x.x (中文(简体) ) | \>=8.x.x | 积极支持 |

## 安装

你可以用我们的 **AI 辅助设置** 以安装插件. 添加数据 [超级技能](https://github.com/capawesome-team/skills) 至您的 AI 工具,使用以下命令:

```bash
npx skills add capawesome-team/skills --skill capacitor-plugins
```

然后使用下列提示:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-youtube-player` plugin in my project.
```

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

```bash
npm install @capawesome/capacitor-youtube-player
npx cap sync
```

### 机器人

在Android上,插件使用 [机器人-youtube-播放器](https://github.com/PierfrancescoSoffritti/android-youtube-player) 库,是一款围绕官方YouTube IFrame Player API的开源包装.

#### 变量

此插件将使用以下工程变量( 在您的应用程序中定义) `variables.gradle` 文件名 :

-   `$androidYoutubePlayerVersion` 版本 `com.pierfrancescosoffritti.androidyoutubeplayer:core` (默认 : `13.1.0`(中文(简体) )

#### 权限

插件自动添加 `android.permission.ACCESS_NETWORK_STATE` 允许您的应用程序的列表。 它用于在网络连接丢失并恢复时恢复玩家. 不需要你采取行动.

### iOS系统

在 iOS 上,插件使玩家在 `WKWebView` 使用官员 [YouTube IFrame 播放器 API](https://developers.google.com/youtube/iframe_api_reference)。不需要额外的配置.

### 网页

网络执行加载 [YouTube IFrame 播放器 API](https://developers.google.com/youtube/iframe_api_reference) 从YouTube的运行时间。 这需要主动的网络连接. 如果您的应用程序执行 [内容安全政策](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP),确保允许YouTube域(例如. `https://www.youtube.com` 页:1 `script-src` 财务报告和审定财务报表 `frame-src`,以及 `https://www.youtube-nocookie.com` 页:1 `frame-src` 如果你设置 `host` 选项).

## 配置

此插件不需要配置 .

## 使用量

以下例子显示如何使用插件 .

### 创建玩家

在您的布局中测量占位符元素, 并在其位置创建玩家 :

```typescript
import { YoutubePlayer } from '@capawesome/capacitor-youtube-player';

const createPlayer = async () => {
  const rect = document
    .querySelector('#player-placeholder')
    .getBoundingClientRect();
  await YoutubePlayer.createPlayer({
    id: 'my-player',
    frame: {
      x: rect.x,
      y: rect.y,
      width: rect.width,
      height: rect.height,
    },
    videoId: 'dQw4w9WgXcQ',
    options: {
      mute: true,
    },
  });
};
```

### 控制重播

```typescript
import { YoutubePlayer } from '@capawesome/capacitor-youtube-player';

const controlPlayback = async () => {
  await YoutubePlayer.play({ id: 'my-player' });
  await YoutubePlayer.seekTo({ id: 'my-player', seconds: 42 });
  await YoutubePlayer.setVolume({ id: 'my-player', volume: 50 });
  await YoutubePlayer.setPlaybackRate({ id: 'my-player', rate: 1.5 });
  await YoutubePlayer.pause({ id: 'my-player' });
};
```

### 倾听事件

```typescript
import { YoutubePlayer } from '@capawesome/capacitor-youtube-player';

const addListeners = async () => {
  await YoutubePlayer.addListener('playerReady', event => {
    console.log('Player ready:', event.id);
  });
  await YoutubePlayer.addListener('playerStateChange', event => {
    console.log('Player state:', event.id, event.state);
  });
  await YoutubePlayer.addListener('playerError', event => {
    console.error('Player error:', event.id, event.code);
  });
};
```

### 删除玩家

```typescript
import { YoutubePlayer } from '@capawesome/capacitor-youtube-player';

const removePlayer = async () => {
  await YoutubePlayer.removePlayer({ id: 'my-player' });
};
```

## API 密码

-   [`createPlayer(...)`](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-createplayer)
-   [`cueVideo(...)`](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-cuevideo)
-   [`getCurrentTime(...)`](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-getcurrenttime)
-   [`getDuration(...)`](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-getduration)
-   [`loadVideo(...)`](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-loadvideo)
-   [`mute(...)`](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-mute)
-   [`pause(...)`](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-pause)
-   [`play(...)`](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-play)
-   [`removePlayer(...)`](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-removeplayer)
-   [`seekTo(...)`](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-seekto)
-   [`setPlaybackRate(...)`](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-setplaybackrate)
-   [`setPlayerFrame(...)`](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-setplayerframe)
-   [`setVolume(...)`](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-setvolume)
-   [`unmute(...)`](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-unmute)
-   [`addListener('currentTimeChange', ...)`](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-addlistenercurrenttimechange-)
-   [`addListener('fullscreenChange', ...)`](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-addlistenerfullscreenchange-)
-   [`addListener('playbackRateChange', ...)`](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-addlistenerplaybackratechange-)
-   [`addListener('playerError', ...)`](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-addlistenerplayererror-)
-   [`addListener('playerReady', ...)`](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-addlistenerplayerready-)
-   [`addListener('playerStateChange', ...)`](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-addlistenerplayerstatechange-)
-   [`removeAllListeners()`](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-removealllisteners)
-   [接口](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-type-aliases)

### 创建 Player (...)

```typescript
createPlayer(options: CreatePlayerOptions) => Promise<CreatePlayerResult>
```

创建新的YouTube播放器.

在Android和iOS上,玩家作为本地视图渲染,即: 位于给定框架的网页视图上方。 这个框架不是 以网页内容滚动. 使用 `setPlayerFrame(...)` 保留 与您的布局同步的帧(请参见 README 的配方).

玩家必须至少为 200x200 CSS 像素, 按照要求 [YouTube 服务条件](https://developers.google.com/youtube/terms/required-minimum-functionality#embedded-player-size)。 。 。 .

| 参数 | 类型 |
| --- | :-: |
| **`options`** | `[CreatePlayerOptions](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-createplayeroptions)` |

**回返情况:** `Promise<[CreatePlayerResult](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-createplayerresult)>`

**自:** 0.1.0 (中文(简体) )

* * *

### cueVideo (...) (中文(简体) )

```typescript
cueVideo(options: CueVideoOptions) => Promise<void>
```

在播放器中装入视频而不开始播放.

| 参数 | 类型 |
| --- | :-: |
| **`options`** | `[CueVideoOptions](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-cuevideooptions)` |

**自:** 0.1.0 (中文(简体) )

* * *

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

```typescript
getCurrentTime(options: GetCurrentTimeOptions) => Promise<GetCurrentTimeResult>
```

获取玩家当前播放时间 .

在Android上,该值从最近推出值中解答: 播放器(在播放时每秒更新多次).

| 参数 | 类型 |
| --- | :-: |
| **`options`** | `[GetCurrentTimeOptions](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-getcurrenttimeoptions)` |

**回返情况:** `Promise<[GetCurrentTimeResult](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-getcurrenttimeresult)>`

**自:** 0.1.0 (中文(简体) )

* * *

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

```typescript
getDuration(options: GetDurationOptions) => Promise<GetDurationResult>
```

获取当前装入的视频的持续时间 .

在Android上,该值从最近推出值中解答: 球员.

| 参数 | 类型 |
| --- | :-: |
| **`options`** | `[GetDurationOptions](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-getdurationoptions)` |

**回返情况:** `Promise<[GetDurationResult](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-getdurationresult)>`

**自:** 0.1.0 (中文(简体) )

* * *

### 加载视频(...)

```typescript
loadVideo(options: LoadVideoOptions) => Promise<void>
```

将视频装入玩家开始回放.

| 参数 | 类型 |
| --- | :-: |
| **`options`** | `[LoadVideoOptions](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-loadvideooptions)` |

**自:** 0.1.0 (中文(简体) )

* * *

### 哑巴(...)

```typescript
mute(options: MuteOptions) => Promise<void>
```

关闭玩家.

| 参数 | 类型 |
| --- | :-: |
| **`options`** | `[MuteOptions](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-muteoptions)` |

**自:** 0.1.0 (中文(简体) )

* * *

### 暂停(...)

```typescript
pause(options: PauseOptions) => Promise<void>
```

暂停播放.

| 参数 | 类型 |
| --- | :-: |
| **`options`** | `[PauseOptions](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-pauseoptions)` |

**自:** 0.1.0 (中文(简体) )

* * *

### 播放(...)

```typescript
play(options: PlayOptions) => Promise<void>
```

开始或恢复播放 .

| 参数 | 类型 |
| --- | :-: |
| **`options`** | `[PlayOptions](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-playoptions)` |

**自:** 0.1.0 (中文(简体) )

* * *

### 删除 Player (...)

```typescript
removePlayer(options: RemovePlayerOptions) => Promise<void>
```

删除玩家并释放其全部资源.

| 参数 | 类型 |
| --- | :-: |
| **`options`** | `[RemovePlayerOptions](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-removeplayeroptions)` |

**自:** 0.1.0 (中文(简体) )

* * *

### 请求(...)

```typescript
seekTo(options: SeekToOptions) => Promise<void>
```

寻求给定的时间.

| 参数 | 类型 |
| --- | :-: |
| **`options`** | `[SeekToOptions](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-seektooptions)` |

**自:** 0.1.0 (中文(简体) )

* * *

### 设置PlaybackRate(...)

```typescript
setPlaybackRate(options: SetPlaybackRateOptions) => Promise<void>
```

设定玩家的回放率 .

| 参数 | 类型 |
| --- | :-: |
| **`options`** | `[SetPlaybackRateOptions](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-setplaybackrateoptions)` |

**自:** 0.1.0 (中文(简体) )

* * *

### 设置 PlayerFrame (...)

```typescript
setPlayerFrame(options: SetPlayerFrameOptions) => Promise<void>
```

更新玩家的框架 .

当布局发生变化时调用此方法( 例如在滚动、 调整大小或 方向变化),使玩家与您的布局保持同步.

| 参数 | 类型 |
| --- | :-: |
| **`options`** | `[SetPlayerFrameOptions](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-setplayerframeoptions)` |

**自:** 0.1.0 (中文(简体) )

* * *

### 设置卷 (...)

```typescript
setVolume(options: SetVolumeOptions) => Promise<void>
```

设定玩家的音量 .

在iOS上,操作系统不允许更改音量 在方案上,这种方法没有效果。 使用 `mute()` 财务报告和审定财务报表 `unmute()` 换句话说.

| 参数 | 类型 |
| --- | :-: |
| **`options`** | `[SetVolumeOptions](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-setvolumeoptions)` |

**自:** 0.1.0 (中文(简体) )

* * *

### 解密(...)

```typescript
unmute(options: UnmuteOptions) => Promise<void>
```

释出玩家.

| 参数 | 类型 |
| --- | :-: |
| **`options`** | `[UnmuteOptions](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-unmuteoptions)` |

**自:** 0.1.0 (中文(简体) )

* * *

### 添加倾听器( “ 当前时间变化 ” ,...)

```typescript
addListener(eventName: 'currentTimeChange', listenerFunc: (event: CurrentTimeChangeEvent) => void) => Promise<PluginListenerHandle>
```

当玩家当前播放时间发生变化时调用.

该事件在回放时每秒发射多次 。 这个 准确的频率取决于平台.

| 参数 | 类型 |
| --- | :-: |
| **`eventName`** | `'currentTimeChange'` |
| **`listenerFunc`** | `(event: [CurrentTimeChangeEvent](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-currenttimechangeevent)) => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-pluginlistenerhandle)>`

**自:** 0.1.0 (中文(简体) )

* * *

### 添加倾听器( “ 全屏变化 ” ,...)

```typescript
addListener(eventName: 'fullscreenChange', listenerFunc: (event: FullscreenChangeEvent) => void) => Promise<PluginListenerHandle>
```

当玩家进出全屏时调用.

仅在Android和Web上提供.

| 参数 | 类型 |
| --- | :-: |
| **`eventName`** | `'fullscreenChange'` |
| **`listenerFunc`** | `(event: [FullscreenChangeEvent](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-fullscreenchangeevent)) => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-pluginlistenerhandle)>`

**自:** 0.1.0 (中文(简体) )

* * *

### 添加 listener ('playbackRateChange', ...) 键盘重置

```typescript
addListener(eventName: 'playbackRateChange', listenerFunc: (event: PlaybackRateChangeEvent) => void) => Promise<PluginListenerHandle>
```

当玩家的回放率改变时调用.

在 iOS 上,此事件仅为 `setPlaybackRate(...)` 打电话.

| 参数 | 类型 |
| --- | :-: |
| **`eventName`** | `'playbackRateChange'` |
| **`listenerFunc`** | `(event: [PlaybackRateChangeEvent](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-playbackratechangeevent)) => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-pluginlistenerhandle)>`

**自:** 0.1.0 (中文(简体) )

* * *

### 添加倾听器( “ player Error ” ,...)

```typescript
addListener(eventName: 'playerError', listenerFunc: (event: PlayerErrorEvent) => void) => Promise<PluginListenerHandle>
```

当玩家出现错误时调用 .

| 参数 | 类型 |
| --- | :-: |
| **`eventName`** | `'playerError'` |
| **`listenerFunc`** | `(event: [PlayerErrorEvent](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-playererrorevent)) => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-pluginlistenerhandle)>`

**自:** 0.1.0 (中文(简体) )

* * *

### 添加收听器( “ 播放器 Ready ” )..

```typescript
addListener(eventName: 'playerReady', listenerFunc: (event: PlayerReadyEvent) => void) => Promise<PluginListenerHandle>
```

当玩家装入完毕并准备接收时调用 命令.

| 参数 | 类型 |
| --- | :-: |
| **`eventName`** | `'playerReady'` |
| **`listenerFunc`** | `(event: [PlayerReadyEvent](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-playerreadyevent)) => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-pluginlistenerhandle)>`

**自:** 0.1.0 (中文(简体) )

* * *

### 添加倾听器( “ player State Change ” ,...)

```typescript
addListener(eventName: 'playerStateChange', listenerFunc: (event: PlayerStateChangeEvent) => void) => Promise<PluginListenerHandle>
```

当玩家状态发生变化时调用.

| 参数 | 类型 |
| --- | :-: |
| **`eventName`** | `'playerStateChange'` |
| **`listenerFunc`** | `(event: [PlayerStateChangeEvent](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-playerstatechangeevent)) => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-pluginlistenerhandle)>`

**自:** 0.1.0 (中文(简体) )

* * *

### 删除所有收听器( )

```typescript
removeAllListeners() => Promise<void>
```

删除此插件的所有听众 .

**自:** 0.1.0 (中文(简体) )

* * *

### 接口

#### 创建 Player 报表

| Prop | 类型 | 说明 | 自兹 |
| --- | :-: | :-: | :-: |
| **`id`** | `string` | 创建玩家的独特标识符 . | 0.1.0 (中文(简体) ) |

#### 创建 Player 选项

| Prop | 类型 | 说明 | 自兹 |
| --- | :-: | :-: | :-: |
| **`frame`** | `[PlayerFrame](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-playerframe)` | 玩家在CSS像素中的框架,相对于取景口. 必须是至少 200x200 CSS 像素. | 0.1.0 (中文(简体) ) |
| **`id`** | `string` | 玩家独有的标识符 。 如果不提供,则生成随机标识符. | 0.1.0 (中文(简体) ) |
| **`options`** | `[PlayerOptions](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-playeroptions)` | 玩家的选择. | 0.1.0 (中文(简体) ) |
| **`videoId`** | `string` | 装入玩家的YouTube视频的ID. 如果不提供,玩家是在没有视频的情况下创建的. 装入一个 `loadVideo(...)` 或者说 `cueVideo(...)`。 。 。 . | 0.1.0 (中文(简体) ) |
| **`web`** | `[CreatePlayerWebOptions](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-createplayerweboptions)` | 仅在Web上提供的选项 . | 0.1.0 (中文(简体) ) |

#### 玩家屏幕

CSS像素中的玩家框架,相对取景口.

| Prop | 类型 | 说明 | 自兹 |
| --- | :-: | :-: | :-: |
| **`height`** | `number` | CSS像素中玩家的高度. 起码是 `200`。 。 。 . | 0.1.0 (中文(简体) ) |
| **`width`** | `number` | CSS像素中的玩家宽度. 起码是 `200`。 。 。 . | 0.1.0 (中文(简体) ) |
| **`x`** | `number` | CSS像素中玩家的x坐标. | 0.1.0 (中文(简体) ) |
| **`y`** | `number` | CSS像素中玩家的y坐标. | 0.1.0 (中文(简体) ) |

#### 玩家选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | :-: | :-: | :-: | --- |
| **`autoplay`** | `boolean` | 播放器创建时视频是否开始自动播放 . | `false` | 0.1.0 (中文(简体) ) |
| **`ccLoadPolicy`** | `boolean` | 默认是否显示已关闭的字幕, 即使用户已关闭字幕 . | `false` | 0.1.0 (中文(简体) ) |
| **`controls`** | `boolean` | 玩家控件是否显示 . | `true` | 0.1.0 (中文(简体) ) |
| **`end`** | `number` | 玩家应该停止播放视频的分秒时间. |  | 0.1.0 (中文(简体) ) |
| **`fullscreen`** | `boolean` | 是否显示全屏按钮 。 仅在Android和Web上提供. | `false` | 0.1.0 (中文(简体) ) |
| **`host`** | `string` | 玩家被装入的宿主 。 设定为 `https://www.youtube-nocookie.com` 来使用 YouTube的 [隐私增强模式](https://support.google.com/youtube/answer/171780)。必须是其中之一 `https://www.youtube.com` 或者说 `https://www.youtube-nocookie.com`。请注意,增强隐私模式并不妨碍YouTube在设备上存储饼干,因为IFrame Player API脚本总是从中加载 `https://www.youtube.com`。 。 。 . | `'https://www.youtube.com'` | 0.1.2 (中文(简体) ) |
| **`hl`** | `string` | 作为玩家界面的语言 [ISO 639-1 二字母语言代码](https://www.loc.gov/standards/iso639-2/php/code_list.php) 或完全指定的地点,例如 `de` 或者说 `pt-BR`. YouTube也使用这种语言来决定是否显示自动字幕. 如果不提供,玩家使用设备语言. 仅在iOS和Web上提供. |  | 0.1.4 (中文(简体) ) |
| **`ivLoadPolicy`** | `boolean` | 视频说明是否默认显示 . | `false` | 0.1.0 (中文(简体) ) |
| **`mute`** | `boolean` | 玩家创建时是否变哑 . | `false` | 0.1.0 (中文(简体) ) |
| **`rel`** | `boolean` | 播放结束时是否显示来自其他频道的相关视频 。 若为 `false`,相关视频仅限于视频频道. | `false` | 0.1.0 (中文(简体) ) |
| **`start`** | `number` | 视频从几秒钟开始播放的时间. |  | 0.1.0 (中文(简体) ) |

#### 创建 Player 网络选项

| Prop | 类型 | 说明 | 自兹 |
| --- | :-: | :-: | :-: |
| **`elementId`** | `string` | 将玩家挂入的 DOM 元素的标识 。 如果提供,玩家会填充此元素,而不是在给定的框架位置,以及 `setPlayerFrame(...)` 没有效果。 仅在Web上提供. | 0.1.0 (中文(简体) ) |

#### CueVideo 选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | :-: | :-: | :-: | --- |
| **`id`** | `string` | 玩家独有的标识符 . |  | 0.1.0 (中文(简体) ) |
| **`startSeconds`** | `number` | 视频播放后从秒开始播放的时间. | `0` | 0.1.0 (中文(简体) ) |
| **`videoId`** | `string` | YouTube视频的标识. |  | 0.1.0 (中文(简体) ) |

#### 获取当前时间结果

| Prop | 类型 | 说明 | 自兹 |
| --- | :-: | :-: | :-: |
| **`currentTime`** | `number` | 当前播放时间( 秒) . | 0.1.0 (中文(简体) ) |

#### 获取当前时间选项

| Prop | 类型 | 说明 | 自兹 |
| --- | :-: | :-: | :-: |
| **`id`** | `string` | 玩家独有的标识符 . | 0.1.0 (中文(简体) ) |

#### 获取期限

| Prop | 类型 | 说明 | 自兹 |
| --- | :-: | :-: | :-: |
| **`duration`** | `number` | 目前装入的视频持续时间以秒计. 回返 `0` 如果未装入视频. | 0.1.0 (中文(简体) ) |

#### 获取期限选项

| Prop | 类型 | 说明 | 自兹 |
| --- | :-: | :-: | :-: |
| **`id`** | `string` | 玩家独有的标识符 . | 0.1.0 (中文(简体) ) |

#### 加载视频选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | :-: | :-: | :-: | --- |
| **`id`** | `string` | 玩家独有的标识符 . |  | 0.1.0 (中文(简体) ) |
| **`startSeconds`** | `number` | 视频从几秒钟开始播放的时间. | `0` | 0.1.0 (中文(简体) ) |
| **`videoId`** | `string` | 要加载的YouTube视频的ID. |  | 0.1.0 (中文(简体) ) |

#### 静音选项

| Prop | 类型 | 说明 | 自兹 |
| --- | :-: | :-: | :-: |
| **`id`** | `string` | 玩家独有的标识符 . | 0.1.0 (中文(简体) ) |

#### 暂停选项

| Prop | 类型 | 说明 | 自兹 |
| --- | :-: | :-: | :-: |
| **`id`** | `string` | 玩家独有的标识符 . | 0.1.0 (中文(简体) ) |

#### 播放选项

| Prop | 类型 | 说明 | 自兹 |
| --- | :-: | :-: | :-: |
| **`id`** | `string` | 玩家独有的标识符 . | 0.1.0 (中文(简体) ) |

#### 删除层选项

| Prop | 类型 | 说明 | 自兹 |
| --- | :-: | :-: | :-: |
| **`id`** | `string` | 玩家独有的标识符 . | 0.1.0 (中文(简体) ) |

#### 查找选项

| Prop | 类型 | 说明 | 自兹 |
| --- | :-: | :-: | :-: |
| **`id`** | `string` | 玩家独有的标识符 . | 0.1.0 (中文(简体) ) |
| **`seconds`** | `number` | 几秒钟的时间来寻求. | 0.1.0 (中文(简体) ) |

#### 设置回放选项

| Prop | 类型 | 说明 | 自兹 |
| --- | :-: | :-: | :-: |
| **`id`** | `string` | 玩家独有的标识符 . | 0.1.0 (中文(简体) ) |
| **`rate`** | `number` | 复出率相. 一定是其中一个 `0.25`, (中文(简体) ), `0.5`, (中文(简体) ), `0.75`, (中文(简体) ), `1`, (中文(简体) ), `1.25`, (中文(简体) ), `1.5`, (中文(简体) ), `1.75` 或者说 `2`。 。 。 . | 0.1.0 (中文(简体) ) |

#### 设置 PlayerFrame 选项

| Prop | 类型 | 说明 | 自兹 |
| --- | :-: | :-: | :-: |
| **`frame`** | `[PlayerFrame](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-playerframe)` | CSS像素中播放器的新框架,相对于取景口. 必须是至少 200x200 CSS 像素. | 0.1.0 (中文(简体) ) |
| **`id`** | `string` | 玩家独有的标识符 . | 0.1.0 (中文(简体) ) |

#### 设置组合选项

| Prop | 类型 | 说明 | 自兹 |
| --- | :-: | :-: | :-: |
| **`id`** | `string` | 玩家独有的标识符 . | 0.1.0 (中文(简体) ) |
| **`volume`** | `number` | 作为值的大小 `0` 财务报告和审定财务报表 `100`。 。 。 . | 0.1.0 (中文(简体) ) |

#### 取消选项

| Prop | 类型 | 说明 | 自兹 |
| --- | :-: | :-: | :-: |
| **`id`** | `string` | 玩家独有的标识符 . | 0.1.0 (中文(简体) ) |

#### 插件听筒

| Prop | 类型 |
| --- | :-: |
| **`remove`** | `() => Promise<void>` |

#### 当前时间变化事件

| Prop | 类型 | 说明 | 自兹 |
| --- | :-: | :-: | :-: |
| **`currentTime`** | `number` | 当前播放时间( 秒) . | 0.1.0 (中文(简体) ) |
| **`id`** | `string` | 玩家独有的标识符 . | 0.1.0 (中文(简体) ) |

#### 全屏变化事件

| Prop | 类型 | 说明 | 自兹 |
| --- | :-: | :-: | :-: |
| **`fullscreen`** | `boolean` | 玩家是否处于全屏状态 . | 0.1.0 (中文(简体) ) |
| **`id`** | `string` | 玩家独有的标识符 . | 0.1.0 (中文(简体) ) |

#### 回放Rate 变换事件

| Prop | 类型 | 说明 | 自兹 |
| --- | :-: | :-: | :-: |
| **`id`** | `string` | 玩家独有的标识符 . | 0.1.0 (中文(简体) ) |
| **`rate`** | `number` | 新回放率. | 0.1.0 (中文(简体) ) |

#### 玩家错误事件

| Prop | 类型 | 说明 | 自兹 |
| --- | :-: | :-: | :-: |
| **`code`** | `[PlayerErrorCode](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-playererrorcode)` | 错误代码. | 0.1.0 (中文(简体) ) |
| **`id`** | `string` | 玩家独有的标识符 . | 0.1.0 (中文(简体) ) |

#### 玩家准备活动

| Prop | 类型 | 说明 | 自兹 |
| --- | :-: | :-: | :-: |
| **`id`** | `string` | 玩家独有的标识符 . | 0.1.0 (中文(简体) ) |

#### 玩家状态变化事件

| Prop | 类型 | 说明 | 自兹 |
| --- | :-: | :-: | :-: |
| **`id`** | `string` | 玩家独有的标识符 . | 0.1.0 (中文(简体) ) |
| **`state`** | `[PlayerState](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-playerstate)` | 玩家的新状态. | 0.1.0 (中文(简体) ) |

### 类型异名

#### 玩家错误代码

玩家错误的错误代码 .

`'html5-error' | 'invalid-parameter' | 'not-embeddable' | 'unknown' | 'video-not-found'`

#### 玩家状态

玩家状态.

`'buffering' | 'cued' | 'ended' | 'paused' | 'playing' | 'unstarted'`

## 框架同步

在Android和iOS上,玩家是一个被渲染的本地视图 **上文** 网页视图。 它不是DOM的一部分,因此不会用您的网页内容来滚动或调整大小. 相反,您将其定位为 CSS 像素框架,并通过调用使其与您的布局同步 `setPlayerFrame(...)` 当布局改变时:

```typescript
import { YoutubePlayer } from '@capawesome/capacitor-youtube-player';

const syncPlayerFrame = async () => {
  const rect = document
    .querySelector('#player-placeholder')
    .getBoundingClientRect();
  await YoutubePlayer.setPlayerFrame({
    id: 'my-player',
    frame: {
      x: rect.x,
      y: rect.y,
      width: rect.width,
      height: rect.height,
    },
  });
};

window.addEventListener('scroll', syncPlayerFrame);
window.addEventListener('resize', syncPlayerFrame);
```

如果使用带有自有滚动容器的框架(例如:. `ion-content`),将收听者附加在那个容器的卷轴事件上。 在网络上,玩家的位置是 `position: fixed`因此,同样的同步代码在所有平台上都起作用. 或者,在网络上,您可以使用 `web.elementId` 选项,在这种情况下不需要帧同步.

由于播放器在网页视图上方渲染,HTML内容永远不能与播放器相重叠. 在设计您的布局时记住这一点( 另见 [YouTube 服务条件](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-youtube-terms-of-service)) (中文(简体) ).

## YouTube 服务条件

通过使用此插件,您同意 [YouTube 服务条件](https://www.youtube.com/t/terms) 编辑 [YouTube API 服务条款](https://developers.google.com/youtube/terms/api-services-terms-of-service)。插件的设计是为了便于遵守 [所需的最低功能](https://developers.google.com/youtube/terms/required-minimum-functionality) 用于嵌入式玩家 :

-   **最小玩家大小**:嵌入式玩家必须至少有200×200像素. 插件执行此选项并拒绝带有较小框架的 `FRAME_INVALID` 错误代码 .
-   **没有背景播放**:视频不得在后台播放. 当应用程序被移动到背景时,插件会自动暂停所有玩家.
-   **没有覆盖**:玩家(包括其广告)不得被其他内容所掩盖. 由于本地玩家的视图总是在网页视图上方提供,所以HTML内容不能通过设计来相重叠.
-   **正确来源**: 插件设置 `origin` 玩家参数在所有平台上正确,这可以避免嵌入出错(例如错误152/153)而无需任何标题工作.
-   **没有玩家修改**:插件嵌入了官方YouTube播放器未被更改. 您的应用程序不能修改、 建立在或屏蔽玩家的任何部分或功能—— 包括它服务的任何广告.
-   **标记**: 如果您的应用程序与玩家一起显示 YouTube 标志或其他品牌资产, 请跟随 [YouTube 品牌准则](https://developers.google.com/youtube/terms/branding-guidelines)。 。 。 .

## 平台支持

并非所有的平台都有功能。 下表列出插件的API的每个平台差异:

| 特性 | 机器人 | iOS系统 | 网页 |
| --- | :-: | :-: | :-: |
| 回放控件 | ✅ | ✅ | ✅ |
| `fullscreen` 选项 | ✅ | ❌ | ✅ |
| `fullscreenChange` 事件 | ✅ | ❌ | ✅ |
| 原生哑巴 | ✅ | 🔄 | ✅ |

额外的特定平台行为 :

-   **iOS 变形模拟**: iOS 播放器库显示没有本地哑音 API,所以 `mute()` 通过设置音量来模拟 `0`。 。 。 . `unmute()` 通过 `setVolume(...)` (或 `100`) (中文(简体) ). 若为 `setVolume(...)` 在播放器被变音时调用, 音量只在下一个时应用 `unmute()` 电话.
-   **iOS 播放率事件**: 在iOS上,该 `playbackRateChange` 事件仅为 `setPlaybackRate(...)` 由于 iOS 播放器库没有显示回放率调用.
-   **iOS 错误映射**: 在iOS上,不允许在嵌入式玩家中播放的视频可以使用错误代码进行报告 `unknown` 改为 `not-embeddable`,由于iOS播放器库的映射出错误.
-   **Android 获取器**:关于Android, `getCurrentTime(...)` 财务报告和审定财务报表 `getDuration(...)` 由玩家所推动的最新数值解答,在回放时每秒更新多次.
-   **`currentTimeChange` 频率**:该事件在Android上每秒发射约10次,在iOS和Web上每秒发射约2次.

## 财务问题

### 此插件与其他类似插件有何不同?

此插件可以同时使多个本地玩家事件, 每个位置都定位到一个精确的框架, 您会保持与您的布局同步 。 它揭露了Android,iOS,和Web上一个完整而强烈打字的事件设定,并嵌入了官方YouTube播放器未被更改. 它是为了遵守YouTube Terms of Service要求的行为而建造的——最小的玩家大小,没有背景回放,没有被画过玩家,以及正确的出处——所以默认情况下保持遵守. 它得到坚定支持的积极维护和支持.

### 为什么我的画框被拒绝 `FRAME_INVALID`? 吗?

嵌入式YouTube播放器必须至少是200×200 CSS像素,这是YouTube服务条款的要求. 确保 `width` 财务报告和审定财务报表 `height` 您的相框至少是 `200`。 。 。 .

### 为什么玩家没有用我的内容来滚动?

在Android和iOS上,玩家是网络视图上方所渲染的本土视图,不属于DOM. 使用 `setPlayerFrame(...)` 使其与您的布局同步(参见 [框架同步](https://npmcn.com/package/%40capawesome/capacitor-youtube-player/#readme-frame-synchronization)) (中文(简体) ).

### 我可以在播放器上方显示 HTML 内容吗 ?

没有。 本地玩家视图总是在网页视图上方提供. 这也是YouTube的"服务条款"中的一项要求,该规定禁止混淆玩家.

### 在背景中还继续播放吗?

没有 YouTube的"服务条款"禁止背景回放,因此插件在应用程序被移动到背景时会自动暂停所有玩家.

### 我能用这个插件吗? 有Ionic、React、Vue或Angular?

是的,插件是框架不可知的。 它在任意网络框架的Capacitor app中工作,包括有Angular,React,或Vue的Ionic,以及平版JavaScript等项目.

## 相关插件

-   [媒体会议](https://capawesome.io/docs/sdks/capacitor/media-session/): 与媒体控制器,音量键和媒体按钮进行交互.
-   [屏幕方向](https://capawesome.io/docs/sdks/capacitor/screen-orientation/):锁定并解锁屏幕取向,例如允许地貌回放.

## 通讯

随时更新有关卡帕韦索姆、Capacitor和Ionic生态系统的最新消息和最新消息,因为我们 [《卡帕索克通讯》](https://cloud.capawesome.io/newsletter/)。 。 。 .

## 更改日志

见 [变动情况](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/youtube-player/CHANGELOG.md)。 。 。 .

## 许可证

见 [自由主义](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/youtube-player/LICENSE)。 。 。 .

\[^1\]: 这个项目不附属于Google LLC或YouTube LLC或其任何子公司或子公司,也不由它们认可,也不由它们赞助或批准. "YouTube"是谷歌有限责任公司的一个商标.

## 常见问题

### @capawesome/capacitor-youtube-player 是什么？

在Android,iOS,和Web上嵌入并控制YouTube播放器的Capacitor插件\.

### 如何安装 @capawesome/capacitor-youtube-player？

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

### @capawesome/capacitor-youtube-player 支持 TypeScript 吗？

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

### @capawesome/capacitor-youtube-player 支持 ESM 还是 CommonJS？

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

### @capawesome/capacitor-youtube-player 可以商用吗？

@capawesome/capacitor-youtube-player 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @capawesome/capacitor-youtube-player 的下载量有多少？

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

### @capawesome/capacitor-youtube-player 还在维护吗？

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