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