mirror of
https://github.com/zhw2590582/ArtPlayer.git
synced 2026-10-21 04:31:20 -08:00
241 lines
13 KiB
Markdown
241 lines
13 KiB
Markdown
# Static Properties
|
|
|
|
Here, `static properties` refer to the `first-level properties` attached to the `constructor`, which are rarely used.
|
|
|
|
## `instances`
|
|
|
|
Returns an array of all player instances. This property can be useful when you need to manage multiple players simultaneously.
|
|
|
|
<div className="run-code">▶ Run Code</div>
|
|
|
|
```js
|
|
console.info([...Artplayer.instances]);
|
|
|
|
var art = new Artplayer({
|
|
container: '.artplayer-app',
|
|
url: '/assets/sample/video.mp4',
|
|
});
|
|
|
|
console.info([...Artplayer.instances]);
|
|
```
|
|
|
|
## `version`
|
|
|
|
Returns the version information of the player.
|
|
|
|
<div className="run-code">▶ Run Code</div>
|
|
|
|
```js
|
|
console.info(Artplayer.version);
|
|
```
|
|
|
|
## `env`
|
|
|
|
Returns the environment variables of the player.
|
|
|
|
<div className="run-code">▶ Run Code</div>
|
|
|
|
```js
|
|
console.info(Artplayer.env);
|
|
```
|
|
|
|
## `build`
|
|
|
|
Returns the build timestamp of the player.
|
|
|
|
<div className="run-code">▶ Run Code</div>
|
|
|
|
```js
|
|
console.info(Artplayer.build);
|
|
```
|
|
|
|
## `config`
|
|
|
|
Returns the shared media-surface inventory, not the default player options (those are in Artplayer.option).
|
|
|
|
### Media surface inventory {#config-contract}
|
|
|
|
The getter returns the same object each time. Its properties, methods, events, and prototypes arrays describe media property names, callable methods, native events, and additional video-specific surface members. They are inventories, not capability guarantees: proxies and browsers may support only part of the surface.
|
|
|
|
The core reads config.events when installing native event forwarding, then forwards those events as video:eventName. Changing the array later does not add/remove listeners on existing players. Debug logging and proxy adapters also consume this inventory; editing it does not create the corresponding native methods or properties. The root Config type retains historical readonly tuples; runtime Config accurately exposes mutable string arrays. Mutation affects shared consumers, so preserve order and restore temporary test changes.
|
|
|
|
<div className="run-code">▶ Run Code</div>
|
|
|
|
```js
|
|
console.info(Artplayer.config);
|
|
```
|
|
|
|
|
|
```ts
|
|
import Artplayer from 'artplayer/runtime';
|
|
import type { Config } from 'artplayer/runtime';
|
|
|
|
const config: Config = Artplayer.config;
|
|
const nativeNames: string[] = config.events.slice();
|
|
const shared: boolean = Artplayer.config === config;
|
|
void [nativeNames, shared];
|
|
```
|
|
|
|
## `utils`
|
|
|
|
Returns the collection of utility functions for the player.
|
|
|
|
<div className="run-code">▶ Run Code</div>
|
|
|
|
```js
|
|
console.info(Artplayer.utils);
|
|
```
|
|
|
|
:::warning For all utility functions, please refer to the following address:
|
|
|
|
[artplayer/types/utils.d.ts](https://github.com/zhw2590582/ArtPlayer/blob/master/packages/artplayer/types/utils.d.ts)
|
|
|
|
:::
|
|
|
|
### Environment and types {#utils-contract}
|
|
|
|
`Artplayer.utils` is a public collection, not bound to a player instance. Text and data helpers work independently; DOM, image, style, and measurement helpers require a browser and the relevant nodes. Resources you create through these utilities are not automatically released when a player is destroyed.
|
|
|
|
`isBrowser`, `userAgent`, `isMobile`, `isSafari`, `isIOS`, and `isIOS13` are calculated at module load, not updated after window or UA changes. The UA uses `globalThis.CUSTOM_USER_AGENT` if set before loading, otherwise navigator. `isIOS13` also recognizes a touch-capable Macintosh. These are compatibility heuristics, not guarantees of media capabilities or OS versions.
|
|
|
|
The root `Utils` retains historical signatures; `Utils` from `artplayer/runtime` describes actual returns and broader DOM inputs. Internal helper shapes require only style for `StyledElement`, and target plus optional composedPath for `EventPathSource`; neither is a separately named export from the runtime entry. A generic query provides a static type without checking the actual element tag.
|
|
|
|
### DOM and styles {#utils-dom}
|
|
|
|
| Utility | Arguments, returns, and boundaries |
|
|
| --- | --- |
|
|
| `query(selector, parent?)` / `queryAll(selector, parent?)` | Default to document; return the first element or null / a fresh array. Search descendants, excluding the parent itself; invalid selectors still throw |
|
|
| `createElement(tag)` | Creates a native HTML element without attaching it |
|
|
| `addClass` / `removeClass` / `hasClass` | Accept a node and one class token; the first two return undefined, the last a boolean. Native classList argument errors are preserved |
|
|
| `append(parent, child)` | Moves same-realm Elements; other values are stringified and appended as HTML. Returns lastElementChild, falling back to lastChild, so appended text is not necessarily the return value; an empty parent may yield null |
|
|
| `remove(child)` / `replaceElement(newChild, oldChild)` | Return the removed node / new node; missing parents still cause errors |
|
|
| `siblings(target)` / `inverseClass(target, name)` | Return other elements under the same parent / remove the class from siblings and add it to target, returning undefined. Require parentElement |
|
|
| `setStyle(element, key, value)` / `setStyles(element, styles)` | Assign directly to style and return the original element. setStyles includes inherited enumerable string keys; neither adds units nor clears previous styles |
|
|
| `getStyle(element, key, numberType = true)` | Reads getComputedStyle/getPropertyValue; defaults to parseFloat, yielding NaN for nonnumeric values. Pass false for the raw string. Use CSS names such as `font-size` |
|
|
| `setStyleText(id, cssText)` | Replaces textContent of an existing element with that id, otherwise creates style. While the document is loading, attachment to head waits for DOMContentLoaded. No Promise or automatic disposal; use a dedicated id |
|
|
| `getRect(element)` | Returns the original getBoundingClientRect DOMRect, beyond the four fields in the root type |
|
|
| `getIcon(key = '', html = '')` | Returns a new i element with art-icon and art-icon-key classes, using append rules for contents; elements are moved, not cloned |
|
|
| `tooltip(target, message, position = 'top')` | On desktop, sets aria-label and hint--rounded / hint--position classes; does nothing on mobile. Later calls do not remove earlier direction classes |
|
|
|
|
HTML strings are not sanitized. Use textContent for plain text or escape for the intended context; do not pass untrusted content directly to append/getIcon.
|
|
|
|
### Events and measurement {#utils-measure}
|
|
|
|
| Utility | Behavior |
|
|
| --- | --- |
|
|
| `getComposedPath(event)` | Calls composedPath with its original receiver and returns its array directly. Otherwise walks target.parentNode and appends window in a browser. The fallback does not reproduce a complete Shadow DOM path |
|
|
| `includeFromEvent(event, target)` | Tests membership in that path, rather than performing a separate DOM contains query |
|
|
| `isInViewport(element, offset = 0)` | Tests rectangle/window intersection, including boundaries. It does not prove full visibility or lack of occlusion, and retains the historical offset calculation |
|
|
| `getSafeAreaInsets()` | Attaches a temporary invisible node and reads numeric env(safe-area-inset-*) values, using zero for unparseable values. Removes the node on success or failure; requires document.body |
|
|
| `supportsFlex()` | Only tests whether an element accepts display:flex, not whether layout works correctly |
|
|
|
|
### Subtitles, images, and files {#utils-resources}
|
|
|
|
| Utility | Behavior and ownership |
|
|
| --- | --- |
|
|
| `srtToVtt(text)` / `assToVtt(text)` | Synchronously return WebVTT text. The former normalizes milliseconds and some style markers; the latter extracts basic Dialogue timing/text. Neither is a full subtitle validator or ASS renderer |
|
|
| `vttToBlob(text)` | Returns a text/vtt Blob URL, not a Blob. The caller must revoke the URL when finished |
|
|
| `getExt(url)` | Removes query/fragment, trims and lowercases, then takes text after the last dot. Without a dot it returns the remaining string; no resource or MIME check |
|
|
| `download(url, name)` | Creates, clicks, and removes a temporary download link. No completion result or guarantee the browser saves a file; does not revoke the input URL |
|
|
| `loadImg(url, scale?)` | Resolves with a loaded HTMLImageElement. Falsy scale or1 returns the original image; other values use canvas/toBlob and load the scaled result. Its image.src is a caller-owned Blob URL that must be revoked after use |
|
|
|
|
`loadImg` does not set crossOrigin and has no public cancellation or timeout option. A cross-origin image can display while still making canvas unreadable. Image loading, canvas, or encoding failures reject the Promise. Successful listeners are removed; failure during scaling releases an already created Blob URL. Revoke a scaled result's src only after the page no longer needs it; the original image URL is not owned by this function.
|
|
|
|
### Data, errors, and scheduling {#utils-data}
|
|
|
|
| Utility | Behavior |
|
|
| --- | --- |
|
|
| `def(object, key, descriptor)` | Object.defineProperty itself, returning the original object. The root string-key overload's historical void return is not the runtime result |
|
|
| `has(object, key)` / `get(object, key)` | Test own-property presence / retrieve an own descriptor, returning undefined if missing |
|
|
| `mergeDeep(...objects)` | Creates a new top-level object using Object.keys. Two non-array objects merge recursively; two arrays use the historical concat/spread rule, which can flatten nested arrays in the latter array. Not a complete deep clone: unmerged values retain references. Cyclic merging is unsupported; __proto__ is stored as own data |
|
|
| `clamp(number, a, b)` | Clamps between either ordering of endpoints; NaN remains NaN |
|
|
| `secondToTime(seconds)` | Floors to mm:ss, or hh:mm:ss from one hour; hours can exceed two digits. Falsy inputs yield00:00. Does not additionally validate negative or nonfinite inputs |
|
|
| `escape(text)` / `unescape(text)` | Only the five fixed entities for ampersand, angle brackets, and single/double quotes, in one pass. unescape is not a general HTML entity parser |
|
|
| `capitalize(text)` | Uppercases only the first character |
|
|
| `ArtPlayerError(message?, context?)` / `errorHandle(condition, message?)` | Error subclass named ArtPlayerError, with context used for supported stack capture / throw that error for falsy conditions, otherwise return the original value |
|
|
| `silencePromise(value)` | If catch is callable, return the result of catching and consuming a rejection; otherwise return the value unchanged. Uses catch capability, not instanceof Promise; synchronous errors thrown by catch itself still propagate |
|
|
| `sleep(milliseconds = 0)` | Resolves with undefined after a timer, without cancellation |
|
|
| `debounce(callback, duration)` | Trailing call with the last arguments and call receiver. Ignores the historical context argument; wrapper returns undefined |
|
|
| `throttle(callback, duration)` | Synchronous leading call, dropping calls during the wait without a trailing call. Preserves the call receiver; wrapper returns undefined |
|
|
|
|
Neither wrapper offers cancel/flush or automatic cancellation on player destruction. Throttle enters its waiting period only after the callback returns normally, preserving synchronous reentry and another attempt after a thrown error. Historical root return inference does not change this behavior.
|
|
|
|
```ts
|
|
import Artplayer from 'artplayer/runtime';
|
|
import type { Utils } from 'artplayer/runtime';
|
|
|
|
const utils: Utils = Artplayer.utils;
|
|
const fragment = document.createDocumentFragment();
|
|
const missing: HTMLVideoElement | null = utils.query<HTMLVideoElement>('video', fragment);
|
|
const div = utils.createElement('div');
|
|
const styled: HTMLDivElement = utils.setStyle(div, 'fontSize', '20px');
|
|
const width: string = utils.getStyle(div, 'width', false);
|
|
const invoke = utils.debounce(function (this: { value: number }, step: number) {
|
|
this.value += step;
|
|
}, 20);
|
|
const returned: void = invoke.call({ value: 0 }, 1);
|
|
void [missing, styled, width, returned];
|
|
```
|
|
|
|
|
|
## `scheme`
|
|
|
|
Returns the validation schema for player options.
|
|
|
|
<div className="run-code">▶ Run Code</div>
|
|
|
|
```js
|
|
console.info(Artplayer.scheme);
|
|
```
|
|
|
|
## `Emitter`
|
|
|
|
Returns the constructor of the event emitter.
|
|
|
|
<div className="run-code">▶ Run Code</div>
|
|
|
|
```js
|
|
console.info(Artplayer.Emitter);
|
|
```
|
|
|
|
## `validator`
|
|
|
|
Returns the validation function for options.
|
|
|
|
<div className="run-code">▶ Run Code</div>
|
|
|
|
```js
|
|
console.info(Artplayer.validator);
|
|
```
|
|
|
|
## `kindOf`
|
|
|
|
Returns the type detection utility function.
|
|
|
|
<div className="run-code">▶ Run Code</div>
|
|
|
|
```js
|
|
console.info(Artplayer.kindOf);
|
|
```
|
|
|
|
## `html`
|
|
|
|
Returns the `html` string required by the player.
|
|
|
|
<div className="run-code">▶ Run Code</div>
|
|
|
|
```js
|
|
console.info(Artplayer.html);
|
|
```
|
|
|
|
This is the current version's static base markup, including required classes and media/control nodes, not a snapshot of an instance's current DOM. When reusing preinserted markup through `useSSR: true`, keep its complete structure and version aligned. The option does not make construction work outside a browser. Actual template instances have no `html` member; the historical root type retains that member for compatibility, but it does not replace the static entry.
|
|
|
|
## `option`
|
|
|
|
Returns the default options of the player.
|
|
|
|
<div className="run-code">▶ Run Code</div>
|
|
|
|
```js
|
|
console.info(Artplayer.option);
|
|
``` |