x15904151985/ArtPlayer
1
0 Fork 0
mirror of https://github.com/zhw2590582/ArtPlayer.git synced 2026-10-21 21:01:20 -08:00
Code Issues Packages Projects Releases Wiki Activity

docs(site): [SITE-04] cross-check existing plugin guide semantics

Browse Source
This commit is contained in:
Harvey Zhao committed 2026-09-16 04:28:32 +08:00
1 parent 4db9789014
commit b029062ace
125 files changed
+4880 -2430
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

packages/artplayer-plugin-dash-control/ARCHITECTURE.md
+4 -2
View File
@@ -91,8 +91,10 @@ Replacing `art.dash` requires ready/restart or explicit update to bind the new S
Release invalidates the record before calling the captured `off` method and attempts
every owned removal. Reentrant replacement wins; caller listeners remain installed.
An asynchronous SDK getter/formatter failure stops observation, clears owned menus,
and warns with the original error. Restore the offending formatter/SDK state and
During asynchronous SDK-event refresh, a synchronous getter/formatter exception
stops observation and clears owned menus. Getters and formatters must return
synchronously; their returned Promises are not awaited. The plugin warns with the
original error. Restore the offending formatter/SDK state and
call explicit `update()` to recover. Explicit update and synchronous menu errors keep
their original throwing behavior. Never convert the public update API to a Promise
or destroy an SDK to handle a plugin rendering failure.
packages/artplayer-vitepress/docs/.vitepress/config.js
+1 -1
View File
@@ -186,7 +186,7 @@ const config = {
],
},
{
text: 'Proxys',
text: 'Proxies',
collapsible: true,
items: [
{ text: 'Canvas', link: '/en/proxy/canvas' },
packages/artplayer-vitepress/docs/en/plugin/audio-track.md
+2
View File
@@ -107,3 +107,5 @@ const art = new Artplayer({
Named types include `Option`, `UpdateOption`, the old `Result`, `RuntimeResult` and `RuntimeFactory`. The online editor's default global retains legacy inference too. To select precise update typing, explicitly use `artplayerPluginAudioTrack as artplayerPluginAudioTrack.RuntimeFactory`. This does not create a second plugin implementation.
Actual desktop tests cover audio/video playback, pause, seeking, updates and destruction. They do not establish support for every mobile device, proxy player, audio format or long-running synchronization combination. Check browser decoding capabilities and the project's validation records for the applicable scope.
Windows WebKit MP4/AAC starvation remains an open native-media validation issue: a stalled video does not reliably emit waiting in that reproduction. Passing source-switch ordering checks does not close that separate case.
packages/artplayer-vitepress/docs/en/plugin/danmuku.md
+15 -3
View File
@@ -52,7 +52,7 @@ https://unpkg.com/artplayer-plugin-danmuku/dist/artplayer-plugin-danmuku.js
## Comment structure
Only `text` is required. Leading and trailing whitespace is removed; empty comments are ignored.
Only `text` is required. Empty or whitespace-only comments are ignored. Direct `emit()` and loaded rows retain the original text, including surrounding spaces; only the input panel trims its submitted text.
```js
({
@@ -67,6 +67,8 @@ Only `text` is required. Leading and trailing whitespace is removed; empty comme
Explicit `time: 0` is preserved. Negative times are clamped to zero. Other than 0, 1 and 2, comment modes are ignored.
Normalization fills time, mode, color and style on the supplied object before calling `filter`. The queue then receives a shallow copy; its style object is still shared. Copy reusable inputs when these mutations matter. The optional string `id` becomes the displayed element's `data-id`; it does not deduplicate comments. Text is rendered through `textContent`, not as HTML.
## All options
Pass an option object to the factory. At runtime, `{}` is valid and all fields have defaults.
@@ -105,7 +107,7 @@ The historical root declarations still require `danmuku`; existing TypeScript pr
```
`OPACITY`, `FONT_SIZE`, `MARGIN` and `SPEED` override slider definitions with `min`, `max` and `steps`.
Each step can contain `name`, `value`, `hide` and `show`; margin values are pairs such as `[10, '50%']`.
Each step can contain `name`, `value`, `hide` and `show`. `hide` suppresses its label; the retained `show` field is not read by the renderer. Margin values are pairs such as `[10, '50%']`.
`COLOR` replaces the palette with an array of CSS color strings; an empty array uses the built-in palette.
## Array, XML and asynchronous input
@@ -300,6 +302,10 @@ Use `$ref.textContent` when adding text in a `visible` handler.
## TypeScript
The `/runtime` `Owner` type describes the internal return object for existing advanced integrations. Its `art`, `option`, `queue` and `states` are live objects; `readys` is the current candidate list. `speed`, `fontSize`, `marginTop/marginBottom` and `isRotate` are computed views. Do not mutate queue state to simulate public commands.
Owner's additional `start/stop` methods control comment scheduling and emit their events; `continue/suspend` resume or pause existing displayed items; `update` schedules work. These methods synchronously return Owner and do not control video playback. `resize` adjusts displayed items, while `seek` cancels old display preparation and schedules again; both return `undefined`. Owner's `destroy` cleans scheduling, nodes and input tasks and emits its destroy event, but does not fully uninstall the settings panel and heatmap. Use `art.destroy()` for complete cleanup. These additional commands are absent from the registered result.
The root and `/legacy` entrypoints keep the npm 5.3.0 declaration shapes for compatibility, including historical inaccuracies about return values.
The current branch adds `/runtime` for accurate types while loading the same runtime factory:
@@ -316,4 +322,10 @@ art.on('artplayerPluginDanmuku:error', onError);
```
The explicit `EventMap` describes payloads; it does not augment the core's historical event declarations automatically.
The factory also exposes the existing `icons` object for customization. Package `README.md` and `ARCHITECTURE.md` describe module ownership, maintenance commands and remaining device/combination validation.
The factory also exposes the existing `icons` object for customization.
Root named types are `Mode`, `Danmuku`, `Slider`, `Danmu`, `Option` and `Result`. `/runtime` exposes `Mode`, `State`, `Margin`, `Point`, `Danmu`, `NormalizedDanmu`, `Item`, `Input`, `SliderStep`, `Slider`, `Heatmap`, `NormalizedOption`, `RuntimeOption`, `Owner`, `RuntimeResult`, `Icons`, `RuntimeFactory` and `EventMap`. `Item` adds `$state/$index/$ref/$restTime/$lastStartTime`; nodes are reused and `$ref` becomes null when recycled. A node received by a visible handler does not permanently belong to that comment.
`icons` contains `$on/$off/$config/$style`, the three pairs `$mode_0_off/$mode_0_on` through `$mode_2_off/$mode_2_on`, and `$check_on/$check_off`. Applications can reuse these SVG strings in their own interfaces. The built-in panel reads bundled icons directly; changing the factory icons object does not replace its icons.
Package `README.md` and `ARCHITECTURE.md` describe module ownership, maintenance commands and remaining device/combination validation.
packages/artplayer-vitepress/docs/en/plugin/dash-control.md
+4 -2
View File
@@ -25,7 +25,7 @@ For script tags, load ArtPlayer, dash.js and `dist/artplayer-plugin-dash-control
The example matches the [online DASH example](https://artplayer.org/?libs=https://cdnjs.cloudflare.com/ajax/libs/dashjs/5.2.1/modern/umd/dash.all.min.js%0A./uncompiled/artplayer-plugin-dash-control/index.js&example=dash.control). Replace the site's container and media URL in your application.
<div className="run-code" data-libs="https://cdnjs.cloudflare.com/ajax/libs/dashjs/5.2.1/modern/umd/dash.all.min.js
./uncompiled/artplayer-plugin-dash-control/index.js"></div>
./uncompiled/artplayer-plugin-dash-control/index.js">▶ Run Code</div>
```js
// npm i dashjs
@@ -141,7 +141,7 @@ art.plugins.artplayerPluginDashControl.update();
Automatic refresh preserves an open, plugin-owned quality or audio settings panel. Explicit `update()` keeps its existing rebuild behavior. Reserve `dash-quality` and `dash-audio` for the plugin's menu names.
If an asynchronous SDK getter or formatter fails, the plugin warns, stops that observation and clears its menus. Fix the formatter/SDK state and call `update()` to recover. Explicit update and synchronous selection errors keep their normal throwing behavior.
If a synchronous SDK getter or formatter throws during an asynchronous refresh scheduled by an SDK event, the plugin warns, stops that observation and clears its menus. Fix the formatter/SDK state and call `update()` to recover. Getters and formatters must return synchronously; the plugin does not await their Promises. Explicit update and synchronous selection errors keep their normal throwing behavior.
## SDK ownership and source switching
@@ -173,6 +173,8 @@ const plugin = dashControl<Level, Track>({
`Option`, `Config`, `QualityLevel`, `AudioTrack` and `Result` are exported from the root. Root and legacy paths remain available. If using actual SDK declarations, dash.js 4.5.2 exposes `BitrateInfo` for quality; 5.2.1 uses `Representation`. Its declarations have different compiler/module-resolution requirements, so test your actual SDK and TypeScript combination. Describe the externally attached `art.dash` in your application's integration types.
The registered result contains only the fixed `name: 'artplayerPluginDashControl'` and `update()`. Ordinary factory calls may omit the options, while the last declaration overload keeps its parameter required: `Parameters<typeof dashControl>[0]` remains `Option`, without `undefined`. This package has no `/runtime` subpath or factory `.default` self-alias.
## Validation scope
The refactor tests fixed dash.js 4.5.2 and 5.2.1 with local adaptive media and old/new core combinations. Those are tested points, not a new blanket support range. The plugin includes a targeted 4.5.2 paused-seek recovery for stale empty-buffer metrics while preserving the caller's SDK settings and media time. Windows Playwright WebKit lacks the MSE path used by these tests; it is not Safari/device playback acceptance. Test your own MPDs, DRM and target devices before adopting the unpublished refactor.
packages/artplayer-vitepress/docs/en/plugin/hls-control.md
+3 -1
View File
@@ -25,7 +25,7 @@ For script tags, load ArtPlayer, Hls.js and the plugin's `dist/artplayer-plugin-
The example uses the site's player container and the same source as the [online HLS example](https://artplayer.org/?libs=https://cdnjs.cloudflare.com/ajax/libs/hls.js/1.5.17/hls.min.js%0A./uncompiled/artplayer-plugin-hls-control/index.js&example=hls.control). Replace the container and stream URL in your application.
<div className="run-code" data-libs="https://cdnjs.cloudflare.com/ajax/libs/hls.js/1.5.17/hls.min.js
./uncompiled/artplayer-plugin-hls-control/index.js"></div>
./uncompiled/artplayer-plugin-hls-control/index.js">▶ Run Code</div>
```js
// npm i hls.js
@@ -160,6 +160,8 @@ const plugin = hlsControl<Level, Track>({
Public `Option`, `Config`, `QualityLevel`, `AudioTrack` and `Result` types are exported from the root entry. The root and legacy import paths remain available. The types do not pretend every ArtPlayer instance already owns an Hls.js engine; describe `art.hls` in your application's integration types.
The registered result contains only the fixed `name: 'artplayerPluginHlsControl'` and `update()`. Ordinary factory calls may omit the options, while the last declaration overload keeps its parameter required: `Parameters<typeof hlsControl>[0]` remains `Option`, without `undefined`. This package has no `/runtime` subpath or factory `.default` self-alias.
## Validation scope
The refactor tests Hls.js 1.5.17 and 1.7.2 with local media and real workers; these are tested points, not a newly declared supported range. Firefox grouped-stream crashes and a separate switching stall remain under investigation. Windows Playwright WebKit lacks the MSE path used in those tests; it does not establish Safari/iOS native-HLS acceptance. Verify your actual streams and target devices before adopting the unpublished refactor.
packages/artplayer-vitepress/docs/en/plugin/vtt-thumbnail.md
+2
View File
@@ -75,6 +75,8 @@ For historical compatibility, start and end times are rounded down to whole seco
Desktop hover selects a cue using the progress percentage multiplied by the video duration. Gaps hide the preview, and previews near the edges are aligned inward. The mobile path responds to progress dragging with an input event and hides about 500ms after the last drag update. Desktop coverage does not establish real touch-device support.
The selected position must be strictly inside the progress bar. Desktop progress at exactly 0 or 1 hides the preview. Those mobile endpoints do not draw a new preview, but an existing preview still hides on its timer. The plugin uses control name `vtt-thumbnail` and CSS class `art-control-thumbnails`; preserve these existing hooks.
## Asynchronous registration, errors and cleanup
Registration fetches and parses the VTT and actually returns a Promise. Its success result contains only `name: 'artplayerPluginVttThumbnail'`. Installation through the constructor's plugins array is asynchronous; do not assume that the result is registered immediately after construction.
packages/artplayer-vitepress/docs/plugin/audio-track.md
+2
View File
@@ -107,3 +107,5 @@ const art = new Artplayer({
命名类型包括 `Option`、`UpdateOption`、旧 `Result`、`RuntimeResult` 与 `RuntimeFactory`。在线编辑器的全局默认类型也保留旧推导；选择精确更新类型时，可显式使用 `artplayerPluginAudioTrack as artplayerPluginAudioTrack.RuntimeFactory`。这不会创建第二份插件实现。
真实桌面测试覆盖音频/视频播放、暂停、seek、更新和销毁；它们不证明所有移动设备、代理播放器、音频格式或长时间同步组合都通过。完整支持范围仍需结合对应浏览器的解码能力与项目验收记录。
Windows WebKit 的 MP4/AAC 耗尽缓冲仍有原生媒体验证缺口：该复现中视频停滞不可靠地触发 waiting。换源顺序检查通过不代表这一独立问题已关闭。
packages/artplayer-vitepress/docs/plugin/danmuku.md
+13 -1
View File
@@ -50,6 +50,8 @@ https://unpkg.com/artplayer-plugin-danmuku/dist/artplayer-plugin-danmuku.js
每一个弹幕是一个对象，多个弹幕组成的数组就是弹幕库，通常只需要`text`就可以发送一个弹幕，其余都是非必要参数
空文本或全空白文本会被忽略。直接 `emit()` 和加载数组保留文本两端的空格；只有输入面板会裁掉提交文本两端的空白。填入 time、mode、color、style 默认值会修改传入对象，然后才执行 `filter`；队列项是浅拷贝，style 对象仍共享。需要复用原数据时请先复制。可选的字符串 `id` 会写入显示节点的 `data-id`，不会用于去重。文本通过 `textContent` 显示，不作为 HTML 解析。
```js
{
text: '', // 弹幕文本
@@ -98,13 +100,15 @@ https://unpkg.com/artplayer-plugin-danmuku/dist/artplayer-plugin-danmuku.js
```
`OPACITY`、`FONT_SIZE`、`MARGIN`、`SPEED` 可覆盖滑块的 `min`、`max`、`steps`。
每个 step 可包含 `name`、`value`、`hide`、`show`；MARGIN 的 value 是上下边距数组。
每个 step 可包含 `name`、`value`、`hide`、`show`；`hide` 隐藏标签，保留的 `show` 字段未被渲染器读取。MARGIN 的 value 是上下边距数组。
`COLOR` 用 CSS 颜色字符串数组替换调色板，空数组使用内置调色板。
## 生命周期
`filter` 同步执行，不应返回 Promise；`beforeEmit` 可异步，但只有严格返回 `true` 才发送。`beforeVisible` 可以异步。普通函数形式的这三个回调，其 `this` 都是当前配置对象。直接调用 `emit` 不执行 `beforeEmit`，需要业务校验时请在调用前完成。
运行时 `filter` 接受同步 truthy 值，`beforeVisible` 接受异步结算后的 truthy 值；旧根声明将它们限制为布尔值。建议仍显式返回布尔值，尤其不要用返回 Promise 的 `filter` 进行异步校验。
来自用户输入的弹幕:
`beforeEmit -> filter -> beforeVisible -> artplayerPluginDanmuku:visible`
@@ -625,6 +629,10 @@ art.on('artplayerPluginDanmuku:loaded', drawPoints);
## TypeScript
`/runtime` 的 `Owner` 描述上述内部返回对象，便于维护已有高级调用。其 `art`、`option`、`queue`、`states` 是实时对象；`readys` 是当前候选列表，`speed`、`fontSize`、`marginTop/marginBottom`、`isRotate` 是计算视图。不要直接修改队列状态来模拟公开命令。
Owner 额外的 `start/stop` 控制弹幕调度并发出对应事件，`continue/suspend` 只恢复或暂停已有显示项，`update` 安排调度；这些方法同步返回 Owner，不控制视频播放。`resize` 调整显示项，`seek` 取消旧显示准备并重新调度，两者返回 `undefined`。Owner 的 `destroy` 清理调度、节点和输入任务，发出 destroy 事件，但不等于完整卸载设置面板和热力图；完整清理由 `art.destroy()` 驱动。注册结果没有这些额外命令。
根入口和 `/legacy` 保留 npm 5.3.0 的历史声明形状，其中部分方法返回值与真实运行时不一致。
当前分支新增 `/runtime` 提供准确类型，加载的仍是同一个运行时工厂；该入口尚未发布，不能从旧 CDN 版本导入。
@@ -641,4 +649,8 @@ art.on('artplayerPluginDanmuku:error', onError);
```
`EventMap` 显式描述事件参数，不会自动扩展核心历史事件声明。工厂仍暴露 `icons` 对象供自定义图标。
根入口命名类型为 `Mode`、`Danmuku`、`Slider`、`Danmu`、`Option`、`Result`。`/runtime` 提供 `Mode`、`State`、`Margin`、`Point`、`Danmu`、`NormalizedDanmu`、`Item`、`Input`、`SliderStep`、`Slider`、`Heatmap`、`NormalizedOption`、`RuntimeOption`、`Owner`、`RuntimeResult`、`Icons`、`RuntimeFactory`、`EventMap`。`Item` 带有 `$state/$index/$ref/$restTime/$lastStartTime`；节点会复用，回收后 `$ref` 为 null，不能将 visible 时取得的节点当作永久归属该弹幕。
`icons` 包含 `$on/$off/$config/$style`、三个模式各自的 `$mode_0_off/$mode_0_on` 到 `$mode_2_off/$mode_2_on`，以及 `$check_on/$check_off`。这些 SVG 字符串可供应用自己的界面复用。内置面板直接读取打包的图标，修改工厂 icons 对象不会替换内置面板图标。
包内 `README.md` 和 `ARCHITECTURE.md` 维护模块职责、验证命令及尚未完成的设备和组合验收。
packages/artplayer-vitepress/docs/plugin/dash-control.md
+4 -2
View File
@@ -25,7 +25,7 @@ import artplayerPluginDashControl from 'artplayer-plugin-dash-control';
下面与[在线 DASH 示例](https://artplayer.org/?libs=https://cdnjs.cloudflare.com/ajax/libs/dashjs/5.2.1/modern/umd/dash.all.min.js%0A./uncompiled/artplayer-plugin-dash-control/index.js&example=dash.control)使用相同代码。接入应用时替换站点容器和视频地址。
<div className="run-code" data-libs="https://cdnjs.cloudflare.com/ajax/libs/dashjs/5.2.1/modern/umd/dash.all.min.js
./uncompiled/artplayer-plugin-dash-control/index.js"></div>
./uncompiled/artplayer-plugin-dash-control/index.js">▶ Run Code</div>
```js
// npm i dashjs
@@ -141,7 +141,7 @@ art.plugins.artplayerPluginDashControl.update();
自动刷新会保留已打开、由插件管理的画质或音轨设置子菜单；显式 `update()` 保留原有重建行为。插件使用 `dash-quality` 和 `dash-audio` 菜单名，其他菜单请避开这些名称。
异步 SDK getter 或格式回调失败时，插件会输出警告、停止该观察并清除菜单；修正回调或 SDK 状态后调用 `update()` 恢复。显式更新和同步选择的错误仍按原语义抛出。
SDK 事件触发的异步刷新中，若同步 SDK getter 或格式回调抛错，插件会输出警告、停止该观察并清除菜单；修正回调或 SDK 状态后调用 `update()` 恢复。getter 和格式回调必须同步返回，插件不会等待它们返回的 Promise。显式更新和同步选择的错误仍按原语义抛出。
## SDK 所有权与换源
@@ -173,6 +173,8 @@ const plugin = dashControl<Level, Track>({
根入口导出 `Option`、`Config`、`QualityLevel`、`AudioTrack` 和 `Result`，原根入口与 legacy 路径继续保留。使用实际 SDK 声明时，dash.js 4.5.2 的画质类型为 `BitrateInfo`，5.2.1 使用 `Representation`；其编译器与模块解析要求不同，应验证实际 SDK/TypeScript 组合。在应用的集成类型中描述外部附加的 `art.dash`。
注册结果只有固定的 `name: 'artplayerPluginDashControl'` 和 `update()`。工厂普通调用允许省略配置；最后一个声明重载保留必填参数，因此 `Parameters<typeof dashControl>[0]` 仍为 `Option`，不包含 `undefined`。本包没有 `/runtime` 子路径，也没有工厂 `.default` 自引用。
## 验证范围
重构使用固定 dash.js 4.5.2 / 5.2.1、本地自适应媒体和新旧核心组合验证；这两个版本是验证点，不是新定义的完整支持范围。插件对4.5.2暂停拖动后空缓冲指标陈旧的问题有定向恢复，保留调用方 SDK 设置和媒体时间。Windows Playwright WebKit 缺少相关 MSE 路径，不能代表 Safari 或真机播放已验收。采用未发布重构前，应验证自己的 MPD、DRM 和目标设备。
packages/artplayer-vitepress/docs/plugin/hls-control.md
+3 -1
View File
@@ -25,7 +25,7 @@ import artplayerPluginHlsControl from 'artplayer-plugin-hls-control';
下面与[在线 HLS 示例](https://artplayer.org/?libs=https://cdnjs.cloudflare.com/ajax/libs/hls.js/1.5.17/hls.min.js%0A./uncompiled/artplayer-plugin-hls-control/index.js&example=hls.control)使用同一份代码和站点容器。接入自己的应用时替换容器与视频地址。
<div className="run-code" data-libs="https://cdnjs.cloudflare.com/ajax/libs/hls.js/1.5.17/hls.min.js
./uncompiled/artplayer-plugin-hls-control/index.js"></div>
./uncompiled/artplayer-plugin-hls-control/index.js">▶ Run Code</div>
```js
// npm i hls.js
@@ -160,6 +160,8 @@ const plugin = hlsControl<Level, Track>({
根入口导出 `Option`、`Config`、`QualityLevel`、`AudioTrack` 和 `Result` 类型，原根入口及 legacy 路径继续保留。声明不会假定每个 ArtPlayer 实例都有 Hls.js；请在应用的集成类型中描述 `art.hls`。
注册结果只有固定的 `name: 'artplayerPluginHlsControl'` 和 `update()`。工厂普通调用允许省略配置；最后一个声明重载保留必填参数，因此 `Parameters<typeof hlsControl>[0]` 仍为 `Option`，不包含 `undefined`。本包没有 `/runtime` 子路径，也没有工厂 `.default` 自引用。
## 验证范围
重构使用本地媒体和真实 worker 验证 Hls.js 1.5.17 / 1.7.2；这两个版本是验证点，不是新定义的支持范围。Firefox 的分组播放崩溃和另一项切组停滞仍在排查。Windows Playwright WebKit 缺少测试所需的 MSE 路径，不能代表 Safari/iOS 原生 HLS 已验收。采用尚未发布的重构前，应验证实际媒体与目标设备。
packages/artplayer-vitepress/docs/plugin/vtt-thumbnail.md
+2
View File
@@ -75,6 +75,8 @@ bbb-sprite.jpg#xywh=128,0,128,72
桌面悬停按进度条百分比乘以视频总时长选择图片；没有匹配项时隐藏，预览靠近边缘时会向内对齐。移动端使用带输入事件的进度拖动路径，并在最后一次拖动更新后约 500ms 隐藏。桌面测试不能替代真实触摸设备验收。
绘制位置必须严格位于进度条内部。桌面进度恰好为 0 或 1 时隐藏预览；移动端这两个端点不会绘制新预览，但已有预览仍按计时器隐藏。插件使用控件名 `vtt-thumbnail` 和样式类 `art-control-thumbnails`，请保留这些既有挂钩。
## 异步注册、错误和销毁
注册会请求并解析 VTT，实际返回 Promise，成功结果只有 `name: 'artplayerPluginVttThumbnail'`。构造器 plugins 数组中的安装是异步的，不要在构造后立即假设结果已注册。