mirror of
https://github.com/zhw2590582/ArtPlayer.git
synced 2026-10-26 00:31:20 -08:00
docs(site): [SITE-04] cross-check existing plugin guide semantics
This commit is contained in:
Harvey Zhao committed
1 parent
4db9789014
commit
b029062ace
125 files changed
+4880
-2430
No files matched your search
@@ -107,3 +107,5 @@ const art = new Artplayer({
|
||||
命名类型包括 `Option`、`UpdateOption`、旧 `Result`、`RuntimeResult` 与 `RuntimeFactory`。在线编辑器的全局默认类型也保留旧推导；选择精确更新类型时，可显式使用 `artplayerPluginAudioTrack as artplayerPluginAudioTrack.RuntimeFactory`。这不会创建第二份插件实现。
|
||||
|
||||
真实桌面测试覆盖音频/视频播放、暂停、seek、更新和销毁；它们不证明所有移动设备、代理播放器、音频格式或长时间同步组合都通过。完整支持范围仍需结合对应浏览器的解码能力与项目验收记录。
|
||||
|
||||
Windows WebKit 的 MP4/AAC 耗尽缓冲仍有原生媒体验证缺口：该复现中视频停滞不可靠地触发 waiting。换源顺序检查通过不代表这一独立问题已关闭。
|
||||
@@ -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` 维护模块职责、验证命令及尚未完成的设备和组合验收。
|
||||
@@ -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 和目标设备。
|
||||
@@ -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 已验收。采用尚未发布的重构前，应验证实际媒体与目标设备。
|
||||
@@ -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 数组中的安装是异步的，不要在构造后立即假设结果已注册。
|
||||
|
||||
Reference in new issue
Block a user