flutter-building-forms

用途：在 Flutter 3.47+ 项目中按统一规范构建表单，覆盖校验、保存、自动填充、焦点顺序与主题样式。明确要求不引入 GetX、flutter_form_builder 或 Expo/RN 表单模式；仓库已有 Form 包装、共享校验器、inputDecorationTheme 或 AutofillGroup 时应扩展而非新建，品牌化界面不套用默认 Material 装饰。\n\n主要能力：\n1) 表单归属：在 State 上持有 final GlobalKey<FormState>，禁止在 build 中分配该 key、FocusNode 或 TextEditingController。提交路径为 if (_formKey.currentState!.validate()) { _formKey.currentState!.save(); }；失败后用 validateGranularly() 再对视觉顺序第一个无效字段 requestFocus()（Set 无序）。\n2) 字段：Form 内需校验或保存的值必须是 TextFormField、DropdownMenuFormField 或自定义 FormField<T>，不可用裸 TextField。validator 为 FormFieldValidator<T>? 返回 String?，需轻量同步；服务端错误放进 forceErrorText（其非空时不调用 validator 且覆盖 errorText，清空后恢复本地校验）。\n3) 自动校验：默认 AutovalidateMode.disabled，首次提交后倾向 onUserInteraction 或 onUnfocus，禁止对必填空字段用 always；不存在 onFocusChange，另有 onUserInteractionIfError。\n4) 样式与布局：通过 ThemeData.inputDecorationTheme 统一；单字段 InputDecoration 只设 labelText、hintText、helperText、prefixIcon。用项目已有 ListView/CustomScrollView 滚动，键盘弹出时裸 Column 会溢出；保留 helper/error 空间避免回流。\n5) 输入与自动填充：每字段设 keyboardType 与 textInputAction（最后一个用 done/go/send 并处理 onFieldSubmitted）；autofillHints 用常量列表，登录 username+password、注册 newUsername+newPassword；同一 AutofillGroup 内客户端需一起构建，成功提交后调用一次 TextInput.finishAutofillContext(shouldSave: true)。\n6) 焦点：首个字段 autofocus，表单包 FocusTraversalGroup；仅当视觉顺序不等于阅读顺序时用 OrderedTraversalPolicy + NumericFocusOrder。\n\n限制与验证：不要在 build 中创建 key/controller/focus node，不跳过 dispose()，不用已废弃的 autovalidate: true，不把 DropdownButtonFormField.value 当 initialValue，不在 lazy ListView 里放任无长期持有者的 controller；需通过 dart analyze / flutter analyze 并覆盖空值、非法、服务端错误与键盘打开等状态。