Video.js 选项参考

注意：本文档仅提供可用选项的参考。要了解如何向 Video.js 传递选项，请参阅“Video.js 设置属性”。

标准 < video> 元素选项

这些选项中的每一个也可作为标准 <video> 元素属性使用；因此，可以用设置指南中概述的所有三种方式来定义它们。通常情况下，默认值不会列出，因为这是由浏览器供应商决定的。

autoplay

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

您应向 videojs 函数传递一个自动播放选项，而不是使用自动播放属性。以下值均有效：

• 布尔值为 false：与视频元素上没有属性相同，不会自动播放

• 布尔值为 true：与视频元素上有属性相同，将使用浏览器自动播放

• 字符串值 "muted"：将视频元素静音，然后在加载开始时手动调用 play()，这很可能有效。

• 字符串值为 "play"：将在 loadstart 时调用 play()，类似于浏览器的自动播放功能。

• 字符串值为 "any"：将在 loadstart 时调用 play()，如果承诺被拒绝，将使视频元素静音，然后调用 play()。

要传递选项

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

// or

player.autoplay('muted');

公共广告位-前端

controlBar.remainingTimeDisplay.displayNegative

类型：boolean

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

controls

类型：boolean

确定播放器是否有用户可以进行交互的控件。如果没有控件，开始播放视频的唯一方法就是使用自动播放属性或通过播放器 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 特殊选项

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

aspectRatio

类型：string

将播放器设置为流体模式，该值用于计算播放器的动态尺寸。该值应代表一个比例 - 用冒号分隔的两个数字（如 "16:9 "或 "4:3"）。

或者，也可以在播放器中添加名为 vjs-16-9、vjs-9-16、vjs-4-3 或 vjs-1-1 的 class。

audioOnlyMode

类型：boolean

默认值：false

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

audioPosterMode

类型：boolean

默认：false

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

autoSetup

类型：boolean

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

注意：必须在加载 videojs 源的同一个 tick 中使用 videojs.options.autoSetup = false 全局设置才能生效。

breakpoints

类型：Object

与响应式选项一起使用时，可设置断点，以配置如何在播放器上切换类名，从而根据播放器的尺寸调整用户界面。

默认情况下，断点为：

虽然不能更改 class 名，但可以通过类似这样的对象来配置宽度范围：

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

• 去掉 vjs-layout- 前缀和任何"-"字符后，breakpoints 对象的键是从相关 class 名派生出来的。

• breakpoints 对象的值定义了范围的最大宽度。

• 并非所有键都需要定义。您可以通过传递包含一个键/值对的对象，轻松覆盖单个断点！创建播放器时，自定义断点将与默认断点合并。

当播放器的大小发生变化时，合并的断点将按照大小顺序进行检查，直到找到匹配的断点。

该断点的相关 class 名将作为一个 class 添加到播放器中。之前断点的 class 将被移除。

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

children

类型：Array|Object

该选项继承自 Component 基类。

disablePictureInPicture

类型：boolean

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

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

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

enableDocumentPictureInPicture

类型：boolean

自 8.3.0 起

如果为 "true"，则将使用 documentPictureInPicture API（如果可用）实现画中画。默认为 false，但当该功能建立后，默认值可能会变为 true。

目前，Chrome 浏览器 111+ 提供了该功能的试用版。

这种画中画模式与以前的模式不同，在这种模式下，整个播放器元素都是窗口化的，而不仅仅是视频本身。在某些情况下，允许在播放器上画中画而不允许仅在视频上画中画（如广告、叠加），因此 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。

这些 SVGs 下载自 Font Awesome 和 Google 的 Material UI。

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

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

fluid

类型：boolean

为 true 时，Video.js 播放器的尺寸将是流动的。换句话说，它将按照视频固有的宽高比或指定的宽高比缩放以适应其容器。

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

fullscreen

类型：Object

默认：{options: {navigationUI: 'hide'}

fullscreen.options 可用于传递特定的全屏选项。在某些情况下，它将与元素和处理程序一起增强更多功能。

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 中语言的更多信息（https://videojs.com/guides/languages/）。

languages

类型：Object

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

了解有关 Video.js 中语言的更多信息（https://videojs.com/guides/languages）

注意：一般情况下不需要此选项，最好将自定义语言传递给 videojs.addLanguage()，这样所有播放器都能使用这些语言！

liveui

类型：boolean

默认：false

允许播放器使用新的实时界面，其中包括：

• 用于在实时窗口内寻路的进度条

• 一个按钮，点击后会显示一个圆圈，表示是否在实时边缘。

如果没有该选项，进度条将被隐藏，取而代之的是表示实时播放的文字。在未来版本中，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 属性，并由 Video.js 而不是浏览器手动启动 play()。

公共广告位-前端

notSupportedMessage

类型：string

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

noUITitleAttributes

类型：boolean

默认：false

控制用户界面元素是否有 title 属性。title 属性会在鼠标悬停时显示，这对可用性很有帮助，但对可访问性有不利影响。将 noUITitleAttributes 设置为 true 可以防止在 UI 元素中添加 title 属性，从而允许插件或外部框架在控件中添加更易于访问的工具提示。

playbackRates

类型：Array

必须大于 0 的数字数组，其中 1 表示正常速度（100%），0.5 表示半速（50%），2 表示双速（200%）等。如果指定了该数组，Video.js 将显示一个控件（class 为 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 插件的更多信息，请参阅插件指南。

preferFullWindow

类型：boolean

默认：false

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

responsive

类型：boolean

默认：false

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

如果该选项为 false（默认值），响应式断点将被忽略。

请注意，这是指播放器内控件的响应速度，而不是播放器本身的响应大小。关于这一点，请参阅流体。

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，则不会立即触发 "无兼容源" 错误，而会在第一次用户交互时发生。这对于谷歌的 "移动友好（mobile friendly）" 测试工具非常有用，因为该工具无法播放视频，但您可能不希望看到显示错误。

公共广告位-前端

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 或未定义，热键将被禁用。如果设置为 true 或一个对象（以便在下文中定义 fullscreenKey 等），热键将按下文所述启用。要覆盖默认的热键处理方式，可将 userActions.hotkeys 设置为可接受按键事件的函数。如果使用 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();
      }
    }
  }
});

默认热键处理方式为：

热键首先需要获取播放器焦点。请注意，如果按钮和菜单等控件的键盘焦点在空格键上，则空格键会激活这些控件。其他热键的作用与播放器中哪个控件有焦点无关。

公共广告位-前端

userActions.hotkeys.fullscreenKey

类型：function

覆盖全屏键定义。如果设置为 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

覆盖静音键定义。如果设置为 true，则执行静音切换操作。

userActions.hotkeys.playPauseKey

类型：function

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

vtt.js

类型：string

允许覆盖 vtt.js 的默认 URL，该 URL 可异步加载，以聚合对 WebVTT 的支持。

此选项将用于 Video.js 的 "novtt" 构建（即 video.novtt.js）。否则，vtt.js 将与 Video.js 捆绑。

组件选项

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

本文仅供快速参考，有关 Video.js 中组件的更多详细信息，请查看组件指南。

children

类型 Array|Object

如果是 Arrau（默认值），则用于确定在播放器（或其他组件）上创建哪些子节点（按组件名称）以及创建的顺序：

// 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 回放技术（即 "技术"）可作为传递给 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，以延迟加载非活动文本轨道，直到使用为止。这可能会在切换字幕时造成短暂的延迟，在此期间可能会出现字幕缺失的情况。