front-end-spec.md 12 KB
Agora实时语音转录前端组件 UI/UX 规范
引言
本文档定义了Agora实时语音转录前端组件的用户体验目标、信息架构、用户流程和视觉设计规范。它作为视觉设计和前端开发的基础，确保提供一致且以用户为中心的体验。
总体UX目标与原则
目标用户画像
- 管理员用户：需要高效管理语音转录功能，关注准确性和性能
- 内容编辑者：需要便捷的语音输入转文字功能，关注易用性和转录质量
可用性目标
- 易学性：新用户5分钟内能开始使用语音转录功能
- 使用效率：熟练用户能快速开始/停止转录操作
- 错误预防：清晰的权限提示和错误状态反馈
- 可记忆性：界面直观，功能明确
设计原则
- 清晰性优先 - 转录状态和结果必须清晰可见
- 即时反馈 - 每个操作都有明确的视觉反馈
- 渐进式披露 - 复杂功能按需展示，避免信息过载
- 一致性 - 与现有管理后台设计系统保持一致
- 无障碍设计 - 支持键盘操作和屏幕阅读器
变更日志
| 日期 | 版本 | 描述 | 作者 |
|---|---|---|---|
| 2025-09-23 | 1.0 | 初始规范创建 | Sally (UX专家) |
信息架构
站点地图/屏幕清单
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%
流程图表：
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的流畅动画
设计策略：
- 懒加载非关键资源
- 优化音频处理性能
- 使用虚拟滚动处理长转录历史
- 实现智能缓存策略
后续步骤
立即行动：
- 与利益相关者评审此规范文档
- 在Figma中创建详细的视觉设计
- 与前端开发团队进行设计交接
- 创建原型进行用户测试验证
设计交接清单：
- 所有用户流程已记录
- 组件清单完整
- 无障碍要求已定义
- 响应式策略清晰
- 品牌指南已整合
- 性能目标已确立
本文档由Sally (UX专家) 创建于2025-09-23