mirror of
https://github.com/zhw2590582/ArtPlayer.git
synced 2026-10-08 19:06:15 -08:00
76 lines
5.0 KiB
Markdown
76 lines
5.0 KiB
Markdown
# Thumbnail 默认行为兼容决策（已批准，已实施）
|
||
|
||
状态：approved，源码、类型及本机验证完成。责任任务 PKG-TOOL-THUMB-04，风险 THUMB-COMPAT-01。
|
||
2026-09-15 用户明确批准：“接受：npm 行为默认，工作区行为显式选择（推荐）”。
|
||
下列方案现在可直接实施，无需再次询问；批准不代替源码、类型和浏览器验证。
|
||
实施结果见 [完成记录](changes/2026-09-15-PKG-TOOL-THUMB-04-approved-policy.md)；
|
||
05/06、设备和发布门槛仍独立保留，Windows WebKit 能力对照不计截图提取通过。
|
||
|
||
## 已复现的冲突
|
||
|
||
恢复的 3.5.31 CDN main 与固定 Git 源码逐字节相等，但没有完整原 npm 归档。
|
||
重构基线中的 4.4.0 是未发布工作区代码；两者对同一调用有不同的默认行为，
|
||
见 [冻结契约](baselines/thumbnail-contract.md) 和对应历史测试。
|
||
|
||
| 行为 | 恢复的 3.5.31 | 未发布工作区 4.4.0 |
|
||
| --- | --- | --- |
|
||
| DEFAULTS | 含 delay: 300，height: 90 | 不含 delay，height: 90 |
|
||
| delay/height 输入 | 检查 number，限制到 10–1000 | 不检查/钳制这两项，开始时覆盖 height |
|
||
| 最终缩略图高度 | 使用配置的 height | 按视频原始宽高比计算 |
|
||
| file 事件 | 同步，早于 video.src 赋值 | 相同 |
|
||
| video 事件 | src 赋值后等待 delay | src 赋值后同步发出 |
|
||
| 每帧及完成 | seek 后等待 delay；最后额外等 delay * 2 | 等媒体就绪，无这两段固定额外延迟 |
|
||
| 选择文件后 | 不清空 input.value | 清空 input.value |
|
||
|
||
例如同样传入 width: 160、height: 25，16:9 视频在旧版保留 25 高，在工作区版
|
||
变成 90 高；loadVideo 后同步注册 video 监听器在两版也会得到不同结果。
|
||
不能通过 TS 重命名或内部拆文件同时满足这两种默认值和时序。
|
||
|
||
## 已批准方案：恢复已发布行为为默认，显式选择工作区模式
|
||
|
||
1. 根构造器默认选择恢复的 3.5.31 行为，支持旧 delay 参数，DEFAULTS 恢复
|
||
delay: 300；配置 height 保留原钳制，video 延迟、每帧/完成延迟及 input
|
||
不重置按上表执行。实际定时器受浏览器调度影响，不承诺精确毫秒时刻。
|
||
2. 新增可选配置 compatibility: 'workspace-4.4'，保留当前工作区的同步 video、
|
||
按比例高度、无额外固定等待和 input 重置。已有工作区调用只需增加这一字段。
|
||
显式 compatibility: 'published-3.5' 可表达默认选择。
|
||
3. 类级 DEFAULTS 没有实例上下文，统一表示根默认的 3.5.31 配置。依赖工作区
|
||
DEFAULTS 精确字段集合的代码需要明确选择/保存自己的配置；不能承诺它同时
|
||
返回两套对象。这个差异也属于本次已批准范围。
|
||
4. 保留已实现的 URL/监听器/定时器所有权、销毁与切源取消、错误结算、输入
|
||
清理和 emitter 修复。不会恢复旧版错绑 this、陈旧回调、资源泄漏等缺陷。
|
||
定时等待不取代真实帧就绪；修复慢解码导致错误截图的路径单独记录和验证。
|
||
5. 原入口、构造器名、事件名、历史 creat* 方法、链式返回、同步错误及 Promise
|
||
形状继续保留。公开声明增加可选模式/延迟类型，旧合法参数继续接受。
|
||
|
||
```js
|
||
// 恢复的 3.5.31 调用保持原样：固定高度和 delay 语义。
|
||
const tool = new ArtplayerToolThumbnail({ fileInput, height: 25, delay: 300 })
|
||
|
||
// 依赖未发布 4.4.0 行为的工作区使用者明确选择原模式。
|
||
const workspaceTool = new ArtplayerToolThumbnail({
|
||
fileInput,
|
||
compatibility: 'workspace-4.4',
|
||
})
|
||
```
|
||
|
||
未选择的替代方案是保留工作区 4.4.0 为默认，并要求已发布 3.5.31 用户选择
|
||
兼容模式；用户已经选择上面的 npm 默认方案。
|
||
|
||
## 批准后实施与验收
|
||
|
||
- 在独立的内部策略模块集中默认值、校验、尺寸和调度选择；source/input/
|
||
extraction 继续各自管理资源，不在各模块散落版本字符串判断。
|
||
- 每次 source/job 拥有延迟句柄；切源、失败、销毁后旧 video/update/done 不得
|
||
迟到。额外等待期间仍允许现有取消和错误路径完成，不制造悬空 Promise。
|
||
- 保留全部历史冻结用例；为两种模式增加同一调用的高度、DEFAULTS、参数校验、
|
||
input 重置、video/每帧/done 时序与交错清理测试，比较冻结版本与新实现。
|
||
- 运行严格类型/旧消费、源码及 main/legacy/ESM 构建消费，重验隔离安装与
|
||
编辑器声明；真实浏览器验证文件选择、像素、事件及清理。Windows WebKit
|
||
已记录的原生 Blob 不可用不能算作提取通过，支持设备验收继续保留。
|
||
- 同步包内维护文档和迁移示例，再根据实际证据完成 04；05/06 和整体验收
|
||
不因本决策自动完成。每个完成任务保持独立提交，无推送或发布授权变化。
|
||
|
||
需要用户选择的原因是 [兼容性契约](compatibility.md) 明确禁止静默改变已有行为，
|
||
且已复现的两套默认语义互斥；并非常规内部结构、依赖或脚本选择需要再次批准。
|