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

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,
});

rotate

• 类型: Boolean
• 默认: false

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

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    rotate: true,
    setting: true,
    autoSize: 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,
});

localVideo

• 类型: Boolean
• 默认: false

内置插件：本地视频插件，需要使用art.plugins.localVideo.attach方法挂载打开视频按钮

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    localVideo: true,
    controls: [
        {
            name: 'preview',
            position: 'right',
            html: '打开视频',
            mounted: ($preview) => {
                art.plugins.localVideo.attach($preview);
            },
        },
    ],
});

localSubtitle

• 类型: Boolean
• 默认: false

内置插件：本地字幕插件，需要使用art.plugins.localSubtitle.attach方法挂载打开字幕按钮

▶ Run Code

var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    localSubtitle: true,
    controls: [
        {
            name: 'preview',
            position: 'right',
            html: '打开字幕',
            mounted: ($preview) => {
                art.plugins.localSubtitle.attach($preview);
            },
        },
    ],
});

networkMonitor

• 类型: Boolean
• 默认: false

内置插件：播放卡顿监听插件

▶ Run Code

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

// 例如，当比率等于0.5时，它意味着每10秒的采样时间里有5秒的时间是卡顿的
let notice = false;
art.on('networkMonitor', (ratio) => {
    if (ratio >= 0.5 && !notice) {
        notice = true;
        console.log('当前播放状态欠佳');
    }
});

// 修改采样时间，单位是毫秒，默认为10秒。
art.plugins.networkMonitor.sample(30000);

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,
});

layers

contextmenu

controls

quality

highlight

plugins

whitelist

switcher

thumbnails

subtitle

moreVideoAttr

icons

customType

lang