跳到主要内容

ImageViewer resolveExportSrc —— 缺省导出前解析下载地址（WEB-1541）

版本： 0.10.0 · 类型： ✨ 新功能

WEB-1541 · 父 issue：WEB-945 · 来源问题：ANT-1620

问题​

ImageViewer 的导出此前只有两档粒度：缺省内置下载（fetch 成 blob → 同源 objectURL → <a download>，带 cache: 'reload' 绕过被 no-cors <img> 污染的 HTTP 缓存、fetch 失败回退原始地址、objectURL 延迟回收），或传 onExport 完全接管、跳过全部内置逻辑。

而 ANT-1620 的真实需求比两者都窄：web4 录音详情页停留过久（超过预签名 URL 有效期）后下载 Highlight 截图，前端仍用本地缓存的已过期 URL，S3 返回 AccessDenied / Request has expired。此时 <img> 早已加载成功、不会重新请求，viewer 层的失败自愈也不会触发，图仍正常显示。需要变的只有地址，blob / 缓存 / 跨域 / 文件名推断这些行为都应原样保留。

只有 onExport 可用时，消费方必须接管后在组件外重新编排一遍「解析地址 → 下载 → 失败回退」——这是把组件已有的编排复制了一份：日后缺省路径若新增埋点、失败提示或多图支持，消费方那条分支会静默脱节。

改动文件​

  • packages/design/src/components/ImageViewer/ImageViewer.tsx
  • packages/design/src/components/ImageViewer/__tests__/ImageViewer.test.tsx
  • packages/design-site/docs/components/image-viewer.mdx（及 zh-CN 版）

改动内容​

  1. 新增可选 prop resolveExportSrc?: (image, index) => string | null | undefined | Promise<string | null | undefined>，只回答「下哪个地址」。返回地址则用它下载；返回空值或抛错则回退 image.src，与既有 blob fetch 失败回退原地址同一口径，不静默失败。
  2. 缺省导出路径抽出 runDefaultExport(image, index)：在 try / catch 中 await resolveExportSrc，再把结果交给内部下载实现。下载实现（downloadImageBySrc）保持模块内私有，不进公开 API。
  3. 明确优先级：传 onExport 即完全接管，此时 resolveExportSrc 不会被调用。prop 的 JSDoc 与组件文档均写明这一点。
  4. 新增 4 条测试：用解析出的新地址下载、解析返回空值回退 image.src、解析抛错回退 image.src、onExport 接管时完全不调用 resolveExportSrc。
  5. image-viewer.mdx（中英两份）补充第三种导出模式：Props 表新增一行，并扩写「导出下载机制说明」一节。

影响面​

纯新增。不传 resolveExportSrc 时，缺省下载路径与 onExport 接管路径行为均零变化，故定为 minor 而非破坏性变更。注意解析地址期间导出按钮没有 loading 态——与现在下载前 fetch 的等待窗口一致。

首批消费方为 web4 的 HighlightImageAttachment（仅在 URL 已过期时以 picture_link 换签）与 ImageFilePage（经 useSourceUrlSelfHeal.resolveFreshUrl 换签）。两处现在都只保留「要不要换签」这段真正的业务判断，回退语义交由组件的既定契约承担。