基础选项 Permalink to "基础选项"
container Permalink to "`container`"
- Type:
String, Element - Default:
#artplayer
播放器挂载的 DOM 容器
var art = new Artplayer({
container: '.artplayer-app',
// container: document.querySelector('.artplayer-app'),
url: '/assets/sample/video.mp4',
});
您可能需要初始化容器元素的大小,如:
.artplayer-app {
width: 400px;
height: 300px;
}
或者使用 aspect-ratio:
.artplayer-app {
aspect-ratio: 16/9;
}
提示
全部选项里,只有 container 是必填的
url Permalink to "`url`"
- Type:
String - Default:
''
视频源地址
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
有时候 url 地址没那么快知道,这时候你可以异步设置 url
var art = new Artplayer({
container: '.artplayer-app',
});
setTimeout(() => {
art.url = '/assets/sample/video.mp4';
}, 1000);
提示
默认支持三种视频文件格式:.mp4, .ogg, .webm
如需要播放 .m3u8 或者 .flv 等其它格式,请参考左侧的 第三方库
id Permalink to "`id`"
- Type:
String - Default:
''
播放器的唯一标识,目前只用于记忆播放 autoplayback
var art = new Artplayer({
id: 'your-url-id',
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
});
onReady Permalink to "`onReady`"
- Type:
Function - Default:
undefined
构造函数接受一个函数作为第二个参数,播放器初始化成功且视频可以播放时触发,和ready事件一样
var art = new Artplayer(
{
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
muted: true,
},
function onReady(art) {
this.play()
},
);
等同于:
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
muted: true,
});
art.on('ready', () => {
art.play();
});
提示
回调函数里的this就是播放器实例,但回调函数假如使用了箭头函数,this则不会指向播放器实例
poster Permalink to "`poster`"
- Type:
String - Default:
''
视频的海报,只会出现在播放器初始化且未播放的状态下
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
poster: '/assets/sample/poster.jpg',
});
theme Permalink to "`theme`"
- Type:
String - Default:
#f00
播放器主题颜色,目前用于 进度条 和 高亮元素 上
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
theme: '#ffad00',
});
volume Permalink to "`volume`"
- Type:
Number - Default:
0.7
播放器的默认音量
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
volume: 0.5,
});
提示
播放器会缓存最后一次音量的大小,下次初始化时(如刷新页面)播放器会读取该缓存值
isLive Permalink to "`isLive`"
- Type:
Boolean - Default:
false
使用直播模式,会隐藏进度条和播放时间
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
isLive: true,
});
muted Permalink to "`muted`"
- Type:
Boolean - Default:
false
是否默认静音
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
muted: true,
});
autoplay Permalink to "`autoplay`"
- Type:
Boolean - Default:
false
是否自动播放
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
autoplay: true,
muted: true,
});
提示
假如希望默认进入页面就能自动播放视频,muted 必需为 true,更多信息请阅读 Autoplay Policy Changes
autoSize Permalink to "`autoSize`"
- Type:
Boolean - Default:
false
播放器的尺寸默认会填充整个 container 容器尺寸,所以经常出现黑边,该值能自动调整播放器尺寸以隐藏黑边,类似 css 的 object-fit: cover;
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
autoSize: true,
});
autoMini Permalink to "`autoMini`"
- Type:
Boolean - Default:
false
当播放器滚动到浏览器视口以外时,自动进入 迷你播放 模式
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
autoMini: true,
});
loop Permalink to "`loop`"
- Type:
Boolean - Default:
false
是否循环播放
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
loop: true,
});
flip Permalink to "`flip`"
- Type:
Boolean - Default:
false
是否显示视频翻转功能,目前只出现在 设置面板 和 右键菜单 里
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
flip: true,
setting: true,
});
playbackRate Permalink to "`playbackRate`"
- Type:
Boolean - Default:
false
是否显示视频播放速度功能,会出现在 设置面板 和 右键菜单 里
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
playbackRate: true,
setting: true,
});
aspectRatio Permalink to "`aspectRatio`"
- Type:
Boolean - Default:
false
是否显示视频长宽比功能,会出现在 设置面板 和 右键菜单 里
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
aspectRatio: true,
setting: true,
});
screenshot Permalink to "`screenshot`"
- Type:
Boolean - Default:
false
是否在底部控制栏里显示 视频截图 功能
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
screenshot: true,
});
提示
由于浏览器安全机制,假如视频源地址和网站是跨域的,可能会出现截图失败
setting Permalink to "`setting`"
- Type:
Boolean - Default:
false
是否在底部控制栏里显示 设置面板 的开关按钮
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
setting: true,
});
hotkey Permalink to "`hotkey`"
- Type:
Boolean - Default:
true
是否使用快捷键
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
hotkey: true,
});
| 热键 | 描述 |
|---|---|
↑ |
增加音量 |
↓ |
降低音量 |
← |
视频快进 |
→ |
视频快退 |
space |
切换播放/暂停 |
提示
只在播放器获得焦点后(如点击了播放器后),这些快捷键才会生效
pip Permalink to "`pip`"
- Type:
Boolean - Default:
false
是否在底部控制栏里显示 画中画 的开关按钮
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
pip: true,
});
mutex Permalink to "`mutex`"
- Type:
Boolean - Default:
true
假如页面里同时存在多个播放器,是否只能让一个播放器播放
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
mutex: true,
});
backdrop Permalink to "`backdrop`"
- Type:
Boolean - Default:
true
是否开启播放器 UI 的背景虚化效果。开启后,设置面板、右键菜单、音量条等浮层会应用 backdrop-filter 毛玻璃效果,看起来更通透,但在部分低性能设备或老旧浏览器上可能会有性能或兼容性问题。
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
backdrop: false, // 关闭毛玻璃效果
});
fullscreen Permalink to "`fullscreen`"
- Type:
Boolean - Default:
false
是否在底部控制栏里显示播放器 窗口全屏 按钮
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
fullscreen: true,
});
fullscreenWeb Permalink to "`fullscreenWeb`"
- Type:
Boolean - Default:
false
是否在底部控制栏里显示播放器 网页全屏 按钮
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
fullscreenWeb: true,
});
subtitleOffset Permalink to "`subtitleOffset`"
- Type:
Boolean - Default:
false
字幕时间偏移,范围在 [-5s, 5s],出现在 设置面板 里
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
subtitleOffset: true,
subtitle: {
url: '/assets/sample/subtitle.srt',
},
setting: true,
});
miniProgressBar Permalink to "`miniProgressBar`"
- Type:
Boolean - Default:
false
迷你进度条,只在播放器失去焦点后且正在播放时出现
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
miniProgressBar: true,
});
useSSR Permalink to "`useSSR`"
- Type:
Boolean - Default:
false
是否使用 SSR 挂载模式,假如你希望在播放器挂载前,就提前渲染好播放器所需的 HTML 时有用
你可以通过 Artplayer.html 访问到播放器所需的 HTML
var $container = document.querySelector('.artplayer-app');
$container.innerHTML = Artplayer.html;
var art = new Artplayer({
container: $container,
url: '/assets/sample/video.mp4',
useSSR: true,
});
playsInline Permalink to "`playsInline`"
- Type:
Boolean - Default:
true
在移动端是否使用 playsInline 模式
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
playsInline: true,
});
layers Permalink to "`layers`"
- Type:
Array - Default:
[]
初始化自定义的 层
var img = '/assets/sample/layer.png';
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
layers: [
{
name: 'potser',
html: `<img style="width: 100px" src="${img}">`,
style: {
position: 'absolute',
top: '20px',
right: '20px',
opacity: '.9',
},
click: function (...args) {
console.info('click', args);
art.layers.show = false;
},
mounted: function (...args) {
console.info('mounted', args);
},
},
],
});
组件配置 请参考以下地址:
settings Permalink to "`settings`"
- Type:
Array - Default:
[]
初始化自定义的 设置面板
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
setting: true,
settings: [
{
html: 'setting01',
selector: [
{
html: 'setting01-01',
},
{
html: 'setting01-02',
},
],
onSelect: function (...args) {
console.info(args);
},
},
{
html: 'setting02',
selector: [
{
html: 'setting02-01',
},
{
html: 'setting02-02',
},
],
onSelect: function (...args) {
console.info(args);
},
},
],
});
设置面板 请参考以下地址
contextmenu Permalink to "`contextmenu`"
- Type:
Array - Default:
[]
初始化自定义的 右键菜单
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
contextmenu: [
{
html: 'your-menu',
click: function (...args) {
console.info('click', args);
art.contextmenu.show = false;
},
},
],
});
组件配置 请参考以下地址:
controls Permalink to "`controls`"
- Type:
Array - Default:
[]
初始化自定义的底部 控制栏
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
controls: [
{
position: 'left',
html: 'your-control',
tooltip: 'Your Control',
style: {
color: 'green',
},
click: function (...args) {
console.info('click', args);
},
},
],
});
组件配置 请参考以下地址:
quality Permalink to "`quality`"
- Type:
Array - Default:
[]
是否在底部控制栏里显示 画质选择 列表
| 属性 | 类型 | 描述 |
|---|---|---|
default |
Boolean |
默认画质 |
html |
String |
画质名字 |
url |
String |
画质地址 |
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
quality: [
{
default: true,
html: 'SD 480P',
url: '/assets/sample/video.mp4',
},
{
html: 'HD 720P',
url: '/assets/sample/video.mp4',
},
],
});
highlight Permalink to "`highlight`"
- Type:
Array - Default:
[]
在进度条上显示 高亮信息
| 属性 | 类型 | 描述 |
|---|---|---|
time |
Number |
高亮时间(单位秒) |
text |
String |
高亮文本 |
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
highlight: [
{
time: 60,
text: 'One more chance',
},
{
time: 120,
text: '谁でもいいはずなのに',
},
{
time: 180,
text: '夏の想い出がまわる',
},
{
time: 240,
text: 'こんなとこにあるはずもないのに',
},
{
time: 300,
text: '--终わり--',
},
],
});
plugins Permalink to "`plugins`"
- Type:
Array - Default:
[]
初始化自定义的 插件
function myPlugin(art) {
console.info(art);
return {
name: 'myPlugin',
something: 'something',
doSomething: function () {
console.info('doSomething');
},
};
}
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
plugins: [myPlugin],
});
thumbnails Permalink to "`thumbnails`"
- Type:
Object - Default:
{}
在进度条上设置 预览图
| 属性 | 类型 | 描述 |
|---|---|---|
url |
String |
预览图地址 |
number |
Number |
预览图数量 |
column |
Number |
预览图列数 |
width |
Number |
预览图宽度 |
height |
Number |
预览图高度 |
scale |
Number |
预览图缩放 |
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
thumbnails: {
url: '/assets/sample/thumbnails.png',
number: 60,
column: 10,
},
});
在线生成预览图
subtitle Permalink to "`subtitle`"
- Type:
Object - Default:
{}
设置视频的字幕,支持字幕格式:vtt, srt, ass
| 属性 | 类型 | 描述 |
|---|---|---|
name |
String |
字幕名字 |
url |
String |
字幕地址 |
type |
String |
字幕类型,可选 vtt, srt, ass |
style |
Object |
字幕样式 |
encoding |
String |
字幕编码,默认 utf-8 |
escape |
Boolean |
是否转义 html 标签,默认为 true |
onVttLoad |
Function |
用于修改 vtt 文本的函数 |
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
subtitle: {
url: '/assets/sample/subtitle.srt',
type: 'srt',
encoding: 'utf-8',
escape: true,
style: {
color: '#03A9F4',
'font-size': '30px',
},
},
});
moreVideoAttr Permalink to "`moreVideoAttr`"
- Type:
Object - Default:
{'controls': false, 'preload': 'metadata'}(Safari 中会自动调整为preload: 'auto'以提升加载体验)
更多视频属性,这些属性将直接写入视频元素里
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
moreVideoAttr: {
'webkit-playsinline': true,
playsInline: true,
},
});
icons Permalink to "`icons`"
- Type:
Object - Default:
{}
用于替换默认图标,支持 Html 字符串和 HTMLElement
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
icons: {
loading: '<img src="/assets/img/ploading.gif">',
state: '<img src="/assets/img/state.png">',
},
});
全部图标的定义
type Permalink to "`type`"
- Type:
String - Default:
''
用于指明视频的格式,需要配合 customType 一起使用,默认视频的格式就是视频地址的后缀(如 .m3u8, .mkv, .ts),但有时候视频地地址没有正确的后缀,所以需要特别指明
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.m3u8',
type: 'm3u8',
});
后缀的识别
播放器只能解析这种后缀:/assets/sample/video.m3u8
但无法解析这种后缀:/assets/sample/video?type=m3u8
所以假如你使用了 customType,最好同时要指明 type
customType Permalink to "`customType`"
- Type:
Object - Default:
{}
通过视频的 type 进行匹配,把视频解码权交给第三方程序进行处理,处理的函数能接收三个参数
video: 视频DOM元素url: 视频地址art: 当前实例
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.m3u8',
customType: {
m3u8: function (video, url, art) {
//
},
},
});
lang Permalink to "`lang`"
- Type:
String - Default:
navigator.language.toLowerCase()
默认显示语言,目前支持:en, zh-cn
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
lang: 'en',
});
更多的语言设置
i18n Permalink to "`i18n`"
- Type:
Object - Default:
{}
自定义 i18n 配置,该配置会和自带的 i18n 进行深度合并
新增你的语言:
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
lang: 'your-lang',
i18n: {
'your-lang': {
Play: 'Your Play'
},
},
});
修改现有的语言
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
i18n: {
'zh-cn': {
Play: 'Your Play'
},
'zh-tw': {
Play: 'Your Play'
},
},
});
更多的语言设置
lock Permalink to "`lock`"
- Type:
Boolean - Default:
false
是否在移动端显示一个 锁定按钮 ,用于隐藏底部 控制栏
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
lock: true,
});
gesture Permalink to "`gesture`"
- Type:
Boolean - Default:
true
是否在移动端启用视频元素上的手势事件
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
gesture: false,
});
fastForward Permalink to "`fastForward`"
- Type:
Boolean - Default:
false
是否在移动端添加长按视频快进功能
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
fastForward: true,
});
autoPlayback Permalink to "`autoPlayback`"
- Type:
Boolean - Default:
false
是否使用自动 回放功能
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
id: 'your-url-id',
autoPlayback: true,
});
提示
因为播放器默认使用 url 作为 key 来缓存播放进度的
但假如你的同一个视频的 url 是不同的话,那么你需要使用 id 来标识视频的唯一 key
autoOrientation Permalink to "`autoOrientation`"
- Type:
Boolean - Default:
false
是否在移动端的网页全屏时,根据视频尺寸和视口尺寸,旋转播放器
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
autoOrientation: true,
});
airplay Permalink to "`airplay`"
- Type:
Boolean - Default:
false
是否显示 airplay 按钮,当前只有部分浏览器支持该功能
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
airplay: true,
});
cssVar Permalink to "`cssVar`"
- Type:
Object - Default:
{}
用于改变内置的css变量
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
cssVar: {
//
},
});
cssVar 写法参考
proxy Permalink to "`proxy`"
- Type:
function - Default:
undefined
函数可以返回一个第三方的 HTMLCanvasElement 或者 HTMLVideoElement,例如可以代理一个已经存在的 video dom元素
var art = new Artplayer({
container: '.artplayer-app',
url: '/assets/sample/video.mp4',
proxy: () => document.createElement('video')
});