快速入门

复制一条配置 prompt，包含安装步骤和该插件的完整 Markdown 指南。

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-youtube-player`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/youtube-player/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

bunx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

然后使用以下 prompt：

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

如果你更倾向于手动设置，请运行以下命令安装插件，并参考下文针对各平台的具体说明：

bun add @capgo/capacitor-youtube-player
bunx cap sync

导入

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

快速入门

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

await YoutubePlayer.initialize({
  playerId: 'my-player',
  videoId: 'dQw4w9WgXcQ',
  playerSize: { width: 640, height: 360 },
  privacyEnhanced: true
});

常见坑点

监听器: 在页面卸载时移除句柄。
仅需初始化一次: 在应用启动阶段运行 setup。
单一事实来源: 信任 src/definitions.ts 在 GitHub 仓库中。

修复主 WebView 中 YouTube Referer 被拦截的问题

如果 YouTube 在插件内运行正常，但在应用通过 Capacitor 的主 WebView 加载 YouTube 页面、嵌入内容或 API 时失败，请在 patchRefererHeader 的 Capacitor 配置中启用。

启用后，插件会在同步/更新期间对 Capacitor 进行补丁处理，使拦截到的 YouTube 请求包含有效的 Referer header。

{
  "plugins": {
    "YoutubePlayer": {
      "patchRefererHeader": true,
      "refererHeader": "https://www.youtube.com"
    }
  }
}

仅 youtube.com, youtube-nocookie.com，以及 youtu.be 请求会受到影响。
已经定义了 Referer header 的请求将保留其原始值。
refererHeader 是可选的，默认值为 https://www.youtube.com.
Capacitor 已支持 8.x 适用于已安装的 iOS 和 Android 平台。

API 概览

`initialize`

初始化一个新的 YouTube player 实例。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

await YoutubePlayer.initialize({
  playerId: 'my-player',
  videoId: 'dQw4w9WgXcQ',
  playerSize: { width: 640, height: 360 },
  privacyEnhanced: true
});

`destroy`

销毁 player 实例并释放资源。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.destroy({ playerId: 'player-id-123' });
console.log(result);

`stopVideo`

停止视频播放并取消加载。请谨慎使用 —— 通常建议优先使用 pauseVideo()。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.stopVideo({ playerId: 'player-id-123' });
console.log(result);

`playVideo`

播放当前排队或已加载的视频。最终播放器状态将变为 PLAYING (1)。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.playVideo({ playerId: 'player-id-123' });
console.log(result);

`pauseVideo`

暂停当前正在播放的视频。最终播放器状态将变为 PAUSED (2)，除非当前已处于 ENDED (0) 状态。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.pauseVideo({ playerId: 'player-id-123' });
console.log(result);

`seekTo`

跳转到视频中的特定时间点。如果播放器处于暂停状态，则保持暂停；如果正在播放，则继续播放。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.seekTo({
  playerId: 'player-id-123',
  seconds: 10,
  allowSeekAhead: true,
});
console.log(result);

`loadVideoById`

通过 YouTube ID 加载并播放视频。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.loadVideoById({
  playerId: 'player-id-123',
  options: { videoId: 'video-id-123' },
});
console.log(result);

`cueVideoById`

通过 ID 预加载视频但不立即播放。加载缩略图并准备播放器，但在调用 playVideo() 之前不会请求视频数据。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.cueVideoById({
  playerId: 'player-id-123',
  options: { videoId: 'video-id-123' },
});
console.log(result);

`loadVideoByUrl`

通过完整 URL 加载并播放视频。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.loadVideoByUrl({
  playerId: 'player-id-123',
  options: { mediaContentUrl: 'https://example.com' },
});
console.log(result);

`cueVideoByUrl`

通过 URL 预加载视频但不立即播放。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.cueVideoByUrl({
  playerId: 'player-id-123',
  options: { mediaContentUrl: 'https://example.com' },
});
console.log(result);

`cuePlaylist`

预加载播放列表但不立即播放。加载播放列表并准备好第一个视频。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.cuePlaylist({
  playerId: 'player-id-123',
  playlistOptions: { listType: 'playlist' },
});
console.log(result);

`loadPlaylist`

加载并播放播放列表。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.loadPlaylist({
  playerId: 'player-id-123',
  playlistOptions: { listType: 'playlist' },
});
console.log(result);

`nextVideo`

播放播放列表中的下一个视频。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.nextVideo({ playerId: 'player-id-123' });
console.log(result);

`previousVideo`

播放播放列表中的上一个视频。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.previousVideo({ playerId: 'player-id-123' });
console.log(result);

`playVideoAt`

通过索引播放播放列表中的特定视频。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.playVideoAt({
  playerId: 'player-id-123',
  index: 1,
});
console.log(result);

`mute`

静音播放器音频。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.mute({ playerId: 'player-id-123' });
console.log(result);

`unMute`

取消静音播放器音频。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.unMute({ playerId: 'player-id-123' });
console.log(result);

`isMuted`

检查播放器当前是否处于静音状态。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.isMuted({ playerId: 'player-id-123' });
console.log(result);

`setVolume`

设置播放器音量。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.setVolume({
  playerId: 'player-id-123',
  volume: 0.5,
});
console.log(result);

`getVolume`

获取当前播放器的音量大小。即使播放器处于静音状态，也会返回音量值。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getVolume({ playerId: 'player-id-123' });
console.log(result);

`setSize`

设置播放器的像素尺寸。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.setSize({
  playerId: 'player-id-123',
  width: 1080,
  height: 1920,
});
console.log(result);

`getPlaybackRate`

获取当前的播放速率。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getPlaybackRate({ playerId: 'player-id-123' });
console.log(result);

`setPlaybackRate`

设置播放速度。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.setPlaybackRate({
  playerId: 'player-id-123',
  suggestedRate: 1,
});
console.log(result);

`getAvailablePlaybackRates`

获取当前视频可用的播放倍速列表。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getAvailablePlaybackRates({ playerId: 'player-id-123' });
console.log(result);

`setLoop`

启用或禁用播放列表循环。启用后，播放列表在最后一个视频结束后将从头开始。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.setLoop({
  playerId: 'player-id-123',
  loopPlaylists: true,
});
console.log(result);

`setShuffle`

启用或禁用播放列表随机播放。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.setShuffle({
  playerId: 'player-id-123',
  shufflePlaylist: true,
});
console.log(result);

`getVideoLoadedFraction`

获取视频已缓冲的比例。比已弃用的 getVideoBytesLoaded/getVideoBytesTotal 更可靠。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getVideoLoadedFraction({ playerId: 'player-id-123' });
console.log(result);

`getPlayerState`

获取播放器的当前状态。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getPlayerState({ playerId: 'player-id-123' });
console.log(result);

`getAllPlayersEventsState`

获取所有活跃播放器的事件状态。适用于追踪多个播放器实例。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getAllPlayersEventsState();
console.log(result);

`getCurrentTime`

获取当前播放进度（秒）。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getCurrentTime({ playerId: 'player-id-123' });
console.log(result);

`toggleFullScreen`

开启或关闭全屏模式。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.toggleFullScreen({
  playerId: 'player-id-123',
  isFullScreen: true,
});
console.log(result);

`getPlaybackQuality`

获取当前的播放画质。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getPlaybackQuality({ playerId: 'player-id-123' });
console.log(result);

`setPlaybackQuality`

设置建议的播放质量。实际质量可能会因网络状况而异。

import { YoutubePlayer, IPlaybackQuality } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.setPlaybackQuality({
  playerId: 'player-id-123',
  suggestedQuality: IPlaybackQuality.SMALL,
});
console.log(result);

`getAvailableQualityLevels`

获取当前视频可用的画质列表。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getAvailableQualityLevels({ playerId: 'player-id-123' });
console.log(result);

`getDuration`

获取当前视频的时长（秒）。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getDuration({ playerId: 'player-id-123' });
console.log(result);

`getVideoUrl`

获取当前视频的 YouTube.com URL。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getVideoUrl({ playerId: 'player-id-123' });
console.log(result);

`getVideoEmbedCode`

获取当前视频的嵌入 code。返回 HTML iframe 嵌入 code。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getVideoEmbedCode({ playerId: 'player-id-123' });
console.log(result);

`getPlaylist`

获取当前播放列表中的视频 ID 数组。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getPlaylist({ playerId: 'player-id-123' });
console.log(result);

`getPlaylistIndex`

获取播放列表中当前正在播放的视频索引。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getPlaylistIndex({ playerId: 'player-id-123' });
console.log(result);

`getIframe`

获取播放器的 iframe DOM 元素。仅限 Web 平台使用。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

const result = await YoutubePlayer.getIframe({ playerId: 'player-id-123' });
console.log(result);

`addEventListener`

为播放器添加事件监听器。仅限 Web 平台。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

YoutubePlayer.addEventListener({
  playerId: 'my-player',
  eventName: 'onStateChange',
  listener: (event) => {
  console.log('Player state:', event.data);
  },
});

`removeEventListener`

从播放器移除事件监听器。仅限 Web 平台。

import { YoutubePlayer } from '@capgo/capacitor-youtube-player';

await YoutubePlayer.removeEventListener({
  playerId: 'player-id-123',
  eventName: 'onReady',
  listener: (event) => {
    console.log(event);
  },
});

类型参考

`PlayerIdOptions`

export interface PlayerIdOptions {
  playerId: string;
}

`SeekToOptions`

export interface SeekToOptions extends PlayerIdOptions {
  playerId: string;
  seconds: number;
  allowSeekAhead: boolean;
}

`VideoByIdMethodOptions`

export interface VideoByIdMethodOptions extends PlayerIdOptions {
  playerId: string;
  options: IVideoOptionsById;
}

`VideoByUrlMethodOptions`

export interface VideoByUrlMethodOptions extends PlayerIdOptions {
  playerId: string;
  options: IVideoOptionsByUrl;
}

`PlaylistMethodOptions`

export interface PlaylistMethodOptions extends PlayerIdOptions {
  playerId: string;
  playlistOptions: IPlaylistOptions;
}

`PlayVideoAtOptions`

export interface PlayVideoAtOptions extends PlayerIdOptions {
  playerId: string;
  index: number;
}

`SetVolumeOptions`

export interface SetVolumeOptions extends PlayerIdOptions {
  playerId: string;
  volume: number;
}

`SetSizeOptions`

export interface SetSizeOptions extends PlayerIdOptions {
  playerId: string;
  width: number;
  height: number;
}

`SetPlaybackRateOptions`

export interface SetPlaybackRateOptions extends PlayerIdOptions {
  playerId: string;
  suggestedRate: number;
}

`SetLoopOptions`

export interface SetLoopOptions extends PlayerIdOptions {
  playerId: string;
  loopPlaylists: boolean;
}

`SetShuffleOptions`

export interface SetShuffleOptions extends PlayerIdOptions {
  playerId: string;
  shufflePlaylist: boolean;
}

`ToggleFullScreenOptions`

export interface ToggleFullScreenOptions extends PlayerIdOptions {
  playerId: string;
  isFullScreen: boolean | null | undefined;
}

唯一数据源

本页面由该插件的 src/definitions.ts当上游的公共 API 发生变化时，请重新运行 sync。

继续阅读入门指南

如果你正在使用 快速入门 来规划 dashboard 和 API 操作，请将其连接至使用 @capgo/capacitor-youtube-player 在“使用 @capgo/capacitor-youtube-player”中实现原生能力， API 概览关于 API 概览中的实现细节，简介有关 Introduction 中的实现细节， API 密钥有关 API Keys 中的实现细节，以及设备有关 Devices 中的实现细节。