✨ 为 GM.download/GM_download 添加 onloadend 回调

[cyfung1031]

Checklist / 检查清单

• Fixes API Compatibility Issue
• Code reviewed by human / 代码通过人工检查
• Changes tested / 已完成测试

背景

当前 GM.download / GM_download 支持通过 onload、onerror 和 ontimeout 分别处理不同的下载终止状态，但缺少一个无论成功、失败还是超时都会执行的统一收尾回调。

这使用户脚本不得不在多个终止回调中重复执行相同的清理、状态更新或 UI 收尾逻辑，也与 GM_xmlhttpRequest 已提供的 onloadend 生命周期接口不一致。

本次改动

• 为 GMTypes.DownloadDetails 新增 onloadend 回调。

• 同步更新以下类型声明：

  • src/types/scriptcat.d.ts
  • src/types/scriptcat.zh-CN.d.ts
  • src/template/scriptcat.d.tpl

• 在以下下载路径中接入 onloadend：

  • downloadMode: "browser"：直接通过后台 chrome.downloads 下载；
  • downloadMode: "native"：先通过 GM_xmlhttpRequest 获取 Blob，再交由后台保存；
  • Blob URL 等直接进入 browser 下载流程的请求。

• 在下载通过以下状态结束时，先执行对应主回调，再执行 onloadend：

  • onload
  • onerror
  • ontimeout
  • save_cancelled，沿用现有兼容行为，将用户取消“另存为”视为成功。

• browser 和 native 最终保存阶段共用统一的后台消息处理，避免两条路径的终止语义出现差异。

• browser 或 native 最终保存阶段连接后台失败时，也会依次执行 onerror、onloadend 并 reject Promise，避免请求永久 pending。

• native XHR 阶段失败时直接完成外层回调和 Promise，并阻止后续部分 Blob 被继续保存。

• 补充单元和回归测试，覆盖成功、失败、超时、后台连接失败、未知后台消息、部分数据、回调抛错、主动中止竞态、Promise 收尾及 Blob URL 释放。

实现考虑

1. 保证主回调与 onloadend 相互独立

终止处理统一通过 withLoadEnd 执行：

1. 调用对应的主回调，例如 onload、onerror 或 ontimeout；
2. 无论主回调是否抛出异常，都继续调用 onloadend；
3. 无论任一用户回调是否抛出异常，都继续完成 Promise 的 resolve 或 reject；
4. native 模式下同时保证 Blob URL 等资源最终得到释放。

这可以避免以下情况：

• onload / onerror / ontimeout 抛错后，onloadend 被跳过；
• onloadend 抛错后，GM.download 返回的 Promise 永久 pending；
• 用户回调异常导致 native 模式的 Blob URL 无法释放。

2. 统一 browser 与 native 的最终下载阶段

browser 模式会直接连接后台执行下载；native 模式则分为两个阶段：

1. 使用 GM_xmlhttpRequest 获取完整 Blob；
2. 创建 Blob URL，再连接后台执行实际保存。

两条路径最终都会收到相同的后台消息，例如：

• onload
• save_cancelled
• onprogress
• ontimeout
• onerror

因此共用同一套终止处理逻辑。

native 模式额外传入幂等的 releaseResources，在以下场景中释放 Blob URL：

• 下载成功；
• 下载失败或超时；
• 后台连接失败；
• 下载过程中被中止；
• 后台主动断开连接；
• 用户回调抛出异常；
• 收到非预期后台消息。

3. 后台连接失败也必须完整结束生命周期

browser 模式和 native 最终保存阶段都依赖与 Service Worker 建立消息连接。

如果 connect() 直接 reject，而调用侧不主动处理：

• onerror 不会执行；
• onloadend 不会执行；
• GM.download 返回的 Promise 会永久 pending；
• native 路径已经创建的 Blob URL 可能无法释放。

因此连接创建失败会按照普通下载错误处理：

1. 调用 onerror；
2. 调用 onloadend；
3. reject Promise；
4. native 模式释放 Blob URL。

4. 避免将失败请求的部分数据保存为文件

native 模式下，底层 XHR 即使已经触发 onerror 或 ontimeout，后续 onloadend 仍可能携带由已接收数据组成的非空 Blob。

如果仅判断 response instanceof Blob，这部分不完整数据可能被误认为下载成功，并继续交给 chrome.downloads 保存为截断文件，同时造成用户侧 onloadend 被重复触发。

实现通过 xhrFailed 标记记录 XHR 阶段是否已经失败。失败后收到的 XHR onloadend 不再进入 Blob 保存流程。

5. 避免 abort() 破坏内部 XHR 的收尾流程

native 模式的 XHR 阶段进入 onerror 或 ontimeout 后，会在调用用户回调前清空 nativeAbort。

这样即使用户在 onloadend 中调用外层 download.abort()，也不会再次中止并断开内部 GM_xmlhttpRequest 的消息通道，避免：

• 内部请求无法收到自己的 onloadend；
• 内部 XHR Promise 永久 pending；
• 引用和消息连接无法正常清理。

外层 GM.download 的 Promise 会直接在 XHR 失败回调的收尾阶段 reject，而不是仅依赖内部 XHR Promise 延迟返回失败结果。

6. 用户回调异常不能中断内部状态机

在 native XHR 的 onerror / ontimeout 阶段，用户回调抛出的异常不能同步传播回 GM_xmlhttpRequest 的消息处理循环。

否则可能中断内部完成状态更新、合成 onloadend 排程及引用清理。

因此该路径会先完成：

• 主回调和 onloadend；
• 外层 Promise reject；
• 内部 XHR 生命周期收尾。

随后再通过微任务异步重新抛出用户回调异常，使异常仍可被全局错误处理捕获，但不会破坏内部状态机。

已知限制

1. 主动调用 abort() 不会新增触发 onloadend

本次改动只为成功、失败、超时以及下载保存阶段的终止结果补充 onloadend。

主动调用返回对象的 abort() 仍沿用现有行为，不额外合成 onabort 或 onloadend。

如需统一主动中止的生命周期，需要单独设计 GM.download 的中止事件语义。

2. onloadend 参数沿用对应终止事件的数据

onloadend 不定义新的专用响应结构，而是尽量复用对应终止状态的数据：

• 成功时携带与 onload 相同的下载结果；
• 失败时携带 { error: "unknown" }；
• 超时时使用空对象；
• 后台连接失败时使用对应的错误响应结构；
• 保留调用方传入的 context。

因此它不是原生 DOM ProgressEvent 的完整映射。

3. save_cancelled 继续视为成功

用户在“另存为”窗口中取消操作时，现有实现会将 save_cancelled 视为成功，并依次调用 onload 和 onloadend、resolve GM.download Promise。

本 PR 保留该兼容行为，不调整取消保存的结果语义。

建议审查重点

• onload / onerror / ontimeout 与 onloadend 的调用顺序是否符合预期；
• 任一用户回调抛错时，另一个回调、Promise settlement 和资源清理是否仍能完成；
• browser/native 后台连接失败时是否会正确完成全部终止步骤；
• native XHR 失败后，xhrFailed 是否能完整阻止部分 Blob 被继续保存；
• 在 onloadend 内调用 abort() 时，外层和内部 Promise 是否都能正常结束；
• browser/native 共用终止处理后，是否保留了各路径原有的下载结果和错误语义；
• Blob URL 在连接失败、后台断连、中止、非预期消息及回调异常场景下是否都会释放；
• 编辑器模板及中英文公开类型声明是否保持一致。