flutter-bloc-forms

使用 BLoC 构建表单架构

• 在专用的 FormBloc 中管理表单状态（而不是在 widget 的 setState 中）
• 每个表单字段都对应 BLoC 状态中的一个属性
• 根据 UX 需求，在字段变化时（实时）或提交时（批量）进行验证
• 在提交流程中发出 FormSubmitting、FormSuccess、FormError 状态

表单事件

• FieldChanged(field, value)：更新状态中的单个字段
• FormSubmitted：触发验证和提交
• FormReset：清除所有字段和错误

表单状态

• 使用一个包含所有字段值、字段级错误和表单状态的状态类：

  sealed class FormStatus { initial, submitting, success, failure }
  

• 字段错误：使用以字段名为键的 Map<String, String?>（null 表示有效）

验证模式

• 在领域层进行验证（不要在 widget 或 BLoC 中验证）
• 创建返回 String? 的纯验证函数（null = 有效，字符串 = 错误消息）：

  String? validateEmail(String value) =>
    value.contains('@') ? null : 'Invalid email';
  

• 组合验证器：String? validate(String v) => validateRequired(v) ?? validateEmail(v)
• 使用 context.l10n 提供本地化错误消息：不要硬编码验证文案

输入控件

• 使用 TextFormField 和 InputDecoration，确保样式一致
• 始终设置 textInputAction，确保键盘行为正确（next、done）
• 始终设置与字段类型匹配的 keyboardType（emailAddress、phone、number）
• 使用 inputFormatters 限制输入（例如，FilteringTextInputFormatter.digitsOnly）
• 为每个表单字段分配 Key('feature_fieldName')，以便在测试中访问
• 在登录／注册表单中使用 AutofillHints（email、password、name）
• 使用 Focus 或 FocusTraversalGroup 包裹表单字段，确保 Tab 顺序正确

控制器生命周期

• 在 initState() 中将 TextEditingController 声明为 late final，并在 dispose() 中释放
• 通过 onChanged 回调或控制器监听器将控制器状态同步到 BLoC

表单提交

• 当 FormStatus.submitting 时禁用提交按钮，防止重复提交
• 在每个字段下方显示内联字段错误（不要只显示在顶层）
• 成功时：导航、显示成功反馈；如果仍停留在同一页面，则重置表单
• 失败时：通过 SnackBar 或内联方式显示错误反馈，并保留表单数据

常见表单模式

• 搜索：在搜索事件上使用 debounce 转换器（延迟 300-500ms）
• 多步骤：每个步骤都是同一个 FormBloc 中独立的表单状态，并单独验证
• 依赖字段：在 on<FieldChanged> 处理器中更新依赖字段的选项（例如，国家 → 城市）