VideoPlayer 组件参考

VideoPlayer 是一种视频播放组件,可通过该组件播放本地和远程视频。

播放本地视频

videoplayer

播放远程视频

videoplayer-remote

点击 属性检查器 下面的 添加组件 按钮,然后从 UI 组件 中选择 VideoPlayer,即可添加 VideoPlayer 组件到节点上。

VideoPlayer 的脚本接口请参考 VideoPlayer API

VideoPlayer 属性

属性功能说明
Resource Type视频来源的类型,目前支持本地(LOCAL)视频和远程(REMOTE)视频 URL
Remote URL当 Resource Type 为 REMOTE 时显示的字段,填入远程视频的 URL
Clip当 Resource Type 为 LOCAL 时显示的字段,拖拽本地视频的资源到此处来使用
Play On Awake视频加载后是否自动开始播放?
Current Time指定从哪个时间点开始播放视频
Volume视频的音量(0.0 ~ 1.0)
Mute是否静音视频。静音时设置音量为 0,取消静音时恢复原来的音量
Keep Aspect Ratio是否保持视频原来的宽高比
Full Screen On Awake是否全屏播放视频
Stay On Bottom永远在游戏视图最底层(该属性仅在 Web 平台生效)
Video Player Event视频播放回调函数,该回调函数会在特定情况被触发,比如播放中,暂时,停止和完成播放。详情见下方的 VideoPlayer 事件 章节或者 VideoPlayerEvent API

注意:Video Player Event 属性的 Node 中,应该填入的是一个挂载有用户脚本组件的节点,在用户脚本中便可以根据用户需要使用相关的 VideoPlayer 事件。

VideoPlayer 事件

VideoPlayerEvent 事件

属性功能说明
target带有脚本组件的节点。
component脚本组件名称。
handler指定一个回调函数,当视频开始播放后,暂停时或者结束时都会调用该函数,该函数会传一个事件类型参数进来。
customEventData用户指定任意的字符串作为事件回调的最后一个参数传入。

详情可参考 API 文档 Component.EventHandler 类型

事件回调参数

名称功能说明
PLAYING表示视频正在播放中。
PAUSED表示视频暂停播放。
STOPPED表示视频已经停止播放。
COMPLETED表示视频播放完成。
META_LOADED表示视频的元信息已加载完成,你可以调用 getDuration 来获取视频总时长。
READY_TO_PLAY表示视频准备好了,可以开始播放了。
ERROR处理视频时触发的错误
CLICKED表示视频被用户点击了。(只支持 Web 平台)

注意:在 iOS 平台的全屏模式下,点击视频无法发送 CLICKED 事件。如果需要让 iOS 全屏播放并正确接受 CLICKED 事件, 可以使用 Widget 组件把视频控件撑满。

详情可参考 VideoPlayer 事件 或者参考引擎自带的 test-cases-3d 测试例中的 21.video-player

详细说明

此控件支持的视频格式为 mp4

通过脚本代码添加回调

方法一

这种方法添加的事件回调和使用编辑器添加的事件回调是一样的。通过代码添加,首先你需要构造一个 Component.EventHandler 对象,然后设置好对应的 targetcomponenthandlercustomEventData 参数。

  1. import { _decorator, Component, VideoPlayer } from 'cc';
  2. const { ccclass, type } = _decorator;
  3. @ccclass('cc.MyComponent')
  4. export class MyComponent extends Component {
  5. @type(VideoPlayer)
  6. videoPlayer = null;
  7. start () {
  8. const eventHandler = new Component.EventHandler();
  9. eventHandler.target = newTarget; // 这个对象是你的事件处理代码组件所属的节点
  10. eventHandler.component = "MyComponent";
  11. eventHandler.handler = "callback";
  12. eventHandler.customEventData = "foobar";
  13. this.videoplayer.videoPlayerEvent.push(eventHandler);
  14. }
  15. // 注意参数的顺序和类型是固定的
  16. callback: function(videoplayer, eventType, customEventData) {
  17. // 这里的 videoplayer 是一个 VideoPlayer 组件对象实例
  18. // 这里的 eventType === VideoPlayer.EventType enum 里面的值
  19. // 这里的 customEventData 参数就等于你之前设置的 "foobar"
  20. }
  21. }

方法二

通过 videoplayer.node.on(VideoPlayer.EventType.READY_TO_PLAY, ...) 的方式来添加

  1. //假设我们在一个组件的 onLoad 方法里面添加事件处理回调,在 callback 函数中进行事件处理:
  2. import { _decorator, Component, VideoPlayer } from 'cc';
  3. const { ccclass, type } = _decorator;
  4. @ccclass('VideoPlayerCtrl')
  5. export class VideoPlayerCtrl extends Component {
  6. @type(VideoPlayer)
  7. videoPlayer = null;
  8. start () {
  9. this.videoplayer.node.on(VideoPlayer.EventType.READY_TO_PLAY, this.callback, this);
  10. }
  11. callback (event) {
  12. // 这里的 event 是一个 EventCustom 对象,你可以通过 event.detail 获取 VideoPlayer 组件
  13. let videoplayer = event.detail;
  14. // 对 videoplayer 进行你想要的操作
  15. // 另外,注意这种方式注册的事件,也无法传递 customEventData
  16. }
  17. }

同样的,用户也可以注册 meta-loadedclickedplaying 等事件,这些事件的回调函数的参数与 ready-to-play 的参数一致。

注意: 由于 VideoPlayer 是特殊的组件,所以它无法监听节点上的 触摸鼠标 事件。

关于完整的 VideoPlayer 的事件列表,可以参考 VideoPlayer API

如何实现 UI 在 VideoPlayer 上渲染

可通过以下三个步骤实现 UI 在 VideoPlayer 上显示:

  1. 确保 项目设置 Macro Config 中的 ENABLE_TRANSPARENT_CANVAS 为勾选状态(设置 Canvas 背景支持 alpha 通道)

    VideoPlayer 组件参考 - 图3

  2. 可通过 属性检查器 中勾选 VideoPlayer 组件上的 stayOnBottom 属性。

    VideoPlayer 组件参考 - 图4

注意:

  • 该功能仅支持 Web 平台。
  • 各个浏览器具体效果无法保证一致,跟浏览器是否支持与限制有关。
  • 开启 stayOnBottom 后,将无法正常监听 VideoPlayerEvent 中的 clicked 事件。

详情可参考引擎自带的 test-cases-3d 测试例中的 21.video-player。最终效果如下图所示:

videoplayer-stayOnButtom

支持平台

由于不同平台对于 VideoPlayer 组件的授权、API、控制方式都不同,还没有形成统一的标准,所以目前只支持 Web、iOS、Android、微信小游戏、Facebook Instant Games 以及 Google Play Instant 平台。

关于自动播放的问题

一些移动端的浏览器或 WebView 不允许自动播放视频,用户需要在触摸事件中手动播放视频。

  1. import { _decorator, Node, Component, find, VideoPlayer } from 'cc';
  2. const { ccclass, type } = _decorator;
  3. @ccclass('VideoPlayerCtrl')
  4. export class VideoPlayerCtrl extends Component {
  5. @type(VideoPlayer)
  6. videoPlayer = null;
  7. start () {
  8. let canvas = find('Canvas');
  9. canvas.on(Node.EventType.TOUCH_START, this.playVideo, this);
  10. }
  11. playVideo () {
  12. this.videoplayer.play();
  13. }
  14. }