控制器 YouTube 播放器插件

嵌入和控制的非官方电容插件 YouTube (英语) android、iOS和Web上的玩家。[^1]

特征

Capacitor YouTube Player插件将YouTube视频嵌入为内线,帧定位于您Capacitor应用程序的玩家. 以下是一些关键特征:

• 🖥️ 跨平台:支持Android,iOS,和Web.
• 🎞️ 内置回放:在所有平台上嵌入玩家,包括iOS.
• 🧩 多种精神:通过ID同时创建并控制多个玩家.
• 📐 框架定位: 使用 CSS 像素帧定位并调整播放器大小, 使其与您的布局同步 .
• 🎛️ 播放控件:装入,提示,播放,暂停,寻找,哑音,音量,和回放速率.
• 📡 类型事件: 听好了,状态,时间,速率,出错,和有打出收听器的全屏事件.
• 📜 术语:建于官方YouTube IFrame Player API上,并配有符合TOS的管道(参见 YouTube 服务条件) (中文(简体) ).
• 🤝 兼容性: 与 媒体会议 财务报告和审定财务报表 屏幕方向 插件 .
• 📦 可可花和SPM:支持CocoaPods和Swift软件包管理器用于iOS.
• 🔁 最新数据:总是支持最新的Capacitor版本.

缺少一个功能? 刚刚 打开一个问题 我们看看!

使用大小写

YouTube Player插件一般用于任何您想要将YouTube视频嵌入您的应用中的地方,例如:

• 媒体应用程序:嵌入了预告片,音乐视频,或内容中的插曲.
• 登入帮助( H):在您的应用程序中直接显示教程和视频.
• 新闻和博客:Render YouTube嵌入有本土回放表演的文章.
• 学历:在一页上搭建多段视频课的课程屏幕.

兼容性

安装

你可以用我们的 AI 辅助设置 以安装插件. 添加数据 超级技能 至您的 AI 工具,使用以下命令:

npx skills add capawesome-team/skills --skill capacitor-plugins

然后使用下列提示:

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

如果你喜欢 手动设置,通过运行以下命令来安装插件,并遵循下面的平台特定指令:

npm install @capawesome/capacitor-youtube-player
npx cap sync

机器人

在Android上,插件使用 机器人-youtube-播放器 库,是一款围绕官方YouTube IFrame Player API的开源包装.

变量

此插件将使用以下工程变量( 在您的应用程序中定义) variables.gradle 文件名 :

• $androidYoutubePlayerVersion 版本 com.pierfrancescosoffritti.androidyoutubeplayer:core (默认 : 13.1.0(中文(简体) )

权限

插件自动添加 android.permission.ACCESS_NETWORK_STATE 允许您的应用程序的列表。 它用于在网络连接丢失并恢复时恢复玩家. 不需要你采取行动.

iOS系统

在 iOS 上,插件使玩家在 WKWebView 使用官员 YouTube IFrame 播放器 API。不需要额外的配置.

网页

网络执行加载 YouTube IFrame 播放器 API 从YouTube的运行时间。 这需要主动的网络连接. 如果您的应用程序执行 内容安全政策,确保允许YouTube域(例如. https://www.youtube.com 页:1 script-src 财务报告和审定财务报表 frame-src,以及 https://www.youtube-nocookie.com 页:1 frame-src 如果你设置 host 选项).

配置

此插件不需要配置 .

使用量

以下例子显示如何使用插件 .

创建玩家

在您的布局中测量占位符元素, 并在其位置创建玩家 :

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

const createPlayer = async () => {
  const rect = document
    .querySelector('#player-placeholder')
    .getBoundingClientRect();
  await YoutubePlayer.createPlayer({
    id: 'my-player',
    frame: {
      x: rect.x,
      y: rect.y,
      width: rect.width,
      height: rect.height,
    },
    videoId: 'dQw4w9WgXcQ',
    options: {
      mute: true,
    },
  });
};

控制重播

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

const controlPlayback = async () => {
  await YoutubePlayer.play({ id: 'my-player' });
  await YoutubePlayer.seekTo({ id: 'my-player', seconds: 42 });
  await YoutubePlayer.setVolume({ id: 'my-player', volume: 50 });
  await YoutubePlayer.setPlaybackRate({ id: 'my-player', rate: 1.5 });
  await YoutubePlayer.pause({ id: 'my-player' });
};

倾听事件

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

const addListeners = async () => {
  await YoutubePlayer.addListener('playerReady', event => {
    console.log('Player ready:', event.id);
  });
  await YoutubePlayer.addListener('playerStateChange', event => {
    console.log('Player state:', event.id, event.state);
  });
  await YoutubePlayer.addListener('playerError', event => {
    console.error('Player error:', event.id, event.code);
  });
};

删除玩家

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

const removePlayer = async () => {
  await YoutubePlayer.removePlayer({ id: 'my-player' });
};

API 密码

• createPlayer(...)
• cueVideo(...)
• getCurrentTime(...)
• getDuration(...)
• loadVideo(...)
• mute(...)
• pause(...)
• play(...)
• removePlayer(...)
• seekTo(...)
• setPlaybackRate(...)
• setPlayerFrame(...)
• setVolume(...)
• unmute(...)
• addListener('currentTimeChange', ...)
• addListener('fullscreenChange', ...)
• addListener('playbackRateChange', ...)
• addListener('playerError', ...)
• addListener('playerReady', ...)
• addListener('playerStateChange', ...)
• removeAllListeners()
• 接口
• 类型异名

创建 Player (...)

createPlayer(options: CreatePlayerOptions) => Promise<CreatePlayerResult>

创建新的YouTube播放器.

在Android和iOS上,玩家作为本地视图渲染,即: 位于给定框架的网页视图上方。 这个框架不是 以网页内容滚动. 使用 setPlayerFrame(...) 保留 与您的布局同步的帧(请参见 README 的配方).

玩家必须至少为 200x200 CSS 像素, 按照要求 YouTube 服务条件。 。 。 .

回返情况: Promise<CreatePlayerResult>

自: 0.1.0 (中文(简体) )

cueVideo (...) (中文(简体) )

cueVideo(options: CueVideoOptions) => Promise<void>

在播放器中装入视频而不开始播放.

自: 0.1.0 (中文(简体) )

获取当前时间(...)

getCurrentTime(options: GetCurrentTimeOptions) => Promise<GetCurrentTimeResult>

获取玩家当前播放时间 .

在Android上,该值从最近推出值中解答: 播放器(在播放时每秒更新多次).

回返情况: Promise<GetCurrentTimeResult>

自: 0.1.0 (中文(简体) )

获取期限(...)

getDuration(options: GetDurationOptions) => Promise<GetDurationResult>

获取当前装入的视频的持续时间 .

在Android上,该值从最近推出值中解答: 球员.

回返情况: Promise<GetDurationResult>

自: 0.1.0 (中文(简体) )

加载视频(...)

loadVideo(options: LoadVideoOptions) => Promise<void>

将视频装入玩家开始回放.

自: 0.1.0 (中文(简体) )

哑巴(...)

mute(options: MuteOptions) => Promise<void>

关闭玩家.

自: 0.1.0 (中文(简体) )

暂停(...)

pause(options: PauseOptions) => Promise<void>

暂停播放.

自: 0.1.0 (中文(简体) )

播放(...)

play(options: PlayOptions) => Promise<void>

开始或恢复播放 .

自: 0.1.0 (中文(简体) )

删除 Player (...)

removePlayer(options: RemovePlayerOptions) => Promise<void>

删除玩家并释放其全部资源.

自: 0.1.0 (中文(简体) )

请求(...)

seekTo(options: SeekToOptions) => Promise<void>

寻求给定的时间.

自: 0.1.0 (中文(简体) )

设置PlaybackRate(...)

setPlaybackRate(options: SetPlaybackRateOptions) => Promise<void>

设定玩家的回放率 .

自: 0.1.0 (中文(简体) )

设置 PlayerFrame (...)

setPlayerFrame(options: SetPlayerFrameOptions) => Promise<void>

更新玩家的框架 .

当布局发生变化时调用此方法( 例如在滚动、 调整大小或 方向变化),使玩家与您的布局保持同步.

自: 0.1.0 (中文(简体) )

设置卷 (...)

setVolume(options: SetVolumeOptions) => Promise<void>

设定玩家的音量 .

在iOS上,操作系统不允许更改音量 在方案上,这种方法没有效果。 使用 mute() 财务报告和审定财务报表 unmute() 换句话说.

自: 0.1.0 (中文(简体) )

解密(...)

unmute(options: UnmuteOptions) => Promise<void>

释出玩家.

自: 0.1.0 (中文(简体) )

添加倾听器( “ 当前时间变化 ” ,...)

addListener(eventName: 'currentTimeChange', listenerFunc: (event: CurrentTimeChangeEvent) => void) => Promise<PluginListenerHandle>

当玩家当前播放时间发生变化时调用.

该事件在回放时每秒发射多次 。 这个 准确的频率取决于平台.

回返情况: Promise<PluginListenerHandle>

自: 0.1.0 (中文(简体) )

添加倾听器( “ 全屏变化 ” ,...)

addListener(eventName: 'fullscreenChange', listenerFunc: (event: FullscreenChangeEvent) => void) => Promise<PluginListenerHandle>

当玩家进出全屏时调用.

仅在Android和Web上提供.

回返情况: Promise<PluginListenerHandle>

自: 0.1.0 (中文(简体) )

添加 listener ('playbackRateChange', ...) 键盘重置

addListener(eventName: 'playbackRateChange', listenerFunc: (event: PlaybackRateChangeEvent) => void) => Promise<PluginListenerHandle>

当玩家的回放率改变时调用.

在 iOS 上,此事件仅为 setPlaybackRate(...) 打电话.

回返情况: Promise<PluginListenerHandle>

自: 0.1.0 (中文(简体) )

添加倾听器( “ player Error ” ,...)

addListener(eventName: 'playerError', listenerFunc: (event: PlayerErrorEvent) => void) => Promise<PluginListenerHandle>

当玩家出现错误时调用 .

回返情况: Promise<PluginListenerHandle>

自: 0.1.0 (中文(简体) )

添加收听器( “ 播放器 Ready ” )..

addListener(eventName: 'playerReady', listenerFunc: (event: PlayerReadyEvent) => void) => Promise<PluginListenerHandle>

当玩家装入完毕并准备接收时调用 命令.

回返情况: Promise<PluginListenerHandle>

自: 0.1.0 (中文(简体) )

添加倾听器( “ player State Change ” ,...)

addListener(eventName: 'playerStateChange', listenerFunc: (event: PlayerStateChangeEvent) => void) => Promise<PluginListenerHandle>

当玩家状态发生变化时调用.

回返情况: Promise<PluginListenerHandle>

自: 0.1.0 (中文(简体) )

删除所有收听器( )

removeAllListeners() => Promise<void>

删除此插件的所有听众 .

自: 0.1.0 (中文(简体) )

接口

创建 Player 报表

创建 Player 选项

玩家屏幕

CSS像素中的玩家框架,相对取景口.

玩家选项

创建 Player 网络选项

CueVideo 选项

获取当前时间结果

获取当前时间选项

获取期限

获取期限选项

加载视频选项

静音选项

暂停选项

播放选项

删除层选项

查找选项

设置回放选项

设置 PlayerFrame 选项

设置组合选项

取消选项

插件听筒

当前时间变化事件

全屏变化事件

回放Rate 变换事件

玩家错误事件

玩家准备活动

玩家状态变化事件

类型异名

玩家错误代码

玩家错误的错误代码 .

'html5-error' | 'invalid-parameter' | 'not-embeddable' | 'unknown' | 'video-not-found'

玩家状态

玩家状态.

'buffering' | 'cued' | 'ended' | 'paused' | 'playing' | 'unstarted'

框架同步

在Android和iOS上,玩家是一个被渲染的本地视图 上文 网页视图。 它不是DOM的一部分,因此不会用您的网页内容来滚动或调整大小. 相反,您将其定位为 CSS 像素框架,并通过调用使其与您的布局同步 setPlayerFrame(...) 当布局改变时:

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

const syncPlayerFrame = async () => {
  const rect = document
    .querySelector('#player-placeholder')
    .getBoundingClientRect();
  await YoutubePlayer.setPlayerFrame({
    id: 'my-player',
    frame: {
      x: rect.x,
      y: rect.y,
      width: rect.width,
      height: rect.height,
    },
  });
};

window.addEventListener('scroll', syncPlayerFrame);
window.addEventListener('resize', syncPlayerFrame);

如果使用带有自有滚动容器的框架(例如:. ion-content),将收听者附加在那个容器的卷轴事件上。 在网络上,玩家的位置是 position: fixed因此,同样的同步代码在所有平台上都起作用. 或者,在网络上,您可以使用 web.elementId 选项,在这种情况下不需要帧同步.

由于播放器在网页视图上方渲染,HTML内容永远不能与播放器相重叠. 在设计您的布局时记住这一点( 另见 YouTube 服务条件) (中文(简体) ).

YouTube 服务条件

通过使用此插件,您同意 YouTube 服务条件 编辑 YouTube API 服务条款。插件的设计是为了便于遵守 所需的最低功能 用于嵌入式玩家 :

• 最小玩家大小:嵌入式玩家必须至少有200×200像素. 插件执行此选项并拒绝带有较小框架的 FRAME_INVALID 错误代码 .
• 没有背景播放:视频不得在后台播放. 当应用程序被移动到背景时,插件会自动暂停所有玩家.
• 没有覆盖:玩家(包括其广告)不得被其他内容所掩盖. 由于本地玩家的视图总是在网页视图上方提供,所以HTML内容不能通过设计来相重叠.
• 正确来源: 插件设置 origin 玩家参数在所有平台上正确,这可以避免嵌入出错(例如错误152/153)而无需任何标题工作.
• 没有玩家修改:插件嵌入了官方YouTube播放器未被更改. 您的应用程序不能修改、 建立在或屏蔽玩家的任何部分或功能—— 包括它服务的任何广告.
• 标记: 如果您的应用程序与玩家一起显示 YouTube 标志或其他品牌资产, 请跟随 YouTube 品牌准则。 。 。 .

平台支持

并非所有的平台都有功能。 下表列出插件的API的每个平台差异:

额外的特定平台行为 :

• iOS 变形模拟: iOS 播放器库显示没有本地哑音 API,所以 mute() 通过设置音量来模拟 0。 。 。 . unmute() 通过 setVolume(...) (或 100) (中文(简体) ). 若为 setVolume(...) 在播放器被变音时调用, 音量只在下一个时应用 unmute() 电话.
• iOS 播放率事件: 在iOS上,该 playbackRateChange 事件仅为 setPlaybackRate(...) 由于 iOS 播放器库没有显示回放率调用.
• iOS 错误映射: 在iOS上,不允许在嵌入式玩家中播放的视频可以使用错误代码进行报告 unknown 改为 not-embeddable,由于iOS播放器库的映射出错误.
• Android 获取器:关于Android, getCurrentTime(...) 财务报告和审定财务报表 getDuration(...) 由玩家所推动的最新数值解答,在回放时每秒更新多次.
• currentTimeChange 频率:该事件在Android上每秒发射约10次,在iOS和Web上每秒发射约2次.

财务问题

此插件与其他类似插件有何不同?

此插件可以同时使多个本地玩家事件, 每个位置都定位到一个精确的框架, 您会保持与您的布局同步 。 它揭露了Android,iOS,和Web上一个完整而强烈打字的事件设定,并嵌入了官方YouTube播放器未被更改. 它是为了遵守YouTube Terms of Service要求的行为而建造的——最小的玩家大小,没有背景回放,没有被画过玩家,以及正确的出处——所以默认情况下保持遵守. 它得到坚定支持的积极维护和支持.

为什么我的画框被拒绝 FRAME_INVALID? 吗?

嵌入式YouTube播放器必须至少是200×200 CSS像素,这是YouTube服务条款的要求. 确保 width 财务报告和审定财务报表 height 您的相框至少是 200。 。 。 .

为什么玩家没有用我的内容来滚动?

在Android和iOS上,玩家是网络视图上方所渲染的本土视图,不属于DOM. 使用 setPlayerFrame(...) 使其与您的布局同步(参见 框架同步) (中文(简体) ).

我可以在播放器上方显示 HTML 内容吗 ?

没有。 本地玩家视图总是在网页视图上方提供. 这也是YouTube的"服务条款"中的一项要求,该规定禁止混淆玩家.

在背景中还继续播放吗?

没有 YouTube的"服务条款"禁止背景回放,因此插件在应用程序被移动到背景时会自动暂停所有玩家.

我能用这个插件吗? 有Ionic、React、Vue或Angular?

是的,插件是框架不可知的。 它在任意网络框架的Capacitor app中工作,包括有Angular,React,或Vue的Ionic,以及平版JavaScript等项目.

相关插件

• 媒体会议: 与媒体控制器,音量键和媒体按钮进行交互.
• 屏幕方向:锁定并解锁屏幕取向,例如允许地貌回放.

通讯

随时更新有关卡帕韦索姆、Capacitor和Ionic生态系统的最新消息和最新消息,因为我们 《卡帕索克通讯》。 。 。 .

更改日志

见 变动情况。 。 。 .

许可证

见 自由主义。 。 。 .

[^1]: 这个项目不附属于Google LLC或YouTube LLC或其任何子公司或子公司,也不由它们认可,也不由它们赞助或批准. "YouTube"是谷歌有限责任公司的一个商标.