注意：本文档仅供参考可用选项。要了解如何将选项传递给 Video.js，请参阅安装指南。

标准 <video> 元素选项

每个选项也可用作标准 <video> 元素属性；因此，它们可以通过安装指南中概述的三种方式进行定义。通常，默认值不在此列出，因为这取决于浏览器供应商。

autoplay

类型：boolean|string 注意：目前，autoplay 属性和选项并不能保证您的视频会自动播放。注意2：如果媒体元素上存在属性，则该选项将被忽略。注意3：您不能在属性中传递字符串值，必须在 videojs 选项中传递。

您应该向 videojs 函数传递一个 autoplay 选项，而不是使用 autoplay 属性。以下值有效：

• 布尔值 false：与视频元素上没有属性相同，不会自动播放。
• 布尔值 true：与视频元素上存在属性相同，将使用浏览器自动播放。
• 字符串值 'muted'：将使视频元素静音，然后在 loadstart 时手动调用 play()。这很可能会起作用。
• 字符串值 'play'：将在 loadstart 时调用 play()，类似于浏览器的自动播放。
• 字符串值 'any'：将在 loadstart 时调用 play()，如果 Promise 被拒绝，它将使视频元素静音，然后调用 play()。

如何传递选项

var player = videojs('my-video', {
  autoplay: 'muted'
});

// or

player.autoplay('muted');

关于 autoplay 支持和更改的更多信息

• 请参阅我们的博客文章：Video.js 自动播放最佳实践

controlBar.remainingTimeDisplay.displayNegative

类型：boolean

默认情况下，剩余时间显示为负时间。要不显示负号，请将 controlBar.remainingTimeDisplay.displayNegative 设置为 false。

controls

类型：boolean

确定播放器是否具有用户可交互的控件。如果没有控件，启动视频播放的唯一方法是使用 autoplay 属性或通过播放器 API。

height

类型：string|number

设置视频播放器的显示高度（以像素为单位）。

loop

类型：boolean

使视频在播放结束后立即重新开始。

muted

类型：boolean

默认情况下将静音任何音频。

poster

类型：string

在视频开始播放之前显示的图像的 URL。这通常是视频的一帧或自定义标题画面。用户点击“播放”后，图像将消失。

preload

类型：string

建议浏览器是否应在 <video> 元素加载后立即开始下载视频数据。支持的值有：

'auto'

立即开始加载视频（如果浏览器支持）。一些移动设备不会预加载视频，以保护用户的带宽/数据使用。这就是为什么该值被称为“auto”，而不是更确定的“true”。

这通常是最常见和推荐的值，因为它允许浏览器选择最佳行为。

'metadata'

仅加载视频的元数据，其中包括视频的时长和尺寸等信息。有时，元数据会通过下载几帧视频来加载。

'none'

不预加载任何数据。浏览器将等到用户点击“播放”后才开始下载。

src

类型：string

要嵌入的视频源的 URL。

width

类型：string|number

设置视频播放器的显示宽度（以像素为单位）。

Video.js 特有选项

除非另有说明，否则每个选项默认为 undefined。

aspectRatio

类型：string

将播放器置于流体模式，该值用于计算播放器的动态大小。该值应表示一个比例——由冒号分隔的两个数字（例如，“16:9”或“4:3”）。

或者，可以将类 vjs-16-9、vjs-9-16、vjs-4-3 或 vjs-1-1 添加到播放器。

audioOnlyMode

类型：boolean 默认值：false

如果设置为 true，它会异步隐藏除控制栏之外的所有播放器组件，以及任何仅视频所需的特定控件。此选项可以在运行时通过调用 audioOnlyMode([true|false]) 设置为 true 或 false。当用作设置器时，它返回一个 Promise。当用作获取器时，它返回一个布尔值。

audioPosterMode

类型：boolean 默认值：false

如果设置为 true，它将通过隐藏视频元素并持续显示海报图像来启用海报查看体验。此选项可以在运行时通过调用 audioPosterMode([true|false]) 设置为 true 或 false。

autoSetup

类型：boolean

防止播放器对具有 data-setup 属性的媒体元素运行自动设置。

注意：这必须在与 videojs 源加载的同一计时中通过 videojs.options.autoSetup = false 进行全局设置才能生效。

breakpoints

类型：Object

与responsive 选项一起使用时，设置断点以配置如何在播放器上切换类名，从而根据播放器尺寸调整 UI。

默认情况下，断点为：

类名不能更改，但宽度范围可以通过类似以下的对象进行配置：

breakpoints: {
  tiny: 300,
  xsmall: 400,
  small: 500,
  medium: 600,
  large: 700,
  xlarge: 800,
  huge: 900
}

• breakpoints 对象的键是通过移除 vjs-layout- 前缀和任何 - 字符，从关联的类名中派生出来的。
• breakpoints 对象的值定义了范围的最大宽度。
• 并非所有键都需要定义。您可以轻松地通过传递一个包含一个键/值对的对象来覆盖单个断点！自定义断点将在播放器创建时与默认断点合并。

当播放器大小改变时，将按大小顺序检查合并后的断点，直到找到匹配的断点。

该断点关联的类名将作为类添加到播放器中。上一个断点的类将被移除。

有关使用默认断点的响应式播放器的示例，请参阅文件 sandbox/responsive.html.example。

children

类型：Array|Object

此选项继承自 Component 基类。

disablePictureInPicture

类型：boolean

如果为 true，则禁用将视频元素切换到画中画模式。默认值为 false。

这对于 Firefox 的专有画中画模式没有影响，该模式未实现标准画中画 API。

这不会禁用文档画中画模式，该模式允许播放器元素进入画中画窗口。

enableDocumentPictureInPicture

类型：boolean

自 8.3.0 起

如果为 true，则（如果可用）将使用documentPictureInPicture API 进行画中画。默认值为 false，但当该功能成熟后，可能会默认为 true。

Chrome 和 Edge 116 版本及更高版本支持。

这与以前可用的画中画模式不同，在这种模式下，整个播放器元素都会窗口化，而不仅仅是视频本身。由于存在希望在播放器上允许画中画，但仅在视频上不允许画中画的场景（例如广告、叠加层），因此 disablePictureInPicture 选项仅禁用视频上旧式画中画模式。

enableSmoothSeeking

类型：boolean 默认值：false

自 8.9.0 起

如果设置为 true，将在移动和桌面设备上提供更流畅的定位体验。

以下将启用流畅定位：

videojs('my-player', {
  enableSmoothSeeking: true
});

播放器创建后也可以修改

var player = videojs('my-player');

player.options({ enableSmoothSeeking: true });

experimentalSvgIcons

类型：boolean

自 8.5.0 起

如果设置为 true，播放器中使用的来自videojs/font 的图标将替换为 Video.js 中存储的 SVG。默认值为 false，但当该功能成熟后，可能会默认为 true。

这些 SVG 是从Font Awesome 和Google 的 Material UI 下载的。

您可以通过将 sandbox/svg-icons.html.example 重命名为 sandbox/svg-icons.html，使用 npm run build 构建 Video.js，然后在您选择的浏览器中打开 sandbox/svg-icons.html 来查看所有可用图标。

在自定义播放器时，图标应使用setIcon 方法添加到播放器内部的 Component 中。

fluid

类型：boolean

当为 true 时，Video.js 播放器将具有流体大小。换句话说，它将根据视频的固有宽高比或指定的aspectRatio 缩放以适应其容器。

此外，如果 <video> 元素具有 "vjs-fluid" 类，此选项将自动设置为 true。

fullscreen

类型：Object 默认值：{options: {navigationUI: 'hide'}

fullscreen.options 可以设置为传递特定的全屏选项。在某些时候，它将通过 element 和 handler 进行增强，以提供更多功能。

options

类型：Object 默认值：{navigationUI: 'hide'}

有关更多详细信息，请参阅全屏 API 规范。

id

类型：string

如果提供，并且元素尚无 id，则此值将用作播放器元素的 id。

inactivityTimeout

类型：number

Video.js 通过 "vjs-user-active" 和 "vjs-user-inactive" 类以及 "useractive" 事件来指示用户是否正在与播放器交互。

inactivityTimeout 确定在声明用户不活动之前所需的不活动毫秒数。值为 0 表示没有 inactivityTimeout，用户将永远不会被视为不活动。

language

类型：string，默认值：浏览器默认值或 'en'

与播放器中可用语言之一匹配的语言代码。这设置了播放器的初始语言，但它始终可以更改。

了解更多关于Video.js 中的语言。

languages

类型：Object

自定义播放器中可用的语言。此对象的键将是语言代码，值将是包含英文键和翻译值的对象。

了解更多关于Video.js 中的语言

注意：通常，此选项不是必需的，最好将您的自定义语言传递给 videojs.addLanguage()，以便它们在所有播放器中都可用！

liveui

类型：boolean 默认值：false

允许播放器使用新的直播 UI，包括：

• 在直播窗口内进行定位的进度条
• 一个可点击的按钮，用于跳转到直播前沿，并带有一个圆圈指示您是否处于直播前沿。

如果没有此选项，进度条将隐藏，取而代之的是指示 LIVE 播放的文本。将没有进度控制，并且您将无法点击文本以跳转到直播前沿。liveui 在未来版本中将默认为 true！

liveTracker.trackingThreshold

类型：number 默认值：20

播放器 liveTracker 组件的一个选项，控制何时应显示 liveui。默认情况下，如果流在进度条上少于 20 秒，即使设置了 liveui 选项，我们也不会显示新的 liveui。

liveTracker.liveTolerance

类型：number 默认值：15

播放器 liveTracker 组件的一个选项，控制距离可寻址末尾多远应被视为直播播放。默认情况下，距离直播可寻址边缘超过 15 秒的任何内容都被视为落后于直播，而其他所有内容都被视为直播。用户向后定位的任何交互都将忽略此值，这与用户的预期一致。

nativeControlsForTouch

类型：boolean

明确设置相关技术选项的默认值。

normalizeAutoplay

类型：boolean

指定是否应将 autoplay: true 和 <video autoplay> 的设置与 autoplay: 'play' 视为相同，即 autoplay 属性应从视频元素中移除（或不添加），并且 play() 应由 Video.js 手动启动，而不是由浏览器启动。

notSupportedMessage

类型：string

允许覆盖当 Video.js 无法播放媒体源时显示的默认消息。

noUITitleAttributes

类型：boolean 默认值：false

控制 UI 元素是否具有 title 属性。title 属性在鼠标悬停时显示，有助于可用性，但对可访问性有缺点。将 noUITitleAttributes 设置为 true 可防止 title 属性添加到 UI 元素，从而允许插件或外部框架向控件添加更具可访问性的工具提示。

playbackRates

类型：Array

一个严格大于 0 的数字数组，其中 1 表示正常速度（100%），0.5 表示半速（50%），2 表示双倍速度（200%）等。如果指定，Video.js 将显示一个控件（类名为 vjs-playback-rate），允许用户从选项数组中选择播放速度。选项按指定顺序从下到上显示。

例如：

videojs('my-player', {
  playbackRates: [0.5, 1, 1.5, 2]
});

playsinline

类型：boolean

自 6.1.0 起

指示浏览器，当全屏播放是原生默认行为时（例如在 iOS Safari 中），首选非全屏播放。

例如：

videojs('my-player', {
  playsinline: true
});

plugins

类型：Object

这支持在播放器初始化时自动初始化带有自定义选项的插件，而无需您手动初始化它们。

videojs('my-player', {
  plugins: {
    foo: {bar: true},
    boo: {baz: false}
  }
});

以上大致等同于：

var player = videojs('my-player');

player.foo({bar: true});
player.boo({baz: false});

然而，由于 plugins 选项是一个对象，初始化顺序不保证！

有关 Video.js 插件的更多信息，请参阅插件指南。

posterImage

类型：boolean，默认值：true

将其设置为 false 会移除 Video.js 的海报元素。

preferFullWindow

类型：boolean，默认值：false

将其设置为 true 将改变不支持 HTML5 全屏 API 但支持视频元素全屏的设备上的全屏行为，例如 iPhone。播放器将拉伸以填充浏览器窗口，而不是使视频全屏。

responsive

类型：boolean，默认值：false

将此选项设置为 true 将使播放器根据响应式断点（参见：breakpoints 选项）进行自定义。

当此选项为 false（默认值）时，响应式断点将被忽略。

请注意，这关乎播放器内部控件的响应能力，而非播放器本身的响应式尺寸。要了解后者，请参阅 fluid。

restoreEl

类型：boolean 或 Element，默认值：false

如果设置为 true，则在播放器初始化之前会创建占位符元素的**副本**。如果播放器被销毁，该副本将被放回 DOM 中，替代播放器的位置。

如果设置为 HTML 元素，则该元素将替代已销毁的播放器。

skipButtons

类型：Object

自 8.2.0 起

skipButtons.forward

类型：number

自 8.2.0 起

如果指定，Video.js 将显示一个控件，允许用户在视频中向前跳转指定秒数。

以下值有效：5 | 10 | 30

videojs('my-player', {
  controlBar: {
    skipButtons: {
      forward: 5
    }
  }
});

skipButtons.backward

类型：number

自 8.2.0 起

如果指定，Video.js 将显示一个控件，允许用户在视频中向后跳转指定秒数。

以下值有效：5 | 10 | 30

videojs('my-player', {
  controlBar: {
    skipButtons: {
      backward: 10
    }
  }
});

sources

类型：Array

一个对象数组，镜像原生 <video> 元素具有一系列子 <source> 元素的能力。这应该是一个包含 src 和 type 属性的对象数组。例如：

videojs('my-player', {
  sources: [{
    src: '//path/to/video.mp4',
    type: 'video/mp4'
  }, {
    src: '//path/to/video.webm',
    type: 'video/webm'
  }]
});

使用 <source> 元素将产生相同的效果：

<video ...>
  <source src="//path/to/video.mp4" type="video/mp4">
  <source src="//path/to/video.webm" type="video/webm">
</video>

suppressNotSupportedError

类型：boolean

如果设置为 true，则不兼容源错误将不会立即触发，而是在第一次用户交互时发生。这对于 Google 的“移动友好”测试工具很有用，该工具无法播放视频，但您可能不希望显示错误。

techCanOverridePoster

类型：boolean

使技术能够覆盖播放器的海报并集成到播放器的海报生命周期中。当使用多种技术且每种技术都必须在播放新源时设置自己的海报时，这会很有用。

techOrder

类型：Array，默认值：['html5']

定义 Video.js 技术偏好顺序。默认情况下，这意味着 Html5 技术是首选。其他注册的技术将在此技术之后按注册顺序添加。

userActions

类型：Object

userActions.click

类型：boolean|function

控制点击播放器/技术的操作方式。如果设置为 false，则禁用点击，并且不会再导致播放器在暂停和播放之间切换。如果通过 controls: false 禁用控件，则不会调用处理函数。

videojs('my-player', {
  userActions: {
    click: false
  }
});

如果未定义或设置为 true，则启用点击并使播放器在暂停和播放之间切换。要覆盖默认点击处理，请将 userActions.click 设置为一个接受 click 事件的函数（在此示例中，它将请求全屏，与 userActions.doubleClick 相同）。

function myClickHandler(event) = {
  // `this` is the player in this context

  if (this.isFullscreen()) {
      this.exitFullscreen();
    } else {
      this.requestFullscreen();
    }
};

videojs('my-player', {
  userActions: {
    click: myClickHandler
  }
});

userActions.doubleClick

类型：boolean|function

控制双击播放器/技术的操作方式。如果设置为 false，则禁用双击。如果未定义或设置为 true，则启用双击并切换全屏模式。要覆盖默认双击处理，请将 userActions.doubleClick 设置为一个接受 dblclick 事件的函数。

function myDoubleClickHandler(event) = {
  // `this` is the player in this context

  this.pause();
};

videojs('my-player', {
  userActions: {
    doubleClick: myDoubleClickHandler
  }
});

userActions.hotkeys

类型： boolean|function|object

控制播放器范围的热键操作。如果设置为false或undefined，热键将被禁用。如果设置为true或一个对象（以允许在下方定义fullscreenKey等），热键将按如下所述启用。要覆盖默认的热键处理，请将userActions.hotkeys设置为一个接受keydown事件的函数。如果控件通过controls: false被禁用，则不会调用处理函数。

var player = videojs('my-player', {
  userActions: {
    hotkeys: function(event) {
      // `this` is the player in this context

      // `x` key = pause
      if (event.which === 88) {
        this.pause();
      }
      // `y` key = play
      if (event.which === 89) {
        this.play();
      }
    }
  }
});

默认热键处理如下：

热键首先需要播放器获得焦点。请注意，如果控件（例如按钮和菜单）具有键盘焦点，则Space键会激活该控件。其他热键无论播放器中哪个控件有焦点都有效。

userActions.hotkeys.fullscreenKey

类型： function

覆盖全屏键定义。如果此项已设置，函数将接收keydown事件；如果函数返回true，则执行全屏切换操作。

var player = videojs('my-player', {
  userActions: {
    hotkeys: {
      muteKey: function(event) {
        // disable mute key
      },
      fullscreenKey: function(event) {
        // override fullscreen to trigger when pressing the v key
        return (event.which === 86);
      }
    }
  }
});

userActions.hotkeys.muteKey

类型： function

覆盖静音键定义。如果此项已设置，函数将接收keydown事件；如果函数返回true，则执行静音切换操作。

userActions.hotkeys.playPauseKey

类型： function

覆盖播放/暂停键定义。如果此项已设置，函数将接收keydown事件；如果函数返回true，则执行播放/暂停切换操作。

vtt.js

类型：string

允许覆盖vtt.js的默认URL，该文件可能会异步加载以填充WebVTT支持。

此选项将在Video.js的“novtt”构建版本（即video.novtt.js）中使用。否则，vtt.js将与Video.js捆绑在一起。

空间导航

spatialNavigation

类型： Object 默认值： {enabled: false, horizontalSeek: false}

此选项配置Video.js播放器中的空间导航，增强智能电视等设备上的辅助功能和用户体验，在这些设备上通过遥控器导航很常见。

属性

• enabled 类型： boolean 默认值： false 如果设置为true，则启用播放器中的空间导航系统，允许用户使用遥控器上的方向键浏览可聚焦组件。

• horizontalSeek 类型： boolean 默认值： false 启用后，用户可以使用左右方向键在视频时间轴中进行快进/快退，从而提升导航体验。

用法

使用默认设置启用空间导航

var player = videojs('my-player', {
  spatialNavigation: {
    enabled: true
  }
});

启用带有水平快进/快退的空间导航

var player = videojs('my-player', {
  spatialNavigation: {
    enabled: true,
    horizontalSeek: true
  }
});

组件选项

Video.js播放器是一个组件。与所有组件一样，您可以定义它包含哪些子组件、它们的显示顺序以及传递给它们的选项。

这旨在作为快速参考；因此，有关Video.js中组件的更多详细信息，请查看组件指南。

children

类型：Array|Object

如果是一个Array（这是默认值），则用于确定在播放器（或其他组件）上创建哪些子组件（按组件名称）以及它们的创建顺序。

// The following code creates a player with ONLY bigPlayButton and
// controlBar child components.
videojs('my-player', {
  children: [
    'bigPlayButton',
    'controlBar'
  ]
});

children选项也可以作为Object传递。在这种情况下，它用于为任何/所有子组件提供options，包括通过false禁用它们。

// This player's ONLY child will be the controlBar. Clearly, this is not the
// ideal method for disabling a grandchild!
videojs('my-player', {
  children: {
    controlBar: {
      fullscreenToggle: false
    }
  }
});

${componentName}

类型：Object

组件可以通过组件名称的小驼峰命名变体（例如，ControlBar对应controlBar）来获得自定义选项。这些选项可以嵌套以表示孙子关系。例如，要禁用全屏控制：

videojs('my-player', {
  controlBar: {
    fullscreenToggle: false
  }
});

技术选项

${techName}

类型：Object

Video.js播放技术（即“techs”）可以作为传递给videojs函数的选项的一部分，获得自定义选项。它们应该在技术名称的小写变体下传递（例如，"html5"）。

html5

nativeControlsForTouch

类型：boolean

仅受Html5技术支持，此选项可以设置为true，以强制触控设备使用原生控件。

nativeAudioTracks

类型：boolean

可以设置为false以禁用原生音轨支持。最常与videojs-contrib-hls一起使用。

nativeTextTracks

类型：boolean

可以设置为false以强制模拟文本轨道而非使用原生支持。nativeCaptions选项也存在，但它只是nativeTextTracks的一个别名。

nativeVideoTracks

类型：boolean

可以设置为false以禁用原生视频轨道支持。最常与videojs-contrib-hls一起使用。

preloadTextTracks

类型：boolean

可以设置为false以延迟加载非活动文本轨道，直到使用时再加载。这可能会导致在切换字幕时出现短暂延迟，期间可能会有字幕缺失。

默认行为是预加载所有文本轨道。