用途:为 Flutter 应用的表单与文本输入提供一套强制规范,把表单视为小型状态机,分离字段文本、FormState 校验与 ViewModel(网络/时钟)三类职责,减少控制器泄漏、未本地化字符串与卡顿。
主要能力与规则:每个在 State 中创建的 TextEditingController 与 FocusNode 必须在 dispose() 释放,值需跨 widget 存活时改放 Notifier;校验消息必须本地化,返回 AppLocalizations.of(context) 的字段而非硬编码字面量;同步 validator 必须纯且即时,返回 String?,不得含 await/Future/网络;异步校验放到去抖的 Riverpod Notifier,通过 InputDecoration.errorText 呈现,去抖用 dart:async Timer,时间戳取自 clockProvider,不阻塞按键;提交可用性由有效性派生,不单独存 bool;按键只重建单个字段;AutovalidateMode 默认 onUserInteraction;每字段声明 keyboardType、textCapitalization、autofillHints 与 TextInputFormatter 等结构约定;错误需通过语义被朗读,不能只靠颜色。
用法:Form + GlobalKey<FormState> 作为协调点,提交时调用 validate()/save();提交前运行 scripts/check_forms.sh;参考 references/validation-sync-and-async.md 与 references/focus-and-keyboard.md;焦点用 TextInputAction.next/.done 与 onFieldSubmitted 推进,长表单用 SingleChildScrollView 配合 Scaffold 的 resizeToAvoidBottomInset 做键盘避让。
适用场景与限制:适用于 Flutter 表单输入相关实现与代码审查;文档给出反模式如异步 validator、硬编码错误串、在 build() 创建控制器、存 _isValid、always 校验、整表 setState 重建、手写 DateTime.now 去抖等。具体版本、平台限制与完整示例未在资料中说明。