Video.js Setup 设置

Tutorial: setup | Video.js Documentation

Video.js Setup 设置

获取 Video.js

Video.js 通过 CDN 和 npm 正式提供。

Video.js 不仅可以使用 HTML <script> 和 <link> 引入，还可以使用所有主流的 bundlers/packagers/builders，如 Browserify、Node、WebPack等。

有关详细信息，请参阅入门文档](https://videojs.com/getting-started/))。

创建一个 Player

注意：Video.js与 <Video> 和 <audio> 元素一起工作，但为了简单起见，我们将只使用<Video> 元素。

一旦在页面上加载了 Video.js，就可以创建播放器了！

Video.js 的核心优势在于它装饰了一个标准的 <Video> 元素并模拟了其关联的事件和 APIs，同时提供了一个可定制的基于 DOM 的UI。

Video.js 支持 <Video> 元素的所有属性（如controls、preload等），但它也支持自己的选项。有两种方法可以创建 Video.js 播放器并传递选项，但它们都是从 class="video-js" 的标准 <Video> 元素开始的：

<video class="video-js">
  <source src="//vjs.zencdn.net/v/oceans.mp4" type="video/mp4">
  <source src="//vjs.zencdn.net/v/oceans.webm" type="video/webm">
</video>

您可以使用 <video js> 元素而不是 <video>。在某些情况下，使用 <video> 元素是不可取的，因为浏览器可能会在播放器初始化之前显示未设置样式的控件或尝试加载源，而自定义元素 <video js> 不会出现这种情况。

<video-js>
  <source src="//vjs.zencdn.net/v/oceans.mp4" type="video/mp4">
  <source src="//vjs.zencdn.net/v/oceans.webm" type="video/webm">
</video-js>

有关所有嵌入方式的高级概述，请查看 embeds page，然后按照本页面的其余部分进行操作。

自动设置

默认情况下，当您的网页完成加载时，Video.js 将扫描具有 data-setup 属性的媒体元素。data-setup 属性用于将选项传递给 Video.js。最简单的例子如下所示：

<video class="video-js" data-setup='{}'>
  <source src="//vjs.zencdn.net/v/oceans.mp4" type="video/mp4">
  <source src="//vjs.zencdn.net/v/oceans.webm" type="video/webm">
</video>

注意：必须在 data-setup 中使用单引号，因为它应该包含JSON。

手动设置

在现代 web 上，页面加载完成后，<video> 元素通常不存在。在这些情况下，无法进行自动设置，但可以通过 videojs 方法进行手动设置。

调用此方法的方式是为其提供 <video> 元素的 id 属性字符串：

<video id="my-player" class="video-js">
  <source src="//vjs.zencdn.net/v/oceans.mp4" type="video/mp4">
  <source src="//vjs.zencdn.net/v/oceans.webm" type="video/webm">
</video>
var player = videojs('my-player');

然而，使用 id 属性并不总是可行的；因此，videojs 方法也可以接受 DOM 元素：

<video class="video-js">
  <source src="//vjs.zencdn.net/v/oceans.mp4" type="video/mp4">
  <source src="//vjs.zencdn.net/v/oceans.webm" type="video/webm">
</video>
var player = videojs(document.querySelector('.video-js'));

获取 Players 的引用

当创建播放器后，Video.js 会在内部跟踪它们。有几种方法可以获得已创建的播放器的引用。

使用 `videojs`

使用创建好的播放器的元素 ID 调用 videojs() 将返回该播放器，而不会创建新的播放器。

如果没有与参数匹配的播放器，将尝试创建一个。

使用 `videojs.getPlayer()`

有时，您希望获得对播放器的引用时，避免调用 videojs() 的潜在副作用。这可以通过调用 videojs.getPlayer() 来实现，它接收元素的 ID 或元素本身。

使用 `videojs.getPlayers()` 或 `videojs.players`

videojs.players 属性存放所有已知的播放器。方法 videojs.getPlayers() 返回相同的对象。

该对象存储所有的播放器，key 是与其匹配的 ID。

注意：从没有 ID 的元素创建的播放器将被分配一个自动生成的 ID。

选项

注意：本指南仅介绍如何在播放器设置期间传递选项。有关所有可用选项的完整参考，请参阅选项指南.。

有三种方法可以将选项传递给 Video.js。由于 Video.js 装饰了 HTML5 <video> 元素，因此许多可用选项也可作为 <video> 元素标准属性使用。

<video controls autoplay preload="auto" ...>

或者，可以使用 data-setup 属性将选项通过 JSON 传递。这也是设置 <video> 元素非标准选项的方法：

<video data-setup='{"controls": true, "autoplay": false, "preload": "auto"}'...>

注意：必须在 data-setup 的值周围使用单引号，因为它包含必须使用双引号的 JSON 字符串。

最后，如果未使用 data-setup 属性触发播放器设置，则可以将播放器选项的对象作为第二个参数传递给 videojs 方法：

videojs('my-player', {
  controls: true,
  autoplay: false,
  preload: 'auto'
});

注意：不要同时使用 data-setup 和选项对象。

全局默认值

所有播放器的默认选项都可以在 videojs.options 上找到，并且可以直接更改。例如，要为所有未来播放器设置{autoplay:true}，请执行以下操作：

videojs.options.autoplay = true;

关于 `<video>` 属性的说明

许多属性都是布尔属性。这意味着它们要么打开（on），要么关闭（off）。在这些情况下，属性应该没有值（或者应该将其名称作为其值）——它的存在意味着真值，而它的缺失意味着假值。

这些是不正确的：

<video controls="true" ...>
<video loop="true" ...>
<video controls="false" ...>

注意：带有 controls="false"的示例可能会让新开发人员感到困惑——它实际上会打开控件！

这些是正确的：

<video controls ...>
<video loop="loop" ...>
<video ...>

Player 准备状态

由于 Video.js 技术具有异步加载的特性，因此在设置后立即与播放器交互并不总是安全的。因此，Video.js 播放器有一个“准备状态”的概念，以前使用过 jQuery 的人都会熟悉这个概念。

本质上，可以为 Video.js 播放器定义任意数量的准备就绪回调。有三种方法可以传递这些回调。在每个示例中，我们将向播放器添加相同的类：

将回调作为第三个参数传递给 videojs() 方法：

// Passing `null` for the options argument.
videojs('my-player', null, function() {
  this.addClass('my-example');
});

将回调传递给播放器的 ready() 方法：

var player = videojs('my-player');
player.ready(function() {
  this.addClass('my-example');
});

监听播放器的 ready 事件：

var player = videojs('my-player');
player.on('ready', function() {
  this.addClass('my-example');
});

在每种情况下，回调都是异步调用的。

上述方式之间的一个重要区别是，必须在播放器准备就绪之前通过 on()为 ready 事件添加侦听器。对于player.ready()，如果播放器已准备就绪，则会立即调用该函数。

高级播放器工作流

有关更高级的播放器工作流的讨论，请参阅《播放器工作流指南》。

setup