获取 Video.js

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

Video.js 不仅可以通过 HTML <script> 和 <link> 标签直接使用，还可以与所有主要打包器/包装器/构建器（例如 Browserify、Node、WebPack 等）配合使用。

有关详细信息，请参阅入门文档。

创建播放器

注意：Video.js 适用于 <video> 和 <audio> 元素，但为简单起见，后续我们将只提及 <video> 元素。

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

Video.js 的核心优势在于它会装饰一个标准的 <video> 元素，并模拟其相关的事件和 API，同时提供可自定义的基于 DOM 的用户界面。

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>

要了解所有各种嵌入选项的高级概述，请查看嵌入页面，然后继续阅读本页面的其余部分。

自动设置

默认情况下，当您的网页完成加载时，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。

手动设置

在现代网络中，页面加载完成后 <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>

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>

videojs(document.querySelector('.video-js'));

获取播放器引用

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

使用 videojs

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

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

使用 videojs.getPlayer()

有时，您希望获取播放器的引用，而避免调用 videojs() 可能产生的副作用。这可以通过调用 videojs.getPlayer() 并传入与元素 ID 匹配的字符串或元素本身来实现。

使用 videojs.getPlayers() 或 videojs.players

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

播放器以其 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> 标签属性的注意事项

许多属性是所谓的布尔属性。这意味着它们要么开启，要么关闭。在这些情况下，属性不应有值（或应以其名称作为其值）——它的存在意味着真值，它的缺失意味着假值。

这些是错误的

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

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

这些是正确的

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

播放器就绪

由于 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()，如果播放器已经就绪，函数会立即调用。

高级播放器工作流程

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