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