ArtPlayer/packages/artplayer-document/docs/zh-cn/Options.md at 17f79d0b2202e4ab8a50f9366a8ec339123847b5

x15904151985/ArtPlayer

0 Fork 0

mirror of https://github.com/zhw2590582/ArtPlayer.git synced 2026-10-08 10:56:15 -08:00

Files

T

Harvey 17f79d0b22 update

2022-02-11 11:20:54 +08:00

22 KiB

Raw Blame History

title, sidebar_position, slug

title	sidebar_position	slug
基础参数	2	/zh-cn/options

container

类型: String、Element
默认: #artplayer
必填: 是

播放器所挂载的 dom 容器，其必须是具有尺寸的，否则播放器无法显示

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    // container: document.querySelector('.artplayer-app'),
    url: '/assets/sample/video.mp4',
});

您可能需要初始化容器元素的大小，如:

.artplayer-app {
    width: 400px;
    height: 300px;
}

url

类型: String
默认: ''
必填: 是

视频源地址，默认支持三种视频文件格式：.mp4、.ogg、.webm

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

poster

类型: String
默认: ''

视频的海报，只会出现在播放器初始化且未播放的状态下

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    poster: '/assets/sample/poster.jpg',
});

title

类型: String
默认: ''

视频标题，目前会出现在视频截图和迷你模式下

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    title: '【新海诚动画】『秒速5センチメートル』',
    screenshot: true,
});

theme

类型: String
默认: #f00

播放器主题颜色，目前只作用于进度条上

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    theme: '#ffad00',
});

volume

类型: Number
默认: 0.7

播放器的默认音量

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    volume: 0.5,
});

:::tip 提示

播放器会缓存最后一次音量的大小，下次初始化时（如刷新页面）播放器会读取该缓存值

:::

isLive

类型: Boolean
默认: false

使用直播模式，会隐藏进度条和播放时间

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    isLive: true,
});

muted

类型: Boolean
默认: false

是否默认静音

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    muted: true,
});

autoplay

类型: Boolean
默认: false

是否自动播放

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    autoplay: true,
    muted: true,
});

:::tip 提示

假如希望默认进入页面就能自动播放视频，muted 必需为 true，更多信息请阅读 Autoplay Policy Changes

:::

autoSize

类型: Boolean
默认: false

播放器的尺寸默认会填充整个 container 容器尺寸，所以经常出现黑边，该值能自动调整播放器尺寸以隐藏黑边

▶ Run Code

// 缩放浏览器窗口查看效果
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    autoSize: true,
});

autoMini

类型: Boolean
默认: false

当播放器滚动到浏览器视口以外时，自动进入迷你播放模式

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    autoMini: true,
});

loop

类型: Boolean
默认: false

是否循环播放

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    loop: true,
});

flip

类型: Boolean
默认: false

是否显示视频翻转功能，目前只出现在 设置面板 里，所以需要同时设置 setting 为 true

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    flip: true,
    setting: true,
});

playbackRate

类型: Boolean
默认: false

是否显示视频播放速度功能，会出现在 设置面板 和 右键菜单 里

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    playbackRate: true,
    setting: true,
});

aspectRatio

类型: Boolean
默认: false

是否显示视频长宽比功能，会出现在 设置面板 和 右键菜单 里

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    aspectRatio: true,
    setting: true,
});

screenshot

类型: Boolean
默认: false

是否在底部控制栏里显示视频截图功能

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    screenshot: true,
    // 可选
    moreVideoAttr: {
        crossOrigin: 'anonymous',
    },
});

:::tip 提示

由于浏览器安全机制，假如视频源地址和网站是跨域的，可能会出现截图失败

:::

setting

类型: Boolean
默认: false

是否在底部控制栏里显示设置面板的开关按钮

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    setting: true,
});

hotkey

类型: Boolean
默认: true

是否使用快捷键

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    hotkey: true,
});

热键	描述
`↑`	增加音量
`↓`	降低音量
`←`	快进 5 秒
`→`	快退 5 秒
`space`	切换播放/暂停

:::tip 提示

只在播放器获得焦点后（如点击了播放器后），该快捷键才会生效

:::

pip

类型: Boolean
默认: false

是否在底部控制栏里显示画中画的开关按钮

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    pip: true,
});

mutex

类型: Boolean
默认: true

假如页面里同时存在多个播放器，是否只能让一个播放器播放

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    mutex: true,
});

fullscreen

类型: Boolean
默认: false

是否在底部控制栏里显示播放器窗口全屏按钮

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    fullscreen: true,
});

fullscreenWeb

类型: Boolean
默认: false

是否在底部控制栏里显示播放器网页全屏按钮

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    fullscreenWeb: true,
});

subtitleOffset

类型: Boolean
默认: false

字幕时间偏移，范围在 [-5s, 5s]

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    subtitle: {
        url: '/assets/sample/subtitle.srt',
    },
    setting: true,
    subtitleOffset: true,
});

miniProgressBar

类型: Boolean
默认: false

迷你进度条，只在播放器失去焦点后且正在播放时出现

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    miniProgressBar: true,
});

useSSR

类型: Boolean
默认: false

是否使用 SSR 挂载模式，假如你希望在播放器挂载前，就提前渲染好播放器所需的HTML时有用

你可以通过Artplayer.html访问到播放器所需的HTML

▶ Run Code

var $container = document.querySelector('.artplayer-app');
$container.innerHTML = Artplayer.html;

var art = new Artplayer({
    container: $container,
    url: '/assets/sample/video.mp4',
    useSSR: true,
});

:::tip 提示

SSR 是 Server Side Render 简称，页面上的内容是通过服务端渲染生成的，浏览器直接显示服务端返回的 HTML 就可以了。

:::

layers

类型: Array
默认: []

初始化自定义的业务图层

属性	类型	描述
`disable`	`Boolean`	是否禁用组件
`name`	`String`	组件唯一名称，用于标记类名
`index`	`Number`	组件索引，用于显示的优先级
`html`	`String`、`Element`	组件的 DOM 元素
`style`	`Object`	组件样式对象
`click`	`Function`	组件点击事件
`mounted`	`Function`	组件挂载后触发
`tooltip`	`String`	组件的提示文本

▶ Run Code

var img = '/assets/sample/layer.png';
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    layers: [
        {
            index: 1,
            name: 'potser',
            disable: false,
            html: `<img style="width: 100px" src="${img}">`,
            style: {
                position: 'absolute',
                top: '20px',
                right: '20px',
                opacity: '.9',
            },
            click: function (...args) {
                console.info('你点击了组件');
                art.layers.show = false;
            },
            mounted: function (...args) {
                console.info('组件挂载完成');
            },
        },
    ],
});

settings

类型: Array
默认: []

初始化自定义的设置面板，更多信息请访问怎么添加设置面板

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    setting: true,
    settings: [
        {
            html: '自定义设置01',
            selector: [
                {
                    html: '子菜单01',
                    onSelect: function() {
                        console.log('你点击了子菜单01');
                    }
                },
                {
                    html: '子菜单02',
                    onSelect: function() {
                        console.log('你点击了子菜单02');
                    }
                },
            ]
        },
        {
            html: '自定义设置02',
            selector: [
                {
                    html: '子菜单01',
                    onSelect: function() {
                        console.log('你点击了子菜单01');
                    }
                },
                {
                    html: '子菜单02',
                    onSelect: function() {
                        console.log('你点击了子菜单02');
                    }
                },
            ]
        },
    ],
});

contextmenu

类型: Array
默认: []

初始化自定义的右键菜单

属性	类型	描述
`disable`	`Boolean`	是否禁用组件
`name`	`String`	组件唯一名称，用于标记类名
`index`	`Number`	组件索引，用于显示的优先级
`html`	`String`、`Element`	组件的 DOM 元素
`style`	`Object`	组件样式对象
`click`	`Function`	组件点击事件
`mounted`	`Function`	组件挂载后触发
`tooltip`	`String`	组件的提示文本

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    contextmenu: [
        {
            html: '自定义菜单',
            click: function () {
                console.info('你点击了自定义菜单');
                art.contextmenu.show = false;
            },
        },
    ],
});

art.on('ready', () => {
    art.contextmenu.show = true;
});

controls

类型: Array
默认: []

初始化自定义的底部控制栏

属性	类型	描述
`disable`	`Boolean`	是否禁用组件
`name`	`String`	组件唯一名称，用于标记类名
`index`	`Number`	组件索引，用于显示的优先级
`html`	`String`、`Element`	组件的 DOM 元素
`style`	`Object`	组件样式对象
`click`	`Function`	组件点击事件
`mounted`	`Function`	组件挂载后触发
`tooltip`	`String`	组件的提示文本
`position`	`String`	位置在 `left` 或者 `right`

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    controls: [
        {
            disable: false,
            name: 'button',
            index: 10,
            position: 'right',
            html: '自定义按钮',
            tooltip: '自定义按钮的提示1',
            style: {
                color: 'red',
            },
            click: function () {
                console.log('你点击了自定义按钮1');
            },
            mounted: function () {
                console.log('自定义按钮挂载完成1');
            },
        },
        {
            position: 'left',
            html: '自定义按钮2',
            tooltip: '自定义按钮的提示2',
            style: {
                color: 'green',
            },
            click: function () {
                console.log('你点击了自定义按钮2');
            },
        },
    ],
});

quality

类型: Array
默认: []

是否在底部控制栏里显示画质选择列表

属性	类型	描述
`default`	`Boolean`	默认画质
`name`	`String`	画质名字
`url`	`String`	画质地址

▶ Run Code

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

类型: Array
默认: []

在进度条上显示高亮信息点

属性	类型	描述
`time`	`Number`	高亮时间（单位秒）
`text`	`String`	高亮文本

▶ Run Code

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

类型: Array
默认: []

初始化自定义的插件

▶ Run Code

function myPlugin(art) {
    console.info('你可以在插件里访问到播放器的实例');
    return {
        name: 'myPlugin',
        something: '自定义导出的属性',
        doSomething: function () {
            console.info('自定义导出的方法');
        },
    };
}

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    plugins: [myPlugin],
});

art.on('ready', () => {
    console.info(art.plugins.myPlugin.something);
    console.info(art.plugins.myPlugin.doSomething());
});

whitelist

类型: Array
默认: []

因为不同的移动设备存在多种差异和限制，所以本播放器默认在移动设备上使用原生方法挂载视频，假如你想在移动设备上使用本播放器，需要手动开启白名单

白名单是一个数组类型，分别与 window.navigator.userAgent 进行匹配，只要其中一项匹配成功则启用播放器

支持字符串匹配、函数匹配、正则匹配

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    whitelist: ['iPhone OS 11'],
    // whitelist: ['*'],
    // whitelist: [(ua) => /iPhone OS 11/gi.test(ua)],
    // whitelist: [/iPhone OS 11/gi],
    
});

:::tip 提示

假如希望全部类型的移动设备都启用播放器，设置 whitelist 为通配符 ['*'] 即可

:::

thumbnails

类型: Object
默认: {}

在进度条上设置预览图

属性	类型	描述
`url`	`String`	预览图地址
`number`	`Number`	预览图数量
`column`	`Number`	预览图列数

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    thumbnails: {
        url: '/assets/sample/thumbnails.png',
        number: 100,
        column: 10,
    },
});

subtitle

类型: Object
默认: {}

设置视频的字幕，支持字幕格式：vtt、srt、ass

属性	类型	描述
`url`	`String`	字幕地址
`type`	`String`	字幕类型，可选 `vtt`、`srt`、`ass`
`style`	`Object`	字幕样式
`encoding`	`String`	字幕编码，默认 `utf-8`
`bilingual`	`Boolean`	是否双字幕样式，通过换行区分

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    subtitle: {
        url: '/assets/sample/subtitle.srt',
        type: 'srt',
        encoding: 'utf-8',
        bilingual: true,
        style: {
            color: '#03A9F4',
            'font-size': '30px',
        },
    },
});

moreVideoAttr

类型: Object
默认: {'controls': false,'preload': 'metadata'}

更多视频属性，这些属性将直接写入视频元素里

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    moreVideoAttr: {
        'webkit-playsinline': true,
        playsInline: true,
    },
});

icons

类型: Object
默认: {}

用于替换默认图标，支持 Html 字符串

▶ Run Code

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">',
        play: '',
        pause: '',
        volume: '',
        volumeClose: '',
        subtitle: '',
        screenshot: '',
        setting: '',
        fullscreen: '',
        fullscreenWeb: '',
        pip: '',
        indicator: '',
    },
});

type

类型: String
默认: ''

用于指明视频的格式，需要配合 customType 一起使用，更多信息请访问第三方库

默认视频的格式就是视频地址的后缀（如 .flv、.mkv、.ts），但有时候视频地地址没有正确的后缀，所以需要特别指明

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.flv',
    type: 'flv',
});

customType

类型: Object
默认: {}

通过视频的格式进行匹配，把视频解码权交给第三方程序进行处理，更多信息请访问第三方库

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.flv',
    customType: {
        flv: function (video, url, art) {
            // video: 视频dom元素
            // url: 视频地址
            // art: 当前实例
        },
    },
});

lang

类型: String
默认: navigator.language.toLowerCase()

默认显示语言，目前支持：en、zh-cn、zh-tw

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    lang: 'en',
});

22 KiB Raw Blame History

container

url

poster

title

theme

volume

isLive

muted

autoplay

autoSize

autoMini

loop

flip

playbackRate

aspectRatio

screenshot

setting

hotkey

pip

mutex

fullscreen

fullscreenWeb

subtitleOffset

miniProgressBar

useSSR

layers

settings

contextmenu

controls

quality

highlight

plugins

whitelist

thumbnails

subtitle

moreVideoAttr

icons

type

customType

lang

22 KiB

Raw Blame History