开始

安装

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

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

然后使用以下提示：

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';

修复 YouTube Referer 阻塞在主 WebView 中

If YouTube works inside the plugin but fails when the same app loads YouTube pages, embeds, or APIs through Capacitor’s main WebView, enable patchRefererHeader in your Capacitor config.

When enabled, the plugin patches Capacitor during sync/update so intercepted YouTube requests include a valid Referer 启用后，插件将在同步/更新期间修补

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

• 复制到剪贴板 youtube.com, youtube-nocookie.com仅 youtu.be , 和
• 请求受影响。 Referer 已定义的
• refererHeader 请求保留其原始值。 https://www.youtube.com.
• 在 Capacitor 上支持 8.x 适用于已安装的 iOS 和 Android 平台。

API 概览

initialize

初始化一个新的 YouTube 播放器实例。

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

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

destroy

销毁一个播放器实例并释放资源。

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

await YoutubePlayer.destroy({} as PlayerIdOptions);

stopVideo

停止视频播放并取消加载。 尽量少用此功能 - 使用 pauseVideo() 通常更好。

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

await YoutubePlayer.stopVideo({} as PlayerIdOptions);

playVideo

播放当前缓冲或已加载的视频。 最终播放器状态将为PLAYING（1）。

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

await YoutubePlayer.playVideo({} as PlayerIdOptions);

pauseVideo

暂停当前播放的视频。 最终播放器状态将为PAUSED（2），除非已经结束（0）。

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

await YoutubePlayer.pauseVideo({} as PlayerIdOptions);

seekTo

在视频中寻找特定时间。 如果播放器暂停，播放器将保持暂停状态。如果正在播放，继续播放。

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

await YoutubePlayer.seekTo({} as SeekToOptions);

loadVideoById

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

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

await YoutubePlayer.loadVideoById({} as VideoByIdMethodOptions);

cueVideoById

通过 ID 播放视频时不播放。 加载缩略图并准备播放器，但直到调用 playVideo() 才请求视频。

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

await YoutubePlayer.cueVideoById({} as VideoByIdMethodOptions);

loadVideoByUrl

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

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

await YoutubePlayer.loadVideoByUrl({} as VideoByUrlMethodOptions);

cueVideoByUrl

通过 URL 播放视频时不播放。

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

await YoutubePlayer.cueVideoByUrl({} as VideoByUrlMethodOptions);

cuePlaylist

通过 URL 加载并播放视频。 加载播放列表并准备第一首视频。

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

await YoutubePlayer.cuePlaylist({} as PlaylistMethodOptions);

loadPlaylist

加载并播放播放列表。

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

await YoutubePlayer.loadPlaylist({} as PlaylistMethodOptions);

nextVideo

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

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

await YoutubePlayer.nextVideo({} as PlayerIdOptions);

previousVideo

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

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

await YoutubePlayer.previousVideo({} as PlayerIdOptions);

playVideoAt

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

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

await YoutubePlayer.playVideoAt({} as PlayVideoAtOptions);

mute

静音播放器音频。

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

await YoutubePlayer.mute({} as PlayerIdOptions);

unMute

取消播放器音频静音。

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

await YoutubePlayer.unMute({} as PlayerIdOptions);

isMuted

复制到剪贴板

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

await YoutubePlayer.isMuted({} as PlayerIdOptions);

setVolume

复制到剪贴板

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

await YoutubePlayer.setVolume({} as SetVolumeOptions);

getVolume

获取当前播放器音量水平。 即使播放器静音，也会返回音量。

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

await YoutubePlayer.getVolume({} as PlayerIdOptions);

setSize

以像素为单位设置播放器尺寸。

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

await YoutubePlayer.setSize({} as SetSizeOptions);

getPlaybackRate

获取当前播放速度。

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

await YoutubePlayer.getPlaybackRate({} as PlayerIdOptions);

setPlaybackRate

设置播放速度。

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

await YoutubePlayer.setPlaybackRate({} as SetPlaybackRateOptions);

getAvailablePlaybackRates

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

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

await YoutubePlayer.getAvailablePlaybackRates({} as PlayerIdOptions);

setLoop

开启或关闭循环播放。 开启后，播放列表将在最后一部视频结束后重新开始。

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

await YoutubePlayer.setLoop({} as SetLoopOptions);

setShuffle

开启或关闭播放列表混洗。

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

await YoutubePlayer.setShuffle({} as SetShuffleOptions);

getVideoLoadedFraction

获取视频缓冲的百分比。 比已废弃的getVideoBytesLoaded/getVideoBytesTotal更可靠。

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

await YoutubePlayer.getVideoLoadedFraction({} as PlayerIdOptions);

getPlayerState

获取当前玩家的状态。

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

await YoutubePlayer.getPlayerState({} as PlayerIdOptions);

getAllPlayersEventsState

获取所有活跃玩家事件的状态。 用于跟踪多个玩家实例。

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

await YoutubePlayer.getAllPlayersEventsState();

getCurrentTime

获取当前播放位置（以秒为单位）。

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

await YoutubePlayer.getCurrentTime({} as PlayerIdOptions);

toggleFullScreen

切换全屏模式开关。

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

await YoutubePlayer.toggleFullScreen({} as ToggleFullScreenOptions);

getPlaybackQuality

获取当前播放质量。

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

await YoutubePlayer.getPlaybackQuality({} as PlayerIdOptions);

setPlaybackQuality

设置建议的播放质量。 实际质量可能根据网络条件而有所不同。

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

await YoutubePlayer.setPlaybackQuality({} as SetPlaybackQualityOptions);

getAvailableQualityLevels

获取当前视频的可用质量级别列表。

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

await YoutubePlayer.getAvailableQualityLevels({} as PlayerIdOptions);

getDuration

获取当前视频的时长（以秒为单位）。

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

await YoutubePlayer.getDuration({} as PlayerIdOptions);

getVideoUrl

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

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

await YoutubePlayer.getVideoUrl({} as PlayerIdOptions);

getVideoEmbedCode

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

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

await YoutubePlayer.getVideoEmbedCode({} as PlayerIdOptions);

getPlaylist

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

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

await YoutubePlayer.getPlaylist({} as PlayerIdOptions);

getPlaylistIndex

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

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

await YoutubePlayer.getPlaylistIndex({} as PlayerIdOptions);

getIframe

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

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

await YoutubePlayer.getIframe({} as PlayerIdOptions);

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({} as PlayerEventListenerOptions<TEvent>);

类型参考

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发生更改时，请重新同步。

继续从开始

如果您正在使用 开始 规划仪表板和API操作，请将其连接到 使用@capgo/capacitor-youtube-player 在使用@capgo/capacitor-youtube-player时，native能力 API概述 为实现细节在 API 概述中 简介 为实现细节在简介中 API 密钥 为实现细节在 API 密钥中，和 设备 为实现细节在设备中。