# Agora实时语音转录前端组件 UI/UX 规范

## 引言

本文档定义了Agora实时语音转录前端组件的用户体验目标、信息架构、用户流程和视觉设计规范。它作为视觉设计和前端开发的基础，确保提供一致且以用户为中心的体验。

### 总体UX目标与原则

#### 目标用户画像
- **管理员用户**：需要高效管理语音转录功能，关注准确性和性能
- **内容编辑者**：需要便捷的语音输入转文字功能，关注易用性和转录质量

#### 可用性目标
- 易学性：新用户5分钟内能开始使用语音转录功能
- 使用效率：熟练用户能快速开始/停止转录操作
- 错误预防：清晰的权限提示和错误状态反馈
- 可记忆性：界面直观，功能明确

#### 设计原则
1. **清晰性优先** - 转录状态和结果必须清晰可见
2. **即时反馈** - 每个操作都有明确的视觉反馈
3. **渐进式披露** - 复杂功能按需展示，避免信息过载
4. **一致性** - 与现有管理后台设计系统保持一致
5. **无障碍设计** - 支持键盘操作和屏幕阅读器

### 变更日志
| 日期 | 版本 | 描述 | 作者 |
|------|---------|-------------|--------|
| 2025-09-23 | 1.0 | 初始规范创建 | Sally (UX专家) |

## 信息架构

### 站点地图/屏幕清单

```mermaid
graph TD
    A[管理后台] --> B[语音转录组件]
    B --> B1[转录控制面板]
    B --> B2[实时结果显示]
    B --> B3[转录历史记录]
    B1 --> B1a[开始转录按钮]
    B1 --> B1b[停止转录按钮]
    B1 --> B1c[麦克风状态指示]
    B2 --> B2a[实时转录文本]
    B2 --> B2b[转录准确率指示]
    B2 --> B2c[临时结果vs最终结果]
    B3 --> B3a[历史记录列表]
    B3 --> B3b[转录详情查看]
    B3 --> B3c[导出功能]
```

### 导航结构
- **主导航**：作为管理后台的一个功能模块，集成到现有导航中
- **二级导航**：组件内部的状态切换（实时转录、历史记录、设置）
- **面包屑策略**：管理后台 > 语音转录 > [当前状态]

## 用户流程

### 开始语音转录

**用户目标**：快速开始语音转录并查看实时结果

**入口点**：
- 管理后台语音转录页面
- 特定内容编辑页面的转录快捷入口

**成功标准**：
- 5秒内完成麦克风权限申请和转录准备
- 实时转录延迟小于2秒
- 转录准确率超过90%

**流程图表**：
```mermaid
graph TD
    A[用户点击开始转录] --> B[检查麦克风权限]
    B --> C{权限已授权?}
    C -->|是| D[加入Agora频道]
    C -->|否| E[请求麦克风权限]
    E --> F{用户授权?}
    F -->|是| D
    F -->|否| G[显示权限拒绝提示]
    D --> H[建立WebSocket连接]
    H --> I[开始音频流传输]
    I --> J[接收实时转录结果]
    J --> K[显示转录文本]
    K --> L{用户停止转录?}
    L -->|是| M[清理资源并结束]
    L -->|否| J
```

**边缘情况与错误处理**：
- 网络连接失败：显示重连选项和错误提示
- WebSocket连接中断：自动重连机制
- 麦克风设备不可用：提供设备选择或错误指导
- 转录服务超时：显示超时提示和重新开始选项

**注意事项**：需要特别关注权限申请的用户体验，避免过于侵入式的提示

## 线框图与原型

**主要设计文件**：建议使用 Figma 进行详细视觉设计

### 关键屏幕布局1：转录控制面板

**用途**：用户开始和管理语音转录的主要界面

**关键元素**：
- 大型开始/停止转录按钮（视觉状态明显区分）
- 实时音频波形可视化
- 转录文本显示区域（支持滚动和复制）
- 麦克风状态和连接状态指示器
- 转录准确率和延迟指标
- 历史记录快捷入口

**交互说明**：
- 开始按钮点击后变为停止按钮，伴有动画过渡
- 音频波形实时反映语音输入强度
- 转录文本区域支持文本选择和复制操作
- 状态指示器使用颜色编码（绿色=正常，黄色=警告，红色=错误）

**设计文件参考**：Figma链接待创建

### 关键屏幕布局2：转录历史记录

**用途**：查看和管理已完成的转录记录

**关键元素**：
- 转录记录列表（时间、时长、准确率）
- 搜索和筛选功能
- 批量操作选项（删除、导出）
- 转录详情查看模态框
- 导出格式选择（TXT、JSON、Word）

**交互说明**：
- 列表支持按时间、准确率排序
- 点击记录项展开详情视图
- 批量选择支持多选操作
- 导出功能提供进度指示

**设计文件参考**：Figma链接待创建

## 组件库/设计系统

**设计系统方法**：基于现有的 shadcn/ui 设计系统进行扩展，确保与整个管理后台的设计一致性

### 核心组件1：转录控制按钮

**用途**：开始和停止语音转录的主要交互控件

**变体**：
- 主要状态：开始（绿色）、停止（红色）、禁用（灰色）
- 尺寸：大号（主要控制）、小号（嵌入式使用）
- 图标变体：带麦克风图标、纯文本、图标+文本

**状态**：
- 默认：准备开始转录
- 悬停：视觉反馈，显示工具提示
- 激活：转录进行中，带有脉冲动画
- 禁用：权限未授权或设备不可用
- 加载：初始化转录服务中

**使用指南**：
- 在转录控制面板中作为主要操作控件
- 使用足够大的点击区域（最小44px）
- 状态变化必须有明确的视觉反馈
- 禁用状态需要提供明确的启用指导

### 核心组件2：实时转录文本显示

**用途**：显示实时语音转录的文字结果

**变体**：
- 实时模式：区分临时结果和最终结果
- 历史模式：只读的已完成转录
- 编辑模式：支持文本修改和标注

**状态**：
- 空状态：显示引导文本或占位符
- 加载中：显示加载指示器
- 实时更新：文本逐字显示，带有打字机效果
- 完成状态：完整的转录文本，支持复制

**使用指南**：
- 实时模式使用不同颜色区分临时/最终结果
- 提供文本复制和导出功能
- 支持文本选择和基本编辑操作
- 确保足够的行高和可读性

### 核心组件3：音频波形可视化

**用途**：实时显示音频输入强度和活动状态

**变体**：
- 条形图：垂直条形显示音频强度
- 波形图：连续的波形显示
- 简约版：简单的活动指示器

**状态**：
- 静音：显示基线或静音提示
- 活动：根据音频强度动态变化
- 峰值：达到最大音量时的视觉反馈
- 错误：音频输入失败的特殊显示

**使用指南**：
- 与转录状态同步更新
- 使用颜色编码表示不同状态
- 提供平滑的动画过渡
- 考虑性能影响，避免过度渲染

## 品牌与样式指南

**品牌指南**：遵循现有管理后台的品牌规范

### 色彩调色板

| 色彩类型 | 十六进制代码 | 用途 |
|---------|-------------|------|
| 主色 | #2563eb | 主要操作按钮、重要状态指示 |
| 辅助色 | #64748b | 次要元素、边框、文本 |
| 强调色 | #f59e0b | 警告状态、需要关注的元素 |
| 成功色 | #10b981 | 转录成功、完成状态 |
| 警告色 | #f59e0b | 权限提示、临时状态 |
| 错误色 | #ef4444 | 错误状态、转录失败 |
| 中性色 | #6b7280, #9ca3af, #d1d5db | 文本、边框、背景 |

### 字体排印

**字体家族**：
- **主字体**：Inter（系统默认无衬线字体）
- **辅助字体**：系统默认字体栈
- **等宽字体**：JetBrains Mono（用于代码和转录文本）

**字体比例**：
| 元素 | 大小 | 字重 | 行高 |
|------|------|------|------|
| H1 | 2rem | 600 | 1.2 |
| H2 | 1.5rem | 600 | 1.3 |
| H3 | 1.25rem | 600 | 1.4 |
| 正文 | 1rem | 400 | 1.5 |
| 小字 | 0.875rem | 400 | 1.4 |

**图标设计**：
- **图标库**：Lucide React图标库
- **使用指南**：使用简洁的线条图标，保持一致的视觉权重

**间距与布局**：
- **网格系统**：12列响应式网格，使用Tailwind CSS间距系统
- **间距比例**：基于0.25rem的倍数（4px、8px、12px、16px、20px、24px、32px、40px、48px）

## 无障碍设计要求

**合规标准**：WCAG 2.1 AA级别

**关键要求**：

**视觉要求**：
- 色彩对比度：文本与背景至少4.5:1，大文本3:1
- 焦点指示：所有可交互元素必须有清晰的焦点环
- 文本大小：支持浏览器字体缩放至200%

**交互要求**：
- 键盘导航：支持完整的键盘操作（Tab、Enter、Space、Esc）
- 屏幕阅读器支持：为所有状态变化提供ARIA标签
- 触摸目标：最小44px触摸区域

**内容要求**：
- 替代文本：所有图标和状态指示器必须有描述性文本
- 标题结构：使用正确的HTML标题层级
- 表单标签：所有输入控件必须有相关联的标签

**测试策略**：
- 使用axe-core进行自动化测试
- 手动键盘导航测试
- 屏幕阅读器兼容性测试（NVDA、VoiceOver）
- 色彩对比度工具验证

## 响应式策略

**断点设置**：

| 断点 | 最小宽度 | 最大宽度 | 目标设备 |
|------|----------|----------|----------|
| 移动端 | 320px | 767px | 智能手机、小屏设备 |
| 平板 | 768px | 1023px | 平板电脑、大屏手机 |
| 桌面端 | 1024px | 1439px | 笔记本电脑、标准显示器 |
| 宽屏 | 1440px | - | 大屏显示器、电视 |

**适配模式**：

**布局变化**：
- 移动端：单列布局，控制面板和结果区域垂直堆叠
- 平板：两列布局，控制面板固定宽度，结果区域自适应
- 桌面端：三列布局，包含控制面板、实时结果、历史记录

**导航变化**：
- 移动端：底部标签栏导航，隐藏次要功能
- 平板：侧边栏导航，支持展开/收起
- 桌面端：完整导航栏，所有功能可见

**内容优先级**：
- 移动端：优先显示转录控制和实时结果
- 平板：增加历史记录快捷入口
- 桌面端：完整功能展示，支持多任务操作

**交互变化**：
- 移动端：简化操作，减少点击深度
- 平板：支持手势操作（滑动切换）
- 桌面端：完整的键盘快捷键支持

## 动画与微交互

**动效原则**：
- 功能性优先：动画服务于用户体验，而非装饰
- 性能友好：确保动画流畅，不影响转录性能
- 可访问性：提供减少动画的选项
- 一致性：使用统一的动画时长和缓动函数

**关键动画**：
- **转录状态切换**：按钮状态平滑过渡，带有缩放效果（时长：300ms，缓动：ease-out）
- **音频波形**：实时音频输入的可视化波动（时长：实时，缓动：linear）
- **文本显示**：转录结果的逐字显示效果（时长：根据文本长度，缓动：ease-in-out）
- **加载状态**：旋转指示器和进度条（时长：不定，缓动：linear）
- **错误提示**：轻微震动和颜色闪烁（时长：500ms，缓动：ease-in-out）

## 性能考虑

**性能目标**：
- **页面加载**：组件初始化时间小于3秒
- **交互响应**：用户操作响应时间小于100ms
- **动画帧率**：保持60fps的流畅动画

**设计策略**：
- 懒加载非关键资源
- 优化音频处理性能
- 使用虚拟滚动处理长转录历史
- 实现智能缓存策略

## 后续步骤

**立即行动**：
1. 与利益相关者评审此规范文档
2. 在Figma中创建详细的视觉设计
3. 与前端开发团队进行设计交接
4. 创建原型进行用户测试验证

**设计交接清单**：
- [ ] 所有用户流程已记录
- [ ] 组件清单完整
- [ ] 无障碍要求已定义
- [ ] 响应式策略清晰
- [ ] 品牌指南已整合
- [ ] 性能目标已确立

---

*本文档由Sally (UX专家) 创建于2025-09-23*