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名称

宽度范围

vjs-layout-tiny

0-210

vjs-layout-x-small

211-320

vjs-layout-small

321-425

vjs-layout-medium

426-768

vjs-layout-large

769-1440

vjs-layout-x-large

1441-2560

vjs-layout-huge

2561+

虽然不能更改 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();
      }
    }
  }
});

默认热键处理方式为:

快捷键

动作

启用

f

切换全屏

仅当控制栏中有全屏按钮时才启用

m

切换静音

始终启用,即使没有控制栏也是如此

k

切换播放/暂停

始终启用,即使没有控制栏也是如此

空格

切换播放/暂停

始终启用,即使没有控制栏也是如此

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

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,以延迟加载非活动文本轨道,直到使用为止。这可能会在切换字幕时造成短暂的延迟,在此期间可能会出现字幕缺失的情况。

说说我的看法
全部评论(
没有评论
关于
本网站专注于 Java、数据库(MySQL、Oracle)、Linux、软件架构及大数据等多领域技术知识分享。涵盖丰富的原创与精选技术文章,助力技术传播与交流。无论是技术新手渴望入门,还是资深开发者寻求进阶,这里都能为您提供深度见解与实用经验,让复杂编码变得轻松易懂,携手共赴技术提升新高度。如有侵权,请来信告知:hxstrive@outlook.com
公众号