前几篇写完项目的整体骨架、路由和房间列表之后，总算要碰一个真正需要“动手填”的界面了。这一篇我们聚焦剧本杀组队App里最核心的入口：发起组队表单。说实话，在很多教程里表单通常被一笔带过，好像就是几个输入框堆在一起而已，但真正把一个表单做好、做稳，涉及的东西远比看起来多。这一篇我就按实际开发中踩过的坑和最终的实现方案，把发起组队表单从需求拆解、控件选型、校验逻辑、状态管理到数据持久化完整过一遍，也重点聊一下Flutter在OpenHarmony设备上的表单适配问题。
如果你是正在用Flutter做OpenHarmony应用，或者准备入坑跨端应用开发，这篇应该能帮你少走不少弯路。就算你没看过系列前面的文章也没关系，这一篇涉及的代码和思路我会从零讲清楚。
1. 发起组队表单的需求拆解与设计思路
1.1 先想清楚表单要收哪些字段
做表单第一步不是写代码，而是列字段。剧本杀组队这个场景下，一个发起人要成功组队，信息必须包含三块：组什么本、什么时候开、需要几个人。除此之外，还有一些锦上添花的字段，比如难度、车队描述、联系方式，这些字段直接影响匹配效率。
我在第一版设计里列出了这几个核心字段：
- 剧本名称：必填，文本输入，长度限制20字以内
- 剧本类型：必填，下拉选择，比如硬核推理、情感沉浸、欢乐机制、恐怖惊悚、古风还原本
- 组队人数：必填，数字选择，支持2到10人
- 开本时间：必填，日期加时间选择，且不能早于当前时间
- 难度要求：选填，滑杆选择，1到5星
- 车头备注：选填，多行文本，比如“新手友好”“可反串”“DM已约好”
- 联系方式：选填，文本输入，校验手机号格式
字段的取舍有个原则：能少则少，但是关键信息不能缺。第一版我加过一个“是否接受跳车补位”的开关，后来想想前期根本不需要这种规则类字段，果断砍掉了。MVP阶段把信息采集做精就好，规则可以等匹配机制上线后再补充。
字段确定之后，每个字段对应什么交互控件也随之确定：
| 字段 | 控件类型 | 是否必填 | 业务原因 |
|---|---|---|---|
| 剧本名称 | TextFormField | 是 | 组队核心标识 |
| 剧本类型 | DropdownButtonFormField | 是 | 决定用户画像 |
| 组队人数 | 自定义Stepper | 是 | 控制组队规模 |
| 开本时间 | InkWell + DatePicker + TimePicker | 是 | 时间错过就无意义 |
| 难度要求 | Slider + 分级文案 | 否 | 辅助筛选，默认1星 |
| 车头备注 | 多行TextFormField | 否 | 补充说明 |
| 联系方式 | TextFormField | 否 | 预留线下沟通渠道 |
1.2 为什么直接用Flutter Form而不是手动维护状态
很多人写表单喜欢给每个TextField配一个TextEditingController，再配一个ValueChanged回调，把值全塞进一个Map里，提交时手动判断每个字段是否为空。这种方式在字段少的时候确实简单直接，但一旦校验规则多起来，代码会变得又长又碎，而且校验逻辑散落在各个回调里，非常难维护。
Flutter原生提供的Form机制就是来解决这个问题的。Form组件通过FormState统一管理子树内所有FormField的状态，包括TextFormField、DropdownButtonFormField这些继承自FormField的组件。我们只需要持有Form的GlobalKey，在提交时调用formKey.currentState.validate()，表单就会自动遍历所有FormField，执行各自配置的validator，并把校验结果汇总返回。有任何一个字段不合法，validate()就会返回false，并把错误文案渲染到对应字段下方。
这套机制最大的好处是“分散配置、统一校验”。每个字段的校验规则就写在它自己的validator里，页面代码只需要关心“触发校验”这一个动作，不用操心错误到底出在哪个字段上。再加上AutovalidateMode，可以在用户输入过程中实时触发校验，交互体验比提交时才弹错误要友好很多。
2. 表单UI布局与控件实现细节
2.1 页面结构与组件拆分
页面整体结构我用了Column加SingleChildScrollView的经典组合。为什么必须套SingleChildScrollView？因为表单项在键盘弹起后很容易超出屏幕可用高度，不包一层滚动视图的话，直接就会触发RenderFlex overflowed报错，在真机上表现为白屏加满屏黄色警告。
看一下最终的页面结构代码：
@override Widget build(BuildContext context) { return Scaffold( appBar: AppBar( title: const Text('发起组队'), centerTitle: true, ), body: SafeArea( child: SingleChildScrollView( padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 12), child: Form( key: _formKey, autovalidateMode: AutovalidateMode.onUserInteraction, child: Column( crossAxisAlignment: CrossAxisAlignment.start, children: [ _buildScriptNameField(), const SizedBox(height: 16), _buildScriptTypeField(), const SizedBox(height: 16), _buildPlayerCountField(), const SizedBox(height: 16), _buildStartTimeField(), const SizedBox(height: 16), _buildDifficultyField(), const SizedBox(height: 16), _buildRemarkField(), const SizedBox(height: 16), _buildContactField(), const SizedBox(height: 32), _buildSubmitButton(), ], ), ), ), ), ); }你可能注意到了，我是一个字段对应一个私有Widget方法。这样做的原因很直接：每个字段的验证逻辑、控制器、回调都封装在各自的方法里，互相不干扰。后面如果要调整某一个字段的UI，只需要看对应的方法就行，不用在一个几百行的build方法里来回找。
2.2 各字段控件的具体实现与选型理由
剧本名称字段没什么特别的，一个标准的TextFormField就够了。关键点在于限制输入长度和trim空白字符。我见过很多用户习惯在文字前后打空格，不处理的话存进数据库的数据会很难看，后面做模糊匹配也容易出问题。
Widget _buildScriptNameField() { return TextFormField( controller: _nameController, maxLength: 20, textInputAction: TextInputAction.next, decoration: const InputDecoration( labelText: '剧本名称', hintText: '例如：病娇男孩的精分日记', border: OutlineInputBorder(), counterText: '', ), validator: (value) { final text = value?.trim() ?? ''; if (text.isEmpty) { return '请填写剧本名称'; } return null; }, ); }把counterText设为空是因为默认的字数计数器在表单里视觉上很吵，我们通过maxLength已经限制了输入长度，不需要再展示计数。
剧本类型字段用DropdownButtonFormField，这是Form体系中少数几个非TextField的FormField组件。需要注意的是，在新版本的Flutter中，DropdownButtonFormField的value参数已经改名成initialValue了，如果还在用旧写法，编译期就会收到deprecation警告。下面的代码用的是当前稳定版的写法：
Widget _buildScriptTypeField() { return DropdownButtonFormField<String>( initialValue: _selectedType, decoration: const InputDecoration( labelText: '剧本类型', border: OutlineInputBorder(), ), items: scriptTypes .map((type) => DropdownMenuItem(value: type, child: Text(type))) .toList(), onChanged: (value) { setState(() => _selectedType = value); }, validator: (value) { if (value == null || value.isEmpty) { return '请选择剧本类型'; } return null; }, ); }组队人数我一开始想用系统默认的Stepper控件，后来发现它的样式太固定，而且点击区域偏小，在国产平板上容易误触。最终我用了自研的加减按钮组合，左侧是减号按钮，右侧是加号按钮，中间显示当前人数。这样视觉上更直观，用户一眼就知道自己能操作什么。
Widget _buildPlayerCountField() { return Row( children: [ const Expanded( child: Text('组队人数', style: TextStyle(fontSize: 16)), ), IconButton.outlined( onPressed: _playerCount > 2 ? () => setState(() => _playerCount--) : null, icon: const Icon(Icons.remove), ), Padding( padding: const EdgeInsets.symmetric(horizontal: 16), child: Text( '$_playerCount人', style: const TextStyle(fontSize: 18, fontWeight: FontWeight.bold), ), ), IconButton.outlined( onPressed: _playerCount < 10 ? () => setState(() => _playerCount++) : null, icon: const Icon(Icons.add), ), ], ); }人数上下限的约束用按钮的enabled状态来体现：到了下限减号置灰，到了上限加号置灰，这比用户按了按钮后弹一个“不能再减了”的提示要友好得多。
开本时间是表单里最复杂的字段，它不是简单的文本输入，而是通过点击弹起日期选择器和时间选择器。我先放一个InkWell包装的显示区域，用户点击后先选日期再选时间，最后把结果拼成一个DateTime对象存到成员变量里。
Widget _buildStartTimeField() { return InkWell( onTap: _pickStartTime, borderRadius: BorderRadius.circular(4), child: InputDecorator( decoration: const InputDecoration( labelText: '开本时间', border: OutlineInputBorder(), ), child: Row( children: [ const Icon(Icons.access_time, size: 20), const SizedBox(width: 8), Text( _startTime == null ? '请选择开本时间' : DateFormat('yyyy-MM-dd HH:mm').format(_startTime!), style: TextStyle( fontSize: 16, color: _startTime == null ? Colors.grey : Colors.black, ), ), ], ), ), ); }这里有个开发小技巧：用InputDecorator包裹自定义的点击区域，可以让它与上方其他表单控件保持完全一致的边框和间距样式，视觉上形成统一的表单风格。
2.3 OpenHarmony环境下的UI适配注意点
标题里写了这是Flutter for OpenHarmony的实战，那么OpenHarmony设备上的适配问题自然绕不开。我实际测试的设备是RK3568开发板，系统是OpenHarmony 3.2 Release，Flutter侧用的是openharmony分支的SDK。整体体验下来，表单这类页面在OpenHarmony设备上比列表页更容易出现UI问题，主要集中在三个方面。
第一是字体缩放。OpenHarmony系统里如果用户把系统字体调到最大，Flutter应用里的文本会等比放大，表单label和输入文本一旦放大，Row布局很容易溢出。旧版本的textScaleFactor已经被废弃，现在推荐用MediaQuery的textScaler，必要的时候可以clamp一下。我就在页面外层包了一个MediaQuery覆盖，把字号限制在正常到1.3倍之间，避免极端字体大小击穿布局。
final mediaQueryData = MediaQuery.of(context); MediaQuery( data: mediaQueryData.copyWith( textScaler: const TextScaler.linear(1.0), ), child: _buildFormContent(context), );这种做法在团队内部争议过一阵，有人觉得限制用户字体大小不友好。我的观点是做应用首先是保证功能可用，剧本杀组队属于工具型页面，信息密度本来就高，字体放大到1.5倍以上整个表单都要滚动很久才能填完，体验反而更差。真要支持大字体，应该重新设计布局，而不是让现有布局被动挤压。
第二是键盘弹起导致表单溢出。Flutter里默认的resizeToAvoidBottomInset是true，也就是键盘弹起时Scaffold会压缩高度，配合SingleChildScrollView就能滚动到被遮挡的字段。这个默认行为在OpenHarmony上大部分时候是正常的，但我在某些版本的三方输入法上遇到过键盘弹起不触发视图压缩的情况，具体表现是底部按钮被键盘挡住完全点不到。排查下来是输入法没有上报inset，Flutter这边收不到通知。临时方案是监听键盘高度变化，手动滚动到聚焦字段：
WidgetsBinding.instance.addObserver( _KeyboardVisibilityObserver( onChanged: (visible) { if (visible) { WidgetsBinding.instance.addPostFrameCallback((_) { Scrollable.ensureVisible( _focusNode.context!, duration: const Duration(milliseconds: 200), alignment: 0.1, ); }); } }, ), );第三是真机性能。RK3568这颗芯片的性能和主流手机芯片还是有差距的，表单页如果有太多的阴影、模糊、半透明效果，滑动时会明显掉帧。我在这个页面上刻意减少了装饰类效果，主要用扁平化的颜色和细边框来区分层级，实测下来在开发板上能稳定在50帧以上，算可以接受的水平。
3. 表单校验与状态管理落地
3.1 憋了一堆校验规则，怎么优雅实现
表单的灵魂在校验。我见过一些项目把所有校验逻辑都堆在提交按钮的onPressed里，几十个if-else层层嵌套，每次加字段都心惊胆战。用Form的validator机制之后，每个字段的校验逻辑都可以独立维护。
除了前面看到的非空校验，还有几个稍微复杂一点的规则值得单独讲。开本时间不能早于当前时间，这个校验比较特殊，因为它不是文本字段，没有现成的validator参数可以用。我的做法是在点击确定时直接判断，如果时间不合法就弹SnackBar提示，并且不更新显示：
Future<void> _pickStartTime() async { final now = DateTime.now(); final date = await showDatePicker( context: context, initialDate: _startTime ?? now, firstDate: now.subtract(const Duration(days: 1)), lastDate: now.add(const Duration(days: 365)), ); if (date == null) return; final time = await showTimePicker( context: context, initialTime: TimeOfDay.now(), ); if (time == null) return; final selected = DateTime(date.year, date.month, date.day, time.hour, time.minute); if (selected.isBefore(now)) { ScaffoldMessenger.of(context).showSnackBar( const SnackBar(content: Text('开本时间不能早于当前时间')), ); return; } setState(() => _startTime = selected); }日期选择器的firstDate可以传入当前时间前一天，这样用户没法通过日历选择过去日期，等于在源头就拦截了一部分非法输入。但时间选择器没法做类似限制，所以提交后的二次校验还是必须有。
联系方式字段的校验则比较常规，用正则匹配手机号格式。这里要考虑一个问题：联系方式是选填字段，用户不填就不校验，填了才检查格式。所以validator里先判空，空则返回null视为合法，非空再走正则：
validator: (value) { final text = value?.trim() ?? ''; if (text.isEmpty) return null; final isPhone = RegExp(r'^1[3-9]\d{9}$').hasMatch(text); if (!isPhone) return '请输入正确的手机号'; return null; },3.2 状态管理：小页面先用setState，别过度设计
发起组队这个页面的状态其实就几个：各个字段的值、校验错误信息、提交按钮是否在loading。这些状态都集中在同一个页面内，没有跨页面共享的需求，所以我在这个页面里坚持用setState，没有引入Provider或者Riverpod。
很多人一看到“状态管理”四个字就条件反射地想上复杂框架，但对于一个单页表单来说这属于过度设计。引入状态管理框架的收益在于跨组件共享状态和逻辑复用，这个页面根本不存在这两个需求。用setState配合StatefulWidget，代码更加直接，新手也能一眼看懂。
提交按钮的可用状态我做了动态控制：所有必填字段都有值、时间不早于当前时间时按钮才可点击。这个逻辑写在build方法里，每次setState都会重新计算：
bool get _isFormValid { final name = _nameController.text.trim(); final type = _selectedType; final time = _startTime; return name.isNotEmpty && type != null && time != null && !time.isBefore(DateTime.now()); }不过要特别强调一点：按钮可用性只是一个交互提示，真正的安全底线是提交时调用validate()。因为_isFormValid这个getter逻辑毕竟只是粗略判断，像联系方式格式这种规则并没有包含在内。我的做法是按钮onPressed里先走validate()，再走一遍isFormValid，两个条件都满足才真正执行提交。
3.3 提交按钮的交互细节
提交按钮的视觉状态做了三种：不可点击时灰色、可点击时主题色、提交中显示转圈。用_statesController创建了一个AnimationController来控制按钮的尺寸变化，点击提交后按钮会稍微缩小并显示一个CircularProgressIndicator，给用户一个明确的反馈。
其实这个效果用ElevatedButton的onPressed里动态判断就够了，不需要动画。我加动画纯粹是产品觉得“提交中”的状态太单调，想做得更有质感。工作量不大，用AnimatedContainer包一下就行：
Widget _buildSubmitButton() { final isLoading = _isSubmitting; return SizedBox( width: double.infinity, height: 52, child: AnimatedContainer( duration: const Duration(milliseconds: 200), child: ElevatedButton( onPressed: isLoading ? null : _submitForm, child: isLoading ? const SizedBox( width: 24, height: 24, child: CircularProgressIndicator(strokeWidth: 2), ) : const Text('发起组队', style: TextStyle(fontSize: 18)), ), ), ); }ElevatedButton在onPressed为null时自动具备置灰效果，不需要额外写disabled样式。转圈的CircularProgressIndicator注意要包一层SizedBox限制尺寸，否则它会试图撑满整个按钮，视觉上会非常怪。
4. 表单提交与数据落地
4.1 提交数据的本地持久化设计
目前这个项目还没有接后端接口，所以发起组队的数据先落到本地存储。我选择了shared_preferences存JSON字符串，而不是直接上一个数据库。原因很现实：现阶段的数据量就是一个人发的组队信息，一条JSON串搞定，用数据库属于杀鸡用牛刀。后期等队伍列表、历史记录、用户系统上线后，再迁移到数据库也不迟。
数据结构设计：
class TeamInfo { final String scriptName; final String scriptType; final int playerCount; final DateTime startTime; final int difficulty; final String remark; final String contact; final DateTime createdAt; Map<String, dynamic> toJson() => { 'scriptName': scriptName, 'scriptType': scriptType, 'playerCount': playerCount, 'startTime': startTime.toIso8601String(), 'difficulty': difficulty, 'remark': remark, 'contact': contact, 'createdAt': createdAt.toIso8601String(), }; factory TeamInfo.fromJson(Map<String, dynamic> json) => TeamInfo( scriptName: json['scriptName'] as String, scriptType: json['scriptType'] as String, playerCount: json['playerCount'] as int, startTime: DateTime.parse(json['startTime'] as String), difficulty: json['difficulty'] as int, remark: json['remark'] as String? ?? '', contact: json['contact'] as String? ?? '', createdAt: DateTime.parse(json['createdAt'] as String), ); }把时间存成ISO8601字符串是必须的好习惯。它能避免时区歧义，而且DateTime.parse可以直接解析，序列化反序列化都不用自己写格式转换。
保存到shared_preferences的代码很简洁：
Future<void> _saveTeamInfo(TeamInfo info) async { final prefs = await SharedPreferences.getInstance(); final existing = prefs.getString('team_list') ?? '[]'; final list = jsonDecode(existing) as List<dynamic>; list.add(info.toJson()); await prefs.setString('team_list', jsonEncode(list)); }读取的时候反过来，把json字符串解析成List再逐个转成TeamInfo。列表页读取这个key就能渲染出用户发过的所有组队信息。
4.2 前端校验通过之后，提交动作的完整闭环
提交动作我拆成了几个步骤，每一步都有明确的职责：
- 调用_formKey.currentState.validate()做整体校验，失败就直接return
- 组装TeamInfo对象
- 设置_isSubmitting = true，按钮进入loading态
- 调用保存函数，写入shared_preferences
- 保存成功后，调用一个轻量的回调通知列表页刷新数据
- 弹出SnackBar提示“组队发布成功”，然后Navigator.pop回上一页
这里有一个细节是，先设loading再执行异步保存，还是保存完再设loading？我选择前者，因为shared_preferences的写入虽然很快，但毕竟是异步操作，如果不先锁住按钮，用户快速连点两次就会写入两条重复数据。
防重复提交的代码：
Future<void> _submitForm() async { if (_isSubmitting) return; if (!_formKey.currentState!.validate()) return; if (!_isFormValid) return; setState(() => _isSubmitting = true); final info = TeamInfo( scriptName: _nameController.text.trim(), scriptType: _selectedType!, playerCount: _playerCount, startTime: _startTime!, difficulty: _difficulty, remark: _remarkController.text.trim(), contact: _contactController.text.trim(), createdAt: DateTime.now(), ); try { await _saveTeamInfo(info); if (!mounted) return; ScaffoldMessenger.of(context).showSnackBar( const SnackBar(content: Text('组队发布成功')), ); Navigator.of(context).pop(true); } catch (e) { if (!mounted) return; setState(() => _isSubmitting = false); ScaffoldMessenger.of(context).showSnackBar( SnackBar(content: Text('保存失败，请重试: $e')), ); } }注意在异步方法里使用context之前要检查mounted，这是Flutter开发中特别容易踩的异步陷阱。如果页面在await期间被用户关闭，mounted会变成false，这时再调Navigator.pop就会崩溃。加上mounted判断不但代码更健壮，也不会在控制台刷出一堆难看的警告。
5. 表单实战中的常见问题与避坑记录
5.1 我在开发中踩过的几个坑
第一个坑是DropdownButtonFormField的value过期问题。旧版本写法是把value参数绑定到一个成员变量，这个变量在做完表单初始化后可能因为异步请求被重新赋值，就会触发“There should be exactly one item with [DropdownButton]'s value”的断言错误，直接红屏。解决方式是升级到新API用initialValue，或者确保items和value始终同步更新。
第二个坑是数字键盘弹出但校验还是不对。人数选择我用的是自研加减按钮而不是文本框，按理说不会触发键盘，但备注和联系方式是文本输入。有些输入法在中文模式下输入英文和数字会自动加空格，如果用户手机号里混入了空格，正则校验直接不通过。这里有个处理技巧：提交时统一对输入做replaceAll(RegExp(r'\s'), '')去掉所有空白字符，再做校验。用户无感知，但能少很多联系方式的投诉。
第三个坑是时间选择器在OpenHarmony上的弹窗异常。showDatePicker在OpenHarmony 3.2上偶尔会出现弹窗背景全透明的情况，字能看见但看不清弹窗边界。排查下来是系统主题适配的问题，Flutter的日期选择器依赖Material主题的surfaceColor，在个别系统版本上这个颜色解析异常。临时解决方案是给MaterialApp主题里显式指定datePickerTheme：
datePickerTheme: DatePickerThemeData( backgroundColor: Colors.grey[50], ),第四个坑是键盘顶起页面导致底部溢出。这个在前面提过，这里再展开一下。我的表单里备注字段在最低端，用户点备注时键盘弹起，SingleChildScrollView会自动滚动Scrollable区域把焦点字段暴露出来。但如果滚动容器里有Margin而不是Padding，滚动后底部会残留一段空白，看起来像是页面内容被顶飞了。这个问题的根源是Column里的SizedBox间距在滚动中被计算在内容高度里，不会造成崩溃但观感很差。解决方法是把间距从SizedBox改成Padding，或者干脆用ListView加itemExtent来精确控制滚动范围。
5.2 问题排查速查表
整理一个我在开发过程中遇到的问题速查表，方便遇到同样问题的人直接对号入座：
| 现象 | 可能原因 | 解决办法 |
|---|---|---|
| 表单无法提交，无任何提示 | validate()返回false但没有错误文案渲染 | 检查是否有字段设置了validator但没放在Form内 |
| 日期选择器背景异常 | 系统主题与Material主题不兼容 | 自定义DatePickerTheme |
| 键盘弹起后按钮被遮挡 | 输入法未上报inset | 监听键盘可见性并手动滚动 |
| 输入中文时字母间出现空格 | 输入法自动补全或联想 | 提交时统一去掉空白字符 |
| 快速点击提交出现两条数据 | 未做防重复处理 | 入口处检查_isSubmitting标志 |
| 页面切后台再回来表单清空 | State被销毁 | 需要持久化处理数据或重写didChangeAppLifecycleState |
5.3 顺手能用的小技巧
最后分享几个表单开发里实测好用的小技巧。
autofillHints可以配合系统自动填充。在联系方式输入框上设置autofillHints: const [AutofillHints.telephoneNumber]，某些输入法会自动识别并让用户快捷填充。不是所有OpenHarmony输入法都支持，但支持的那部分体验会好很多。
textInputAction要按字段顺序配置。剧本名称配TextInputAction.next，键盘右下角会变成“下一项”，点击直接跳到下一个输入框，不用用户手动点击焦点。最后一个字段配TextInputAction.done，点击收起键盘。这个细节虽然小，但对表单填写效率的提升非常明显。
还可以在页面顶上放置一个输入聚焦起点。有些用户不习惯点击输入框再打字，而是打开页面就直接输入。我们可以用FocusNode结合autofocus: true让页面打开后第一个字段自动获取焦点，配合键盘弹起，用户进来就能直接打字。不过这个要谨慎，如果页面有多种进入方式，有些场景自动弹键盘反而会遮挡页面内容。
一些自己的想法
表单页面做到这里，功能上已经可以支撑发起组队这条主流程了。从技术上来说，Flutter Form这套机制设计得确实成熟，把分散的字段、校验、状态收敛到一个统一模型中，代码写起来非常舒服。但真正在实际设备上跑起来之后，还是发现OpenHarmony的适配工作比想象中多，尤其是字体缩放、输入法事件这些细节，不上真机根本发现不了问题。
后面这个项目的计划是先把本地存储的数据做成分页列表展示在首页，等用户反馈跑通之后，再考虑把组队信息同步到远端服务器，同时加上编辑和取消组队的功能。如果到时候真机测试没有问题，我尽量把服务端部分也写成实战文章放出来，毕竟组队App的核心价值一定是在线匹配，光有本地表单是不够的。
