import{_ as n,o as e,c as l,ak as s,j as a}from"./chunks/framework.xxfEszSJ.js";const E=JSON.parse('{"title":"Advanced Properties","description":"","frontmatter":{},"headers":[],"relativePath":"en/advanced/built-in.md","filePath":"en/advanced/built-in.md","lastUpdated":1789506045000}'),t={name:"en/advanced/built-in.md"};function p(h,i,r,k,d,o){return e(),l("div",null,i[0]||(i[0]=[s('

Advanced Properties ​

The Advanced Properties here refer to the secondary properties attached to the instance, which are less commonly used.

option ​

The player's options.

',4),a("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

console.info(art.option);

Note

If you directly modify this option object, the player will not respond immediately.

template ​

Manages all DOM elements of the player.

`,4),a("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

console.info(art.template);
console.info(art.template.$video);

Note

To easily distinguish between DOM elements and regular objects, all DOM elements within the player are named with a $ prefix.

This is the definition of all DOM elements: artplayer/types/template.d.ts

$container is the div supplied by the caller; $player is the generated player root inside it. They are different elements. These fields retain node references bound during initialization rather than performing a new query on every read:

FieldDefault selector or source
$containerSupplied div container
$player.art-video-player
$video.art-video
$tracktrack
$poster.art-poster
$subtitle.art-subtitle
$danmuku.art-danmuku
$bottom.art-bottom
$progress.art-progress
$controls.art-controls
$controlsLeft.art-controls-left
$controlsCenter.art-controls-center
$controlsRight.art-controls-right
$layer.art-layers
$loading.art-loading
$notice.art-notice
$noticeInner.art-notice-inner
$mask.art-mask
$state.art-state
$setting.art-settings
$info.art-info
$infoPanel.art-info-panel
$infoClose.art-info-close
$contextmenu.art-contextmenus

art.query(selector) and art.template.query(selector) are the same bound function and can be extracted for later calls. Queries always search descendants of the original $container, excluding the container itself. They do not follow player/media nodes moved outside it. Missing matches return null; invalid selectors retain querySelector errors. art.video returns the cached template.$video, which can be a canvas with a proxy. The original $track can become detached with a replaced video, so stored references need not remain connected inside the container.

template.art references the player. Optional $mini can appear after creating a mini window; the default mini node is attached to document.body outside the original container. Do not rebuild the player by replacing these fields. template.init() initializes the template: ordinary mode replaces container HTML, then binds nodes and the proxy. Repeating it is not a supported interface-reset workflow. template.destroy(removeHtml) only handles template DOM: true empties the container, false adds art-destroy. Use art.destroy(removeHtml?) for complete resource cleanup.

Read the template string from static Artplayer.html. The old root declaration's art.template.html is not an actual instance member and normally reads as undefined. useSSR: true preserves and queries supplied markup without filling missing nodes. Keep that markup complete and version-matched; instantiation still requires a browser. Runtime types retain nullable nodes while root types retain historical non-null shapes. A type assertion cannot repair incomplete SSR markup.

events ​

Manages all DOM events for the player. It essentially proxies addEventListener and removeEventListener. When using the following methods to handle events, the events will also be automatically destroyed when the player is destroyed.

`,10),a("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var container = document.querySelector('.artplayer-app');

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

art.events.proxy(container, 'click', event => {
	console.info('click', event);
});

art.events.hover(container, (event) => {
    console.info('mouseenter', event);
}, (event) => {
    console.info('mouseleave', event);
});

Note

If you need DOM events that should only exist during the player's lifecycle, it is strongly recommended to use these functions to avoid memory leaks.

This registry manages DOM listeners registered through it, separately from player subscriptions using art.on/off. art.proxy is the same proxy shortcut. proxy(target, name, callback, options?) returns a disposer, or an array of disposers when name is an array. Call each disposer directly or pass it to art.events.remove(dispose) for early removal. Options retain native capture/once/passive/signal behavior; a normal listener's this is the native event target, not the player.

hover registers mouseenter/mouseleave and returns undefined; it does not create a new player hover event. destroyEvents holds cleanup functions and should not be mutated directly. events.destroy() clears the current registry, including core listeners; it does not destroy the player. Normally use art.destroy(). New proxies on a destroyed player do not register listeners.

bindGlobalEvents({ window, document }) rebinds global listeners after a cross-document move. A successful replacement releases the old binding; a failed replacement preserves it. Omitted fields use the player node's document/window. Supply both when moving between windows. This method neither moves DOM nodes nor rebinds listeners your application installed itself.

storage ​

Manages the player's local storage.

`,8),a("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

art.storage.set('test', { foo: 'bar' });
const test = art.storage.get('test');
console.info(test);
art.storage.del('test');
art.storage.clear();

Note

By default, all player instances share the same localStorage, and the default key is artplayer_settings.

If you want different players to use different localStorage, you can modify art.storage.name.

`,2),a("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

art.storage.name = 'your-storage-key';
art.storage.set('test', { foo: 'bar' });

name is the localStorage key containing the entire JSON record; the key passed to set/get/del selects a field inside it. get() returns the full data and get(key) reads one field. Historical truthy-key selection means an empty string (and numeric zero at runtime) returns the full data; use nonempty string keys. set/del/clear synchronously return undefined.

clear() removes only the current name entry, not all localStorage for the origin. Changing name does not migrate old data. Same-origin instances with the same name share persisted data. settings is a per-instance error fallback, not a live mirror of persistence. Failed reads or writes use the corresponding fallback operation; restored access does not merge fallback data automatically. Storage uses JSON and does not preserve functions, circular objects or all other non-JSON values.

icons ​

Manages all svg icons for the player.

`,5),a("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

console.info(art.icons.loading);

This is the definition of all icons:

artplayer/types/icons.d.ts

These 27 default names share the same read behavior:

text
loading, state, play, pause, check, volume, volumeClose, screenshot, setting, pip, arrowLeft, arrowRight, playbackRate, aspectRatio, config, lock, flip, unlock, fullscreenOff, fullscreenOn, fullscreenWebOff, fullscreenWebOn, switchOn, switchOff, error, close, airplay

Every read creates a new <i class="art-icon art-icon-NAME"> wrapper, so two reads of art.icons.play are different objects. This is not a reference to the icon already mounted in a button; modifying a later wrapper does not change the existing button. Root declarations retain HTMLDivElement, although the wrapper is an i element; runtime types use HTMLElement.

Supply constructor icons options to replace default content or add custom names. Strings are parsed as HTML and should contain trusted markup. An HTMLElement is moved into the new wrapper rather than cloned; a later read may move it out of its previous wrapper. Use strings or your own cloned elements when independent copies are needed.

Names and values are shallow-copied at initialization. Later changes to art.option.icons do not replace that mapping or the rendered interface. Properties are read-only getters and are non-enumerable by default. An unconfigured ordinary custom name returns undefined; check it before appending.

i18n ​

Manages the player's i18n.

`,10),a("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

console.info(art.i18n.get('Play'));

art.i18n.update({
    'zh-cn': {
        Play: 'Your Play'
    }
});

WARNING

Using art.i18n.update can only update the i18n after instantiation. If you want to update i18n before instantiation, please use the i18n option in the basic settings.

languages holds dictionaries by language code, language is the selected dictionary, and art references the player. update({ 'zh-cn': { Play: '播放' } }) deep-merges dictionaries and calls init(); both return undefined. init selects art.option.lang.toLowerCase(), without lowercasing dictionary keys. Simplified Chinese is built in; an unloaded language falls back to the original key text.

get(key) returns a nonempty translation or the key itself; an empty translation also falls back. Updating dictionaries does not redraw existing button, tooltip or menu text. After changing option.lang, init updates future lookups; it is not a complete interface-language switch API. These text keys from the historical declarations share the same lookup rules; runtime lookup also accepts application-defined keys:

text
Context Menu
Lock
Video Info
Close
Video Load Failed
Volume
Progress
Back
Settings
Play
Pause
Rate
Mute
Video Flip
Horizontal
Vertical
Reconnect
Show Setting
Hide Setting
Screenshot
Play Speed
Aspect Ratio
Default
Normal
Open
Switch Video
Switch Subtitle
Fullscreen
Exit Fullscreen
Web Fullscreen
Exit Web Fullscreen
Mini Player
PIP Mode
Exit PIP Mode
PIP Not Supported
Fullscreen Not Supported
Subtitle Offset
Last Seen
Jump Play
AirPlay
AirPlay Not Available

notice ​

Manages the player's notifications. Assign text through show or read its visibility state.

`,7),a("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

art.on('ready', () => {
    art.notice.show = 'Video Ready To Play';
})

WARNING

If you want to hide the notice immediately: art.notice.show = '';

Assigning a string or Error displays plain text and restarts the hide timer. Errors use their trimmed message; ordinary strings retain their original text. Reading notice.show returns a boolean visibility state, not the last assigned text. Assigning false or an empty string hides immediately, without immediately clearing the text or canceling the old timer.

Each display reads its delay from Artplayer.NOTICE_TIME. timer is a timer handle, not a countdown. destroy() cancels the timer without hiding the node or destroying the player. New notices cannot appear after player destruction. The root entry retains the historical getter type; use artplayer/runtime for its accurate boolean type.

layers ​

Manages the player's layers.

`,7),a("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

art.on('ready', () => {
    art.layers.add({
        html: 'Some Text',
    });

	setTimeout(() => {
		art.layers.show = false;
	}, 1000);
});

For Component Configuration, please refer to:

/component/layers.html

controls ​

Manages the player's controls.

`,5),a("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

art.on('ready', () => {
    art.controls.add({
        html: 'Some Text',
        position: 'left',
    });

	setTimeout(() => {
		art.controls.show = false;
	}, 1000);
});

For Component Configuration, please refer to:

/component/controls.html

contextmenu ​

Manages the player's context menu

`,5),a("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

art.on('ready', () => {
    art.contextmenu.add({
        html: 'Some Text',
    });

    art.contextmenu.show = true;
	setTimeout(() => {
		art.contextmenu.show = false;
	}, 1000);
});

For Component Configuration, please refer to:

/component/contextmenu.html

subtitle ​

Manages the player's subtitle functionality

`,5),a("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

art.on('ready', () => {
    art.subtitle.url = '/assets/sample/subtitle.srt'
    art.subtitle.style({
        color: 'red',
    });
});

info ​

Manages the player's information panel, commonly used to view the current status of the player and video, such as version number, resolution, duration, etc.

`,4),a("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

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

    setTimeout(() => {
        art.info.show = false;
    }, 3000);
});

loading ​

Manages the player's loading layer

`,4),a("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

art.on('ready', () => {
    art.loading.show = true;
	setTimeout(() => {
		art.loading.show = false;
	}, 1000);
});

hotkey ​

Manages the player's hotkey functionality

`,4),a("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

function hotkeyEvent(event) {
    console.info('click', event);
}

art.on('ready', () => {
    art.hotkey.add('Space', hotkeyEvent);
    setTimeout(() => {
		art.hotkey.remove('Space', hotkeyEvent);
	}, 5000);
});

Note

These hotkeys only take effect after the player gains focus (e.g., after clicking on the player)

Use KeyboardEvent.code strings such as 'Space', 'KeyK' and 'ArrowLeft', not numeric keyCode values. add/remove return the hotkey manager. Removal requires the original callback. Different callbacks may share a key; the same callback is not added twice. A callback's this is the player. Adding a custom Space callback does not replace built-in play/pause.

keys stores callback arrays by code; art references the player. Desktop construction calls init automatically. hotkey: false disables built-in keys, but manually added callbacks still work. Mobile keyboard listening is opt-in through the existing init method; this is not physical-device acceptance. Repeated init does not duplicate the same default callbacks or document subscription.

Inputs, textareas, selects, editable content, composition and modified key events are excluded. Native activation keys on buttons/links and keys already handled by player controls do not trigger duplicate shortcuts. Matching callbacks prevent the native default action and are followed by the hotkey event; the player keydown event follows as well.

mask ​

Manages the player's mask layer

`,8),a("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

art.on('ready', () => {
    art.mask.show = false;
	setTimeout(() => {
		art.mask.show = true;
	}, 1000);
});

setting ​

Manages the player's settings panel

`,4),a("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
    setting: true,
    flip: true,
    playbackRate: true,
    aspectRatio: true,
    subtitleOffset: true,
});

art.on('ready', () => {
    art.setting.show = true;
	setTimeout(() => {
		art.setting.show = false;
	}, 1000);
});

For Settings Panel, please refer to

/component/setting.html

plugins ​

Manages the player's plugin functionality, with only one method add for dynamically adding plugins

`,4),a("div",{className:"run-code"},"▶ Run Code",-1),s(`
js
var art = new Artplayer({
    container: '.artplayer-app',
    url: '/assets/sample/video.mp4',
});

function myPlugin(art) {
    console.info(art);
    return {
        name: 'myPlugin',
        something: 'something',
        doSomething: function () {
            console.info('doSomething');
        },
    };
}

art.on('ready', () => {
    art.plugins.add(myPlugin);
});

TypeScript service views ​

The current, unpublished refactor's artplayer/runtime entry supplies accurate declarations for the same implementation, including boolean notice.show, EventListener objects and service members. Root and legacy entries preserve historical declaration shapes. Runtime exports EventRegistry, Storage, I18n<Host>, Hotkey<Host> and Notice describe services; Dictionary/Languages describe language data.

ts
import Artplayer from 'artplayer/runtime';

const art = new Artplayer({ container: '#player', url: '/video.mp4', hotkey: false });
const dispose = art.events.proxy(document, 'click', { handleEvent(event) { console.log(event.type); } });
art.events.remove(dispose);
const onSpace = function (this: Artplayer, event: KeyboardEvent) { console.log(this.id, event.code); };
art.hotkey.add('Space', onSpace);
art.hotkey.remove('Space', onSpace);
art.notice.show = 'Ready';
const visible: boolean = art.notice.show;
art.notice.show = false;
art.i18n.update({ en: { Play: 'Start' } });
console.log(visible, art.i18n.get('Play'));

TypeScript template and icon views ​

The unpublished refactor's artplayer/runtime uses Template<Host>, Icons and media-capability types for nullable queries, unknown icons and proxy media. This example uses the same implementation as the root entry:

ts
import Artplayer from 'artplayer/runtime';

const art = new Artplayer({
    container: '#player', url: '/video.mp4',
    icons: { customMark: '<span aria-hidden="true">*</span>' },
});
const query = art.query;
const player: HTMLDivElement | null = query('.art-video-player');
const icon: HTMLElement | undefined = art.icons.customMark;
if (player && icon) player.append(icon);
console.log(Artplayer.html, art.video === art.template.$video);
`,7)]))}const y=n(t,[["render",p]]);export{E as __pageData,y as default};