109 lines
4.8 KiB
Markdown
109 lines
4.8 KiB
Markdown
# UI 指导文档：WebCodecs AVC/HEVC 判定单页
|
||
|
||
本页旨在用 React + TailwindCSS + shadcn/ui + TypeScript + Vite 实现“当前页面是否支持 WebCodecs 的 AVC 与 HEVC”的判定与展示。仅做能力判定与结果呈现，不进行视频解码、上传、登录等额外功能。
|
||
|
||
## 1. 目标与范围
|
||
- 目标：清晰、可靠地展示浏览器对 WebCodecs、AVC(H.264) 与 HEVC(H.265) 的支持状态。
|
||
- 范围：
|
||
- 首屏自动判定，并支持手动“重新检测”。
|
||
- 展示支持、非支持、未知三种状态，并提供详细信息（环境、判定过程、错误）。
|
||
- 仅单页应用，无路由与多页结构。
|
||
- 非目标：
|
||
- 不做实际视频解码/播放。
|
||
- 不做账号、权限、国际化切换等。
|
||
|
||
## 2. 信息架构与布局
|
||
- 顶部：标题与简述
|
||
- 标题：WebCodecs 编码能力判定
|
||
- 说明：展示当前环境对 WebCodecs、AVC 与 HEVC 的支持情况
|
||
- 核心卡片（DetectorCard）：
|
||
- 总览状态行：
|
||
- WebCodecs：可用/不可用
|
||
- AVC(H.264)：支持/不支持/未知
|
||
- HEVC(H.265)：支持/不支持/未知（重点关注）
|
||
- 操作区：
|
||
- 按钮：重新检测（Button）
|
||
- 按钮：复制检测详情（Button，可选）
|
||
- 详情折叠区（可展开）：
|
||
- 环境信息：UA、`isSecureContext`、平台信息
|
||
- 判定细节：各 `VideoDecoder.isConfigSupported` 的输入与返回
|
||
- 错误信息：异常堆栈、失败原因
|
||
- 底部：
|
||
- 兼容性声明与提示链接（例如参考文档）
|
||
|
||
## 3. 组件清单与样式（shadcn/ui + Tailwind）
|
||
- Card：`<Card> <CardHeader> <CardTitle> <CardContent>` 用于包裹判定结果
|
||
- Badge：用于标识状态
|
||
- 成功（支持）：绿色 `bg-emerald-500` / shadcn `variant="default"` + `text-white`
|
||
- 失败（不支持）：红色 `bg-red-500` / `variant="destructive"`
|
||
- 未知：琥珀色或灰色 `bg-amber-500`/`bg-gray-500`
|
||
- Button：主要（重新检测）、次要（复制详情）
|
||
- Separator：分隔信息块
|
||
- Collapsible / Accordion：用于展开判定详情
|
||
- Alert（可选）：在 WebCodecs 不可用或非安全上下文时提示
|
||
|
||
Tailwind 约定：
|
||
- 容器宽度：`max-w-2xl mx-auto px-4`；移动优先布局。
|
||
- 字体与层级：标题 `text-xl font-semibold`，正文 `text-sm text-muted-foreground`。
|
||
- 状态色统一：支持=绿色、失败=红色、未知=琥珀/灰。
|
||
|
||
## 4. 状态与数据流
|
||
- 数据源：`utils/codecs` 封装的检测函数（Promise）
|
||
- 类型（页面侧以只读消费）：
|
||
- `CodecStatus = 'supported' | 'unsupported' | 'unknown'`
|
||
- `CodecSupport`：
|
||
- `webCodecs: boolean`
|
||
- `avc: CodecStatus`
|
||
- `hevc: CodecStatus`
|
||
- `details: { env, checks, errors, timestamp }`
|
||
- 生命周期：
|
||
- 初次渲染：显示加载状态（Skeleton/Spinner），完成后渲染结果。
|
||
- 重新检测：刷新整个检测流程并更新时间戳。
|
||
- 错误：捕获并在详情区展示，页面用 Alert 简述。
|
||
|
||
## 5. 交互流程（主要场景）
|
||
1) 首屏加载：
|
||
- 调用 `detectAll()` -> 返回 `CodecSupport`
|
||
- 显示三行状态（WebCodecs/AVC/HEVC）与详情入口
|
||
2) 用户点击“重新检测”：
|
||
- 再次调用 `detectAll()`，展示加载与最新结果
|
||
3) 用户点击“复制检测详情”（可选）：
|
||
- 将 `details` 序列化为 JSON 并复制至剪贴板
|
||
|
||
## 6. 响应式与可访问性
|
||
- 响应式：
|
||
- 移动端：单列卡片；按钮占满或并排但保持可点击区域
|
||
- 桌面端：保持居中与合理留白
|
||
- 可访问性：
|
||
- 所有交互元素有可见焦点态（Tailwind focus 样式）
|
||
- 状态色同时提供文本标签（如“支持/不支持/未知”），避免仅靠颜色传达
|
||
- 按钮加上 `aria-label`
|
||
|
||
## 7. 文案与视觉规则
|
||
- 标题：`WebCodecs 编码能力判定`
|
||
- 说明：简述仅判定能力，不做解码测试
|
||
- 状态行文案：
|
||
- WebCodecs：`可用`/`不可用`
|
||
- AVC(H.264)：`支持`/`不支持`/`未知`
|
||
- HEVC(H.265)：`支持`/`不支持`/`未知`
|
||
- 详情区：
|
||
- 环境信息：UA、安全上下文、平台
|
||
- 判定过程：每次 `isConfigSupported` 的输入与输出
|
||
- 错误：异常消息与堆栈（裁剪）
|
||
|
||
## 8. 错误与边界情况提示
|
||
- 非安全上下文（`!isSecureContext`）：提示必须在 HTTPS 下使用 WebCodecs
|
||
- 浏览器不支持 WebCodecs（如部分 Firefox）：
|
||
- 顶部 Alert 提示不支持 WebCodecs
|
||
- AVC/HEVC 状态标为 `未知`
|
||
- HEVC 平台依赖性强：不同系统/浏览器的结果可能不同；详情区给出判定依据
|
||
|
||
## 9. 组件映射到目录结构
|
||
- 页面：`src/App.tsx`（单页）
|
||
- 组件：`src/components/DetectorCard.tsx`（包含状态、操作与详情）
|
||
- 工具：`src/utils/codecs/*`（判定逻辑与类型）
|
||
|
||
## 10. 未来扩展（暂不实现）
|
||
- 导出检测报告 JSON
|
||
- 增加更多编码（VP9/AV1）判定
|
||
- 国际化与主题切换 |