1. 先拆需求：发起组队表单到底在解决什么问题
做剧本杀组队类产品的人应该都有感触：用户从“有玩一局的念头”到“真正把车组起来”，中间最劝退的环节往往不是刷列表，而是发起组队那一刻要填的那张表单。这张表单如果字段太多、校验太严、交互卡顿，用户大概率直接退出；如果字段太少、信息残缺，后面匹配和上车又全是沟通成本。所以“发起组队表单”这个页面，是整个App发布链路里含金量最高的一环。
这一期实战就围绕这个页面展开，用 Flutter 在 OpenHarmony 设备上实现一个可用的发起组队表单。内容包括字段设计、Form 校验、日期时间联动、相册选图、提交反馈，以及我在 OpenHarmony 适配过程中踩过的几个典型坑。适合正在做 Flutter 跨端项目、尤其是要同步跑 OpenHarmony 的同学参考。
1.1 一局剧本杀组队需要哪些核心信息
表单设计的第一步永远是信息架构，而不是写代码。我按“发布后别人看到什么、决定是否上车”来逆推字段，最后收敛成下面这张表：
| 字段 | 控件类型 | 是否必填 | 校验规则 | 设计理由 |
|---|---|---|---|---|
| 剧本名 | 文本框 | 是 | 非空，2-30字 | 列表页主展示信息，直接决定点击率 |
| 剧本类型 | 下拉框 | 是 | 非空 | 用户筛选和检索的主要维度 |
| 开本时间 | 日期+时间联动 | 是 | 不能早于当前时间 | 组队最核心的约束条件 |
| 所在区域 | 文本框 | 是 | 非空 | 剧本杀有强线下属性，距离决定意愿 |
| 组队人数 | 下拉框 | 是 | 4-12人常用档位 | 不同本人数需求差异大，枚举比手输更稳 |
| 人均费用 | 文本框 | 否 | 数字，0-999 | 空值表示面议 |
| 联系方式 | 文本框 | 是 | 手机号或微信号 | 线下成团必须留联系方式，但要做隐私提示 |
| 备注 | 多行文本 | 否 | 100字以内 | 放“新手友好”“车友自取”等软信息 |
这几个字段没有一个是多余的。剧本名和类型解决“玩什么”，时间解决“什么时候”，区域解决“在哪”，人数和费用解决“能不能拼”，联系方式解决“怎么联系”，备注是给老玩家留的发挥空间。做过撮合类产品就会知道，字段每多一个，发布转化率就掉一截，所以我在这个页面上刻意砍掉了类似“性别偏好”“语音条”“封面必传”这类高门槛项，把封面图做成可选。
1.2 技术选型：为什么这里用 Flutter 而不是 ArkUI
既然目标是 OpenHarmony，自然会有人问：为什么不用 OpenHarmony 的原生声明式框架 ArkUI？我的理由是项目并不仅仅跑 OpenHarmony。同一套登录、组队、消息模块，Android 和 iOS 也有发行需求，Flutter 一套 Dart 代码可以覆盖三端，团队不需要拆成两组人维护同一份业务逻辑。表单页这种交互密集、状态明确、重 UI 轻硬件调用的场景，恰好是 Flutter 最擅长的领域，没必要在 ArkUI 里再写一遍。
另外，Flutter 的表单三件套 Form、TextFormField、Validator 在这个场景下非常成熟，Material 组件库里的 DatePicker、Dropdown、SnackBar 开箱即用，开发效率明显高于手写状态机。当然这不是说 OpenHarmony 原生不行，只是在“一次编写、多端分发”这个前提下，Flutter 的综合成本更低。代价是工程结构里会多一个 ohos 适配层，打包产物变成 hap，这部分我在后面单独讲。
2. 页面骨架与表单状态设计
表单类页面的骨架设计有一个很容易被新手忽略的原则：先想清楚状态从哪里来、到哪里去，再动手铺 UI。我这个页面用最简单的 StatefulWidget 加 setState，没有引入 Provider 或 Riverpod，原因是这个页面的状态边界非常清晰——一堆控制器、一个表单校验器、一个提交中标记，setState 完全够用。等后期页面之间需要共享车队数据时，再升级到统一状态管理不迟。
2.1 控制器与 FormKey
页面的状态可以分成两类。一类是“用户正在输入的值”，用 TextEditingController 持有，另一类是“用户已经选择的值”，比如剧本类型、人数、开本时间，用普通成员变量持有。下面是初始化骨架：
class CreateTeamPage extends StatefulWidget { const CreateTeamPage({super.key}); @override State<CreateTeamPage> createState() => _CreateTeamPageState(); } class _CreateTeamPageState extends State<CreateTeamPage> { final _formKey = GlobalKey<FormState>(); final _scriptNameController = TextEditingController(); final _contactController = TextEditingController(); final _feeController = TextEditingController(); final _remarkController = TextEditingController(); final _regionController = TextEditingController(); String? _scriptType; String? _playerCount; DateTime _startTime = DateTime.now().add(const Duration(hours: 2)); bool _submitting = false; @override void dispose() { _scriptNameController.dispose(); _contactController.dispose(); _feeController.dispose(); _remarkController.dispose(); _regionController.dispose(); super.dispose(); } }注意两点。一是所有控制器都要在 dispose 里释放，否则页面频繁进出时会造成内存驻留，这在 OpenHarmony 这类需要严格控制资源占用的设备上更明显。二是 _startTime 的初始值我给了“当前时间 + 2 小时”，这样用户如果直接不改时间，默认值也在合理区间，避免提交时再被“时间早于现在”的校验拦住，体验会顺很多。
2.2 滚动与键盘避让策略
表单页必然要面对软键盘。这里我采用的做法是让整个表单放在 SingleChildScrollView 里，页面本身不设置 resizeToAvoidBottomInset，用底部 padding 手动补偿键盘高度：
@override Widget build(BuildContext context) { final bottomInset = MediaQuery.of(context).viewInsets.bottom; return Scaffold( appBar: AppBar(title: const Text('发起组队')), body: SingleChildScrollView( padding: EdgeInsets.fromLTRB(16, 16, 16, bottomInset + 24), child: Form( key: _formKey, autovalidateMode: AutovalidateMode.onUserInteraction, child: Column( crossAxisAlignment: CrossAxisAlignment.start, children: [ _buildScriptNameField(), // ...其余字段 _buildSubmitButton(), ], ), ), ), ); }这里的关键是把 resizeToAvoidBottomInset 交给 SingleChildScrollView 配合 bottomInset 处理，而不是让 Scaffold 自动压缩。遇到文本输入框被键盘遮挡、按钮点不到的问题，先看这一层，大多数情况是底部 padding 没加够。我实际测试中，OpenHarmony 设备上输入法高度跟 Android 略有差异，用 viewInsets.bottom 动态补偿是最稳的，写死一个 300 或者 400 容易在某台设备上多空或少空。
3. 字段实现细节与校验规则
表单页最花时间的其实不是布局，是校验规则怎么写得既温和又有用。我的原则是：错误提示要具体到“用户下一步该做什么”，不能所有字段都用一句“格式错误”糊弄。另外，本地校验只是第一道防线，它的目的是缩短反馈循环，真正拦住脏数据的必须是服务端，这一点后面提交逻辑里还会强调。
3.1 文本输入与正则校验
剧本名是最直接的文本字段，校验就是非空加长度控制。关键是把 trim 放在判断之前，否则用户输入几个空格也会被当成有效内容：
Widget _buildScriptNameField() { return TextFormField( controller: _scriptNameController, maxLength: 30, decoration: const InputDecoration( labelText: '剧本名', hintText: '例如：一桩事先张扬的凶案', counterText: '', border: OutlineInputBorder(), ), validator: (value) { final text = value?.trim() ?? ''; if (text.isEmpty) return '请填写剧本名'; if (text.length < 2) return '剧本名至少2个字'; return null; }, ); }联系方式字段我做了双规则匹配，兼容手机号和微信号两种可能，并且会明确告诉用户支持哪两种格式：
String? _validateContact(String? value) { final text = value?.trim() ?? ''; if (text.isEmpty) return '请留下联系方式'; final isPhone = RegExp(r'^1\d{10}$').hasMatch(text); final isWechat = RegExp(r'^[a-zA-Z][a-zA-Z0-9_-]{5,19}$').hasMatch(text); if (!isPhone && !isWechat) { return '请输入11位手机号或6-20位微信号'; } return null; }费用字段比较特殊，它是可选项，留空表示面议，所以校验逻辑要先判断是否为空，空就直接放过，非空才走数字和范围判断。这里用 int.tryParse 而不是 int.parse 可以安全捕获转换异常，不需要写 try-catch 也能避免崩溃：
String? _validateFee(String? value) { if (value == null || value.trim().isEmpty) return null; final fee = int.tryParse(value.trim()); if (fee == null) return '人均费用只能填数字'; if (fee < 0 || fee > 999) return '费用范围是0-999元'; return null; }3.2 下拉选择与动态联动
剧本类型和人数都用 DropdownButtonFormField，好处是用户不需要敲键盘，选择即有效，天然降低脏数据比例。我把选项定义成常量，一个在代码顶部维护，后续加剧本类型只改一处：
const scriptTypeOptions = ['恐怖本', '还原本', '情感本', '阵营本', '机制本', '欢乐本']; const playerCountOptions = ['4人局', '5人局', '6人局', '7人局', '8人局', '9人局', '10人局', '12人局'];下拉的 validator 同样要写，因为初始值为空时直接提交，Form 会认为这个字段没值：
DropdownButtonFormField<String>( initialValue: _scriptType, decoration: const InputDecoration( labelText: '剧本类型', border: OutlineInputBorder(), ), items: scriptTypeOptions .map((e) => DropdownMenuItem(value: e, child: Text(e))) .toList(), onChanged: (v) => setState(() => _scriptType = v), validator: (v) => v == null ? '请选择剧本类型' : null, )这里有个版本差异需要提一下：较新版本的 Flutter 中 DropdownButtonFormField 的 value 参数改成了 initialValue，如果你在某个分支上还看到 value 参数被标废弃，不要慌，功能没变，按编译器提示改一下就行。组队人数目前是静态枚举，但如果后面要做“根据剧本类型推荐默认人数”这类联动，只要把 items 变成计算属性即可，这个结构已经留好了扩展位。
3.3 日期时间联动选择器
开本时间是我在这个页面上花注意力最多的字段。用户需要先选日期、再选时间，而且日期不能是过去时间。Flutter 自带的 showDatePicker 和 showTimePicker 都是 Material 组件，在 OpenHarmony 适配版上也能正常跑，只是需要把本地化配置配好，这个我在第五章踩坑里细说。
先看实现：
Future<void> _selectStartTime() async { final now = DateTime.now(); final pickedDate = await showDatePicker( context: context, initialDate: _startTime, firstDate: now, lastDate: now.add(const Duration(days: 30)), helpText: '选择开本日期', cancelText: '取消', confirmText: '确定', ); if (pickedDate == null || !mounted) return; final pickedTime = await showTimePicker( context: context, initialTime: TimeOfDay.fromDateTime(_startTime), helpText: '选择开本时间', cancelText: '取消', confirmText: '确定', ); if (pickedTime == null) return; setState(() { _startTime = DateTime( pickedDate.year, pickedDate.month, pickedDate.day, pickedTime.hour, pickedTime.minute, ); }); }lastDate 限制在 30 天内，这是产品层面的考虑：剧本杀的局很少有人提前一个多月预定，放开反而增加无效选择。firstDate 直接取 now，从机制上杜绝选到过去日期。组装 DateTime 时分开取年月日和时分，避免直接用 DateTime 的 copyWith 在某些时区边界下出现日期错位的问题。选中后在 UI 上用一行只读文本来展示，比如“11月20日 周六 19:30 开本”，点击整行都会触发选择器，命中区域比单独的小按钮大很多，移动端上这很重要。
3.4 封面图与相册权限（可选字段）
封面图我设计成可选，但提供了明显的“添加封面”占位块，用户点击后从相册选一张图。有封面的车队在列表页曝光效果明显好于纯文字，所以引导要给足，但权限成本不能变成必填门槛。
实现上我用 image_picker，在 OpenHarmony 工程里需要换成适配过 image_picker_ohos 的产物，代码层面的 API 基本一致：
File? _coverFile; Future<void> _pickCover() async { try { final picked = await ImagePicker().pickImage(source: ImageSource.gallery); if (picked == null) return; setState(() => _coverFile = File(picked.path)); } catch (e) { ScaffoldMessenger.of(context).showSnackBar( const SnackBar(content: Text('相册打开失败，请检查权限设置')), ); } }关键点是权限配置。OpenHarmony 上读相册需要对应权限，在 ohos 模块的 module.json5 里声明请求列表。不同 API 版本媒体权限名称有差异，我在实践里使用过 READ_IMAGEVIDEO 这类细分权限，也在旧版本上用过 READ_MEDIA，建议以你对接的 SDK 版本为准，在官方权限说明里确认后再写入配置。权限被拒绝时用户看到的就是上面那个 SnackBar，不会崩，也不会让整个表单不可用。
4. 提交流程与结果反馈
表单校验只是前半程，用户点了“发布”之后发生什么，决定了他对这个页面最后的印象。我在提交环节重点做了三件事：数据清洗、加载态、失败兜底。
4.1 数据装配与清洗
校验通过后不直接拿 controller.text 拼请求，先做一层清洗。主要工作是 trim 掉首尾空格、把费用字符串转成 int、空值转 null、时间统一转成 ISO8601 字符串。这样后端拿到的数据结构是干净且自解释的。
Future<void> _submit() async { if (_submitting) return; if (!_formKey.currentState!.validate()) return; setState(() => _submitting = true); final payload = <String, dynamic>{ 'scriptName': _scriptNameController.text.trim(), 'scriptType': _scriptType, 'startTime': _startTime.toIso8601String(), 'region': _regionController.text.trim(), 'playerCount': _playerCount, 'fee': _feeController.text.trim().isEmpty ? null : int.parse(_feeController.text.trim()), 'contact': _contactController.text.trim(), 'remark': _remarkController.text.trim(), 'coverPath': _coverFile?.path, }; final ok = await _publishTeam(payload); if (!mounted) return; setState(() => _submitting = false); if (ok) { Navigator.of(context).pop(true); ScaffoldMessenger.of(context).showSnackBar( const SnackBar(content: Text('车队已发布，等待小伙伴上车')), ); } else { ScaffoldMessenger.of(context).showSnackBar( const SnackBar(content: Text('发布失败，请稍后重试')), ); } }_publishTeam 在真实项目里会替换成网络请求，我这里先用 Future.delayed 模拟延时，方便单独调试 UI 状态。有一点值得提醒：校验通过不代表数据合理，比如联系方式格式正确但号码是假的、备注里夹带广告，这类问题本地校验管不了，必须服务端做二次校验。表单的本地校验解决的是“用户填错了”，服务端校验解决的是“用户故意填假”，两层都不能省。
4.2 Loading 与重复提交拦截
提交按钮的禁用状态我直接绑定 _submitting，同时 _submit 方法开头也有一次拦截。这样既能防止用户连续点击造成重复发布，也能在请求期间通过按钮文案变化给出明确反馈：
Widget _buildSubmitButton() { return SizedBox( width: double.infinity, height: 48, child: FilledButton( onPressed: _submitting ? null : _submit, child: _submitting ? const SizedBox( width: 20, height: 20, child: CircularProgressIndicator(strokeWidth: 2), ) : const Text('发布组队'), ), ); }加载中按钮禁用 + 转圈，是移动端表单最通用的反馈模式。不要用“提交后弹一个 Dialog 再手动关”的方案，多一步操作就多一分流失。另外，await 之后一定要做 mounted 检查再访问 context，这在 Flutter 的异步回调里是必查项。我早期在这上面吃过亏，页面已经 pop 了回调才回来，直接操作 context 导致异常，mounted 检查加上之后这类问题基本绝迹。
5. OpenHarmony 适配与踩坑记录
Flutter 页面跑在 OpenHarmony 上，整体体验已经很接近标准 Flutter，但工程和运行时确实有一些差异。这些坑不致命，第一次遇到却会卡很久。我把这次实战里遇到的四个问题记在这里。
5.1 中文输入法下的限长和光标问题
剧本名和备注字段我都设了 maxLength，但在 OpenHarmony 设备上实测，中文输入法拼音组字中间态有时会触发限长判断，导致拼音打到一半就被截断，光标还会跳到行尾。我调整后的做法是把硬限长从 TextField 属性里拿掉，只保留 validator 里的长度校验。用户即使超长输入，提交时会被 validator 拦住并提示具体超了多少字，体验反而更清晰。当然如果产品要求输入过程中就硬限制，那要接受拼音中间态偶尔被截断的副作用，没有两全方案。
5.2 日期选择器本地化配置
showDatePicker 在没配本地化时，按钮文字是英文的，日期格式也是英文习惯。要让中文本地化生效，需要两步。第一步在 pubspec.yaml 加依赖：
dependencies: flutter_localizations: sdk: flutter第二步在 MaterialApp 里配置 delegates 和 locale。注意 flutter_localizations 是 SDK 自带的，不需要写版本号：
MaterialApp( localizationsDelegates: const [ GlobalMaterialLocalizations.delegate, GlobalWidgetsLocalizations.delegate, GlobalCupertinoLocalizations.delegate, ], supportedLocales: const [Locale('zh', 'CN')], locale: const Locale('zh', 'CN'), home: const CreateTeamPage(), )这个配置是全局性的，配一次整个App的 Material 组件文案都会中文化。我在 OpenHarmony 上遇到过配置不生效的情况，最后发现是 pubspec 里漏加了依赖，delegate 引用直接编译不过，补上之后就正常了。
5.3 插件适配与 MissingPluginException
Flutter 生态里绝大多数插件原生实现都是针对 Android/iOS 的，在 OpenHarmony 工程里直接用，最常见的报错就是 MissingPluginException。解决思路不是自己写 platform channel，而是优先找 OpenHarmony 社区适配过的插件版本。比如 image_picker 在 OpenHarmony 上就有对应的适配实现，包名和 API 设计尽量贴近原版，替换依赖后代码基本不用改。使用任何插件前，先确认它有没有 ohos 适配分支，这个检查应该写进团队的项目启动清单里。
5.4 文本基线差异导致视觉截断
OpenHarmony 的默认字体和 Android 不是同一套，相同 fontSize 下实际渲染高度会有几个像素的偏差。我在显示“开本时间”那行只读文本时，一开始用了固定高度容器加 Row 水平布局，结果在部分字重下出现文字下半截被裁掉的问题。后来把所有文字容器改成 minHeight 加 padding 而不是固定高度，问题就消失了。这个经验也适用于底部 Tab 和列表项，凡是文字可能换行或溢出的小组件，宁可多留空隙也不要写死高度。
6. 常见问题速查表
最后把这次实战里容易被绊住的问题整理成一张速查表，方便你对照排查：
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
| validate() 一直返回 false 但页面没提示 | 字段的 validator 没写，或者 autovalidateMode 没开 | 确认每个 FormField 都有 validator；用 onUserInteraction 即时提示 |
| 日期选择器显示英文 | 缺少 flutter_localizations 配置 | 添加依赖并配置 delegates 和 locale |
| image_picker 报 MissingPluginException | 使用了未适配 OpenHarmony 的插件版本 | 切换到 ohos 适配版本，检查 pubspec 依赖来源 |
| 键盘弹起后按钮被遮挡 | 底部 padding 没补偿键盘高度 | 用 MediaQuery viewInsets.bottom 动态加 padding |
| 中文本输入时 maxLength 截断拼音 | 输入法中间态触发了限长 | 去掉输入框硬限长，用 validator 做最终长度控制 |
| 小字号文本下半截被裁 | OpenHarmony 字体基线不同，容器高度过紧 | 改固定高度为 minHeight + padding |
| 图片选择成功后页面无反应 | 权限被拒但未捕获异常 | 确认 module.json5 已声明媒体权限，catch 里给用户明确提示 |
| 提交按钮连续点击产生重复发布 | 缺少提交中拦截 | _submit 开头加 _submitting 判断，按钮同时置灰 |
这里第 2 条和第 5 条是 OpenHarmony 场景下最容易踩的，其他几条在标准 Flutter 项目里也会遇到，属于通用经验。
我个人在实际操作中的体会是，这类表单页面写起来不难，难的是把边界情况都照顾到。一次成功的“发起组队”体验，背后是字段取舍、校验文案、键盘避让、权限降级这些琐碎细节叠在一起的结果。页面能跑只是第一步，把每个异常路径都走一遍、把每台测试设备都过一遍，才敢说这个功能真正做完了。如果你也在做 Flutter 跨端表单，建议把代码里写死的高度、写死的字符串、写死的权限假设全部过一遍，换成动态计算和明确提示，这套页面在 OpenHarmony 上的稳定性会有质的提升。
