1.9 KiB
1.9 KiB
Context
项目里已存在三类视频预览来源：
- 任务结果自带
previewImageUrl/thumbnail - Service Worker 为缓存媒体生成
?thumbnail=预览图 - 无法生成首帧时只能直接依赖
<video>
现状问题不在“完全没有能力”，而在于展示入口未统一复用，导致素材库等高频列表仍走原生 video 首次解码。
Goals
- 降低视频列表和卡片首次渲染成本
- 不让跨域失败导致视频完全不可预览
- 不破坏已有点击播放和原生控制条场景
Non-Goals
- 不改动视频分析器、画布视频节点等重交互播放内核
- 不新增后端缩略图服务
- 不强制为所有远程跨域视频生成首帧
Decision
采用统一策略：
- 优先海报
- 若业务已提供
posterUrl/thumbnail/previewImageUrl，优先直接展示 - 否则对虚拟缓存 URL 使用现有
useThumbnailUrl(..., 'video')
- 失败降级
- 海报图加载失败时自动退回
<video> - 对远程跨域 URL，由于
useThumbnailUrl会返回原视频地址，img失败后自动退回<video>
- 交互分层
- 列表、网格、时间线、任务卡片等场景：默认只展示海报，必要时仅保留播放 icon
- 详情预览、嵌入卡片等可点击播放场景：默认海报，用户点击后切换到
<video controls> - 画布节点、分析工具主预览等必须即时播放/控制的场景：继续直接使用
<video>
Risks
- 某些样式只给
video写了 class，需要同步兼容img - 海报与视频尺寸不一致时可能出现裁切差异
- 远程视频会先经历一次
img失败再退回video，需要避免闪烁过重
Verification
- 本地上传视频首次进入素材库，应优先看到海报而非黑屏或长时间等待
- 远程跨域视频无法抽帧时，应自动退回 video，仍可预览/播放
- 可播放详情场景点击海报后，应切换为可控制的 video