快速入门

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

        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 配置中。

启用后，插件会在 sync/update 时修补 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 Overview 中的实现细节，简介关于 Introduction 中的实现细节， API 密钥有关 API Keys 的实现细节，以及设备有关 Devices 的实现细节。