点击下载教程相关资源
注意:本文档仅提供可用选项的参考。要了解如何向 Video.js 传递选项,请参阅“Video.js 设置属性”。
这些选项中的每一个也可作为标准 <video> 元素属性使用;因此,可以用设置指南中概述的所有三种方式来定义它们。通常情况下,默认值不会列出,因为这是由浏览器供应商决定的。
类型: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');
类型:boolean
默认情况下,剩余时间显示为负数。要不显示负号,请将 controlBar.remainingTimeDisplay.displayNegative 设为 false。
类型:boolean
确定播放器是否有用户可以进行交互的控件。如果没有控件,开始播放视频的唯一方法就是使用自动播放属性或通过播放器 API。
类型:string|number
以像素为单位设置视频播放器的显示高度。
类型:boolean
循环播放,使视频结束后立即重新开始。
类型:boolean
默认情况下将静音。
类型:string
视频开始播放前显示的图像的 URL。通常是视频的一帧或自定义标题屏幕。一旦用户点击 "播放",图片就会消失。
类型:string
向浏览器建议是否应在加载 <video> 元素后立即开始下载视频数据。支持的值有:
'auto'
立即开始加载视频(如果浏览器支持)。有些移动设备为了保护用户的带宽/数据使用,不会预先加载视频。这就是为什么该值被称为 "auto",而不是 "true" 这样更明确的值。
这往往是最常见和最推荐的值,因为它允许浏览器选择最佳行为。
'metadata'
只加载视频的元数据,包括视频的时长和尺寸等信息。有时,元数据会通过下载几帧视频来加载。
'none'
不预载任何数据。浏览器会等到用户点击 "播放 "时才开始下载。
类型:string
要嵌入的视频源的源 URL。
类型:string|number
以像素为单位设置视频播放器的显示宽度。
除非另有说明,否则每个选项默认为未定义。
类型:string
将播放器设置为流体模式,该值用于计算播放器的动态尺寸。该值应代表一个比例 - 用冒号分隔的两个数字(如 "16:9 "或 "4:3")。
或者,也可以在播放器中添加名为 vjs-16-9、vjs-9-16、vjs-4-3 或 vjs-1-1 的 class。
类型:boolean
默认值:false
如果设置为 true,则会异步隐藏除控制栏以外的所有播放器组件,以及仅在视频时才需要的任何特定控件。该选项可在运行时调用 audioOnlyMode([true|false]) 设置为 true 或 false。当作为设置器使用时,它会返回一个 Promise。当用作 getter 时,它返回一个布尔值。
类型:boolean
默认:false
如果设置为 "true",则会通过隐藏视频元素和持续显示海报图像来启用海报查看器体验。该选项可通过在运行时调用 audioPosterMode([true|false]) 设置为 true 或 false。
类型:boolean
防止播放器为带有 data-setup 属性的媒体元素运行自动设置。
注意:必须在加载 videojs 源的同一个 tick 中使用 videojs.options.autoSetup = false 全局设置才能生效。
类型: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,了解使用默认断点的响应式播放器示例。
类型:Array|Object
该选项继承自 Component 基类。
类型:boolean
如果为 true,则禁用将视频元素切换为画中画。默认为 false。
这对 Firefox 没有影响,因为 Firefox 实现的专有画中画模式没有实现标准的画中画 API。
这不会禁用允许播放器元素进入画中画窗口的文档画中画模式。
类型:boolean
自 8.3.0 起
如果为 "true",则将使用 documentPictureInPicture API(如果可用)实现画中画。默认为 false,但当该功能建立后,默认值可能会变为 true。
目前,Chrome 浏览器 111+ 提供了该功能的试用版。
这种画中画模式与以前的模式不同,在这种模式下,整个播放器元素都是窗口化的,而不仅仅是视频本身。在某些情况下,允许在播放器上画中画而不允许仅在视频上画中画(如广告、叠加),因此 disablePictureInPicture 选项仅禁用视频上的旧式画中画模式。
类型:boolean
默认:false
自 8.9.0 起
如果设置为 true,将在移动和桌面设备上提供更流畅的搜索体验。
以下操作将启用平滑搜索:
videojs('my-player', { enableSmoothSeeking: true });
也可在创建播放器后进行修改:
var player = videojs('my-player'); player.options({ enableSmoothSeeking: true });
类型: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 方法添加到播放器内部的组件中。
类型:boolean
为 true 时,Video.js 播放器的尺寸将是流动的。换句话说,它将按照视频固有的宽高比或指定的宽高比缩放以适应其容器。
此外,如果 <video> 元素具有 "vjs-fluid",此选项将自动设为 true。
类型:Object
默认:{options: {navigationUI: 'hide'}
fullscreen.options 可用于传递特定的全屏选项。在某些情况下,它将与元素和处理程序一起增强更多功能。
options
类型:Object
默认:{navigationUI: 'hide'}
更多详情,请参阅全屏 API 规范。
id
类型:string
如果提供,且元素还没有 id,则此值将用作播放器元素的 id。
类型:number
Video.js 通过 "vjs-user-active" 和 "vjs-user-inactive" 类以及 "useractive" 事件来表示用户正在与播放器交互。
不活动超时(inactivityTimeout)决定了在宣布用户不活动之前需要多少毫秒的不活动时间。值为 0 表示没有 inactivityTimeout,用户永远不会被视为不活动。
类型:string
默认:浏览器默认语言或 "en
与播放器中可用语言之一相匹配的语言代码。这将设置播放器的初始语言,但可以随时更改。
了解有关 Video.js 中语言的更多信息(https://videojs.com/guides/languages/)。
类型:Object
自定义播放器中可用的语言。该对象的键将是语言代码,值将是具有英文键和翻译值的对象。
了解有关 Video.js 中语言的更多信息(https://videojs.com/guides/languages)
注意:一般情况下不需要此选项,最好将自定义语言传递给 videojs.addLanguage(),这样所有播放器都能使用这些语言!
类型:boolean
默认:false
允许播放器使用新的实时界面,其中包括:
用于在实时窗口内寻路的进度条
一个按钮,点击后会显示一个圆圈,表示是否在实时边缘。
如果没有该选项,进度条将被隐藏,取而代之的是表示实时播放的文字。在未来版本中,liveui 将默认为 true!
类型:number
默认:20
播放器 liveTracker 组件的一个选项,用于控制何时显示 liveui。默认情况下,如果流媒体的寻道时间少于 20 秒,那么即使设置了 liveui 选项,我们也不会显示新的 liveui。
类型:number
默认:15
播放器 liveTracker 组件的一个选项,用于控制距离可寻址端多远的内容应被视为实时播放。默认情况下,距离实时搜索边缘超过 15 秒的内容将被视为落后于实时内容,而其他内容则被视为实时内容。任何向后搜索的用户交互都将忽略该值,正如用户所期望的那样。
类型:boolean
明确设置相关技术选项的默认值。
类型:boolean
指定是否应将设置 autoplay:true 和 <video autoplay> 与设置 autoplay:'play'(自动播放)同等对待,也就是说,应从视频元素中移除(或不添加)autoplay 属性,并由 Video.js 而不是浏览器手动启动 play()。
类型:string
允许覆盖 Video.js 无法播放媒体源时显示的默认信息。
类型:boolean
默认:false
控制用户界面元素是否有 title 属性。title 属性会在鼠标悬停时显示,这对可用性很有帮助,但对可访问性有不利影响。将 noUITitleAttributes 设置为 true 可以防止在 UI 元素中添加 title 属性,从而允许插件或外部框架在控件中添加更易于访问的工具提示。
类型: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] });
类型:boolean
自 6.1.0 起
当全屏播放是本机默认设置(如在 iOS Safari 中)时,用于指示浏览器优先选择非全屏播放。
例如:
videojs('my-player', { playsinline: true });
类型: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 插件的更多信息,请参阅插件指南。
类型:boolean
默认:false
将此设置为 true 将改变不支持 HTML5 全屏 API 但支持视频元素全屏的设备(如 iPhone)上的全屏行为。播放器将被拉伸以填充浏览器窗口,而不是使视频全屏。
类型:boolean
默认:false
将此选项设置为 true,播放器将根据响应式断点(参见:断点选项)进行自定义。
如果该选项为 false(默认值),响应式断点将被忽略。
请注意,这是指播放器内控件的响应速度,而不是播放器本身的响应大小。关于这一点,请参阅流体。
类型:boolean 或 Element
默认:false
如果设置为 true,将在播放器启动前复制占位符元素。如果播放器被弃置,该副本将放回 DOM,取代播放器的位置。
如果设置为 HTML 元素,则该元素将取代被弃置的播放器。
类型:Object
自 8.2.0 起
类型:number
自 8.2.0 起
如果指定,Video.js 将显示一个控件,允许用户在视频中向前跳转指定的秒数。
以下值均有效: 5 | 10 | 30
videojs('my-player', { controlBar: { skipButtons: { forward: 5 } } });
类型:number
自 8.2.0 起
如果指定了该值,Video.js 将显示一个控件,允许用户按指定秒数跳回视频。
以下数值有效: 5 | 10 | 30
videojs('my-player', { controlBar: { skipButtons: { backward: 10 } } });
类型: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>
类型:boolean
如果设置为 true,则不会立即触发 "无兼容源" 错误,而会在第一次用户交互时发生。这对于谷歌的 "移动友好(mobile friendly)" 测试工具非常有用,因为该工具无法播放视频,但您可能不希望看到显示错误。
类型:boolean
允许技术覆盖播放器的海报,并融入播放器的海报生命周期。当使用多个技术时,每个技术都必须在播放新信号源时设置自己的海报,这一点非常有用。
类型: Array
默认:['html5']
定义优先使用 Video.js 技术的顺序。默认情况下,优先使用 Html5 技术。其他已注册的技术将按照注册顺序添加到该技术之后。
类型: Object
类型: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 } });
类型: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 } });
类型: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 | 切换播放/暂停 | 始终启用,即使没有控制栏也是如此 |
空格 | 切换播放/暂停 | 始终启用,即使没有控制栏也是如此 |
热键首先需要获取播放器焦点。请注意,如果按钮和菜单等控件的键盘焦点在空格键上,则空格键会激活这些控件。其他热键的作用与播放器中哪个控件有焦点无关。
类型: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); } } } });
类型:function
覆盖静音键定义。如果设置为 true,则执行静音切换操作。
类型:function
覆盖播放/暂停键定义。如果设置了该值,函数将接收 keydown 事件;如果函数返回true,则执行播放/暂停切换操作。
类型:string
允许覆盖 vtt.js 的默认 URL,该 URL 可异步加载,以聚合对 WebVTT 的支持。
此选项将用于 Video.js 的 "novtt" 构建(即 video.novtt.js)。否则,vtt.js 将与 Video.js 捆绑。
Video.js 播放器是一个组件。与所有组件一样,您可以定义它包括哪些子组件、它们的显示顺序以及传递给它们的选项。
本文仅供快速参考,有关 Video.js 中组件的更多详细信息,请查看组件指南。
类型 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 } } });
类型:Object
可通过组件名称的小写字母变体(小写驼峰命名)为组件提供自定义选项(例如,controlBar 表示 ControlBar)。这些选项可以嵌套在子代关系中。例如,禁用全屏控件:
videojs('my-player', { controlBar: { fullscreenToggle: false } });
类型:Object
Video.js 回放技术(即 "技术")可作为传递给 videojs 函数的选项的一部分赋予自定义选项。这些选项应在技术名称的小写变体(如 "html5")下传递。
类型:boolean
该选项仅受 Html5 技术的支持,可设置为 true 以强制使用触摸设备的本地控件。
类型:boolean
可设置为 false 以禁用原生音轨支持。最常用于videojs-contrib-hls。
类型:boolean
可设置为 false,以强制模拟文本轨迹,而非本地支持。nativeCaptions 选项也存在,但只是 nativeTextTracks 的别名。
类型:boolean
可设置为 false 以禁用本地视频轨道支持。最常用于videojs-contrib-hls。
类型:boolean
可设置为 false,以延迟加载非活动文本轨道,直到使用为止。这可能会在切换字幕时造成短暂的延迟,在此期间可能会出现字幕缺失的情况。