vgs_test_suites/trae/design.md

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）判定
• 国际化与主题切换