开始使用

安装

您可以使用我们的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';

修复主 WebView 中的 YouTube Referer 阻塞

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 已经定义了
• header Referer header 保持原始值。
• 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

播放列表的提示

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

pagePath

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

Get the embed code for the current video. Returns HTML iframe embed 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 的原生能力 API 概述 为 API 概述 的实现细节 介绍 为介绍 的实现细节 API 密钥 为 API 密钥 的实现细节， 设备 为设备 的实现细节。