开始入门

安装

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

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.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

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

导入

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

解决YouTube Referer阻塞在主WebView

如果 YouTube 在插件中正常工作，但在同一应用加载 YouTube 页面、嵌入或 API 时失败，通过 Capacitor 主 WebView，请启用 patchRefererHeader 在您的 Capacitor 配置中启用

启用后，插件将在同步/更新期间修补 Capacitor，以便拦截的 YouTube 请求包含有效的 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 for the native capability in Using @capgo/capacitor-youtube-player, API概述 为实现细节在API概述中 简介 为实现细节在简介中 API密钥 为实现细节在API密钥中，和 设备 为实现细节在设备中。