qzl
01c36eb32e
- 删除 mock_api_client、mock_calendar_service、mock_history_service - 新增 fixed_length_code_input、link_button、message_composer 共享组件 - 优化登录/注册/密码重置页面使用新组件 - 简化 injection.dart 移除 mock 分支 - 更新 env.dart 配置（BACKEND_URL 替换 API_URL） - 后端 agentscope 工具和测试更新 - 重构 AGENTS.md 文档结构 - 新增 deploy/ 目录和 protocol 文档
4.7 KiB
4.7 KiB
Home 输入组件重做设计（HomeComposer Redesign）
1. 目标与范围
1.1 目标
- 解决当前输入组件“质感弱、结构割裂、录音时布局漂移”的问题。
- 统一
+按钮、输入区、右侧动作图标到一个圆角矩形主容器内。 - 保留并复用现有录音、转写、自动发送、停止生成、Toast 错误处理逻辑。
1.2 非目标
- 不改动聊天流、消息发送后端协议、语音识别接口。
- 不改动
+按钮业务行为。 - 不新增独立的页面级浮层录音面板。
2. 问题诊断（现状）
- 当前输入区由多个分离容器拼接，视觉上像“纸片贴上去”。
- 输入框本体和右侧图标视觉上未合为一个整体容器。
- “按住说话”提示与录音动画在主布局外追加，录音时造成结构上下跳动。
3. 方案对比
方案 A：单容器双模式（推荐）
- 单一胶囊主容器承载三段：左操作、中间主内容、右操作。
- 中间区域在文本模式与按住说话模式之间替换（
AnimatedSwitcher）。 - 录音动画仅在中间区域内部切换显示，不改变主容器高度。
优点：结构稳定、状态清晰、维护成本低。
缺点：视觉表达自由度略低于 Overlay 方案。
方案 B：双容器交叉切换
- 文本容器和语音容器完整分离，做交叉淡入。
优点：切换动效可做得更明显。
缺点：状态同步复杂，容易再次出现错位与边界问题。
方案 C：Overlay 浮层
- 保持输入容器不变，录音时叠加浮层。
优点：动画自由度高。
缺点：与“整块替换”诉求不一致，事件命中与无障碍处理更复杂。
结论：采用方案 A。
4. 信息架构与组件边界
4.1 新组件
- 新建
HomeComposer（从home_screen.dart抽离输入区渲染职责）。 HomeScreen继续持有业务状态与行为方法，HomeComposer负责展示与手势分发。
4.2 主容器结构
- 一个圆角矩形主容器（轻拟物胶囊风格）。
- 左侧：
+按钮（行为不变）。 - 中间：
- 文本模式：无边框输入区（文字垂直居中）。
- 语音模式：按住说话按钮区。
- 录音中/识别中：在语音模式内部替换状态内容。
- 右侧：动作图标（声波/键盘/发送/停止）。
5. 状态机设计
5.1 状态定义
- 模式层：
text/holdToSpeak - 过程层：
idle/recording/transcribing
5.2 核心约束
- 主容器高度固定，状态变化不得引发外层布局高度变化。
recording时禁止模式切换，避免状态错位。
5.3 右侧图标决策
- Agent 等待中：停止图标。
- 非等待：
- 有文本：发送图标。
- 无文本且
text：LucideIcons.activity。 - 无文本且
holdToSpeak：LucideIcons.keyboard。
6. 交互与动画
6.1 长按语音流程
onLongPressStart：触发HapticFeedback.lightImpact()，开始录音。onLongPressMoveUpdate：上滑超过阈值，取消录音。onLongPressEnd：未取消则停止录音，转写并自动发送。
6.2 提示文案显示策略
- “松开发送，上滑取消”仅在
recording显示。 - 空闲按住说话模式不显示该提示。
6.3 动画策略
- 模式切换：短时
AnimatedSwitcher（淡入/轻位移）。 - 录音波形：仅在
recording驱动；停止后立刻回收。 - 动画渲染在中间区域内部，不新增外部占位。
7. 视觉规范（Design Tokens）
- 严格使用
apps/lib/core/theme/design_tokens.dart中的AppColors、AppSpacing、AppRadius。 - 禁止硬编码颜色、间距、圆角、尺寸、阴影。
- 主容器采用白色底 + 细边 + 柔和阴影，形成轻拟物层次。
- 输入区内部无额外边框，确保文字垂直居中和图标视觉对齐。
8. 验收标准
- 图标与输入区在同一圆角矩形中，不再分离。
- 录音全流程不出现输入组件上移、下坠或高度抖动。
- 提示文案仅在实际录音中显示。
- 文本/语音模式切换平滑；
+与发送逻辑行为保持一致。
9. 风险与缓解
- 风险：重构过程中影响现有发送/停止生成分支。
- 缓解：优先复用原有行为方法，仅调整 UI 结构与状态映射。
- 风险：手势与模式切换并发导致状态错乱。
- 缓解：录音期间加切换锁，结束后释放。
10. 验证计划
- 手工验证：
- 文本发送、停止生成、
+弹层、语音长按录音、上滑取消、自动发送。 - 文本模式与语音模式往返切换稳定性。
- 文本发送、停止生成、
- Widget 测试（建议新增）：
- 右侧图标状态映射测试。
- 录音中提示文案显示条件测试。
- 模式切换时主容器高度恒定测试。