企业官网建设流程全解析

Flutter for OpenHarmony 剧本杀组队App实战04：发起组队表单实现

做这个系列已经写到第四篇了，前面几篇我们搭好了整体导航结构，搞定了剧本列表和组队广场的信息展示。说实话，前面那些页面大多是“只读”的，列表滑一滑、详情点一点，真正的交互压力还没来。这一篇的发起组队表单，算是App从“能看”到“能用”的分水岭——用户能不能顺畅地把一个组队需求发出去，全靠这一步。所以这篇我写得尽量细，尤其是表单校验、键盘适配和OpenHarmony专属的那些坑，尽量把我自己踩过的都交代清楚。

如果你正在用Flutter做OpenHarmony端的应用，或者哪怕你只是对跨端开发感兴趣，这篇文章里提到的表单设计思路、校验层写法、布局避坑，都能直接抄走用。别的不说，先把表单这件事想明白，后面接消息、接列表刷新都会顺很多。

1. 表单设计想清楚了才能动手

写表单最容易犯的毛病就是一上来就堆控件。文本输入框、下拉菜单、日期选择器、按钮，全往一个页面上放，样式还没统一，交互先乱了。我在做发起组队这个页面之前，先把用户场景摆到桌面上捋了一遍，才决定表单长什么样。

1.1 这个表单到底要收集哪些信息

剧本杀组队的核心信息，拆开无非是几个维度：组什么本、什么时候玩、在哪儿玩、缺几个人、有什么要求。但落到App里，这些信息不能一股脑全塞给用户。你想一下真实场景，用户想发起组队时，脑子里最先想到的是什么？大概率是“我今晚想玩一个恐怖本，缺两个人”，而不是“我要把店名、座位号、主持人要求全部填完”。所以表单字段不能设计成填空题，得是选择为主、填空为辅。

最终我定下的字段是这样几组：

• 剧本名称和剧本类型，名称用文本输入，类型用选择器；
• 期望的开场日期和时间，日期用日历选择，时间用滑动选择；
• 所在城市和具体店家，城市用下拉，店家先用文本输入（后续有能力再做成搜索选择）；
• 组队人数，这里要拆成“当前已有几人”和“总共需要几人”两个信息，避免用户理解偏差；
• 一句话备注，比如“新手车”“硬核推土机”“不许跳车”这类附加约束。

这个设计看起来不复杂，但每一条都是从用户行为反推的。比如“城市和店家”，如果城市是必填、店家选填，就能覆盖大部分需求，又不会因为店家数据不全而卡住表单。这就是表单设计的第一原则：让用户以最小的成本完成目标，而不是让表单显得豪华完整。

1.2 布局方案的取舍：为什么用Form + TextFormField

页面结构我在一开始就决定了用Flutter自带的Form组件包裹，配合TextFormField实现输入校验，而不是自己手写一套校验逻辑。原因很简单，Form提供了一套统一的表单状态管理机制，配合GlobalKey<FormState>，可以集中处理“校验全部字段”“重置表单”“保存状态”这些操作。你要是自己用TextEditingController挨个字段写validate()，字段一多代码就会变得非常脏。

布局上我用了ListView作为最外层容器，而不是Column。这里可能有人觉得奇怪，表单页面字段不多，用Column不就行了？问题在于键盘弹起时，Column容易溢出，而ListView天然可以滚动，键盘弹起来之后用户还能滑动到被遮挡的输入框。这个选择在OpenHarmony真机上的感受差异非常明显，后面我会专门展开讲。

1.3 状态管理与数据流设计

表单页内部的状态我用的是StatefulWidget，字段值通过TextEditingController分别持有，提交时统一读取。很多教程喜欢推荐Bloc或者Provider来做表单状态管理，但在一个独立表单页里，这样做收益不大。表单状态是页面私有的，不需要和全局状态共享，引入重型状态管理反而增加了代码跳转成本。

当然，提交之后的“数据带出去”这一步需要好好设计。我采用的做法是：表单页通过构造函数接收一个回调函数，提交成功时把组装好的组队信息对象作为参数回传，由上一级页面负责后续的上传或列表更新。这个模式在Flutter里很简单，也很好用，就是所谓的“回调将数据提升到父级”。

2. 核心字段与校验逻辑逐个拆解

表单设计的骨架定好了，接下来才是真正的硬功夫：每个字段具体怎么实现、校验规则怎么给、错误提示怎么展示。这些细节直接决定用户的填写体验，也是我这次花费时间最多的地方。

2.1 组队主题与描述：文本输入的两层校验

剧本名称和备注这两个文本字段，我都用了TextFormField，但校验策略完全不同。

剧本名称属于必填项，规则很简单：不能为空。但如果只判断是否为空，用户体验很一般——用户只输入一个空格怎么办？所以我加了一个trim()之后的空值判断。这里有个小细节：TextFormField默认不会trim，你拿到手的是一个带着首尾空格的字符串，必须自己在校验前处理。

备注这一栏是选填的，但也不能完全放养。我做了一个长度上限的限制，超过40个字就禁止继续输入。这个限制用LengthLimitingTextInputFormatter就能做到。有人可能觉得40字太短，但你想想，备注在组队卡片上只是一行小字，太长了显示效果很差，而且真正重要的信息用户会写在主题里。长度限制是产品设计的手段，不是技术限制。

2.2 人数选择：Stepper还是自定义计数器

人数信息在表单里是硬需求，但我没有用Stepper组件，原因很简单：Stepper默认的样式比较死板，在OpenHarmony端上它的增量按钮触控区域偏小，很容易误触。而且组队人数有一个天然的业务下限（最少2人，否则不成局），用Stepper还得自己写min、max限制，样式还难调。

最后我用了自定义计数器：一个Row，左边是减号按钮，中间是当前人数，右边是加号按钮。按钮用IconButton包一下，加上SizedBox控制尺寸。这个方案的好处是每个元素都可以自由控制样式，触控区域也可以人为放大，对移动端手指操作非常友好。

这个字段的校验逻辑有点特殊：我要校验“当前人数”不能大于“总人数”。这个跨字段校验在单个TextFormField里做不到，只能在点击提交时统一处理。具体做法是读取两个状态值，如果当前人数大于总人数，就弹一个SnackBar提示用户调整。这里要注意，跨字段错误不适合写在字段下方的校验文案里，因为用户不知道该去改哪个字段。

2.3 时间地点与偏好标签：三种输入控件的取舍

日期时间选择这组字段，我一开始想直接用showDatePicker和showTimePicker。但实测OpenHarmony端上，showDatePicker的默认样式在不同版本上表现不完全一致，偶尔会卡在月历视图加载上。稳妥起见，我自己写了一个底部弹出的日期选择面板。

这个自定义面板其实不复杂，用showModalBottomSheet做一个半屏弹层，里面放一个CalendarDatePicker组件，选定日期后回调关闭弹层并更新表单显示。这么做有几个好处：样式可控、交互路径明确、不依赖系统控件差异。时间选择也是同样的思路，用CupertinoDatePicker的模式，放在同一套自定义弹层里。

城市选择我用了DropdownButtonFormField，但这里有一个OpenHarmony特色问题：这个组件的下拉菜单在部分版本上出现在屏幕中央而不是锚定在字段下方。排查之后发现是整个弹窗的Route属性设置问题，后面我在坑位清单里细说。剧本类型和玩家偏好标签，我用了Wrap包裹的ChoiceChip多选组件，用户点一下就选中，再点一下取消，视觉反馈直接，操作效率比下拉框高很多。

2.4 校验信息即时反馈的交互细节

校验反馈这块，Flutter的TextFormField自带一套方案：validator返回非空字符串时，错误信息会显示在输入框下方的decoration.errorText里。但我做了两个增强。

第一个增强是“首次模糊后再报错”。如果用户还没填完就开始提示“必填”，视觉冲击太强，容易让人心烦。所以我在FocusNode的onFocusChange里加了一个逻辑：只有这个字段失焦过，才显示校验错误。这个“已触摸”标记我存在一个Set<String>里，字段级管理，不会互相干扰。

第二个增强是报错文案的颗粒度。对于主题这种必填字段，“请输入剧本名称”会让人困惑——我明明输入了呀？如果是因为输入了空格而被判空，提示语就会变成“剧本名称不能为空”。有些用户会输入一堆无意义的“啊吧啊吧”，这种内容技术上无法屏蔽，但至少能通过长度下限（2个字）让他意识到要正经填。

3. 实操：完整实现一个发起组队表单

前面把设计思路和字段逻辑说透了，下面该上代码了。我会按实际项目的实现顺序来走一遍，重点讲关键部分，重复性代码我会简略带过，但关键的坑会标注出来。

3.1 基础脚手架：FormState与GlobalKey

class CreateTeamPage extends StatefulWidget { const CreateTeamPage({super.key, required this.onTeamCreated}); final void Function(TeamDraft draft) onTeamCreated; @override State<CreateTeamPage> createState() => _CreateTeamPageState(); } class _CreateTeamPageState extends State<CreateTeamPage> { final _formKey = GlobalKey<FormState>(); final _scriptNameController = TextEditingController(); final _cityController = TextEditingController(); final _storeController = TextEditingController(); final _remarkController = TextEditingController(); final _touchedFields = <String>{}; ... }

这段代码定义了表单页的基础结构。特别注意GlobalKey<FormState>是用来驱动表单校验和提交状态的核心句柄，_touchedFields是我用来记录用户“已触及”字段的集合，配合失焦事件使用。

3.2 字段代码实现与要点注释

接下来看几个有代表性的字段写法。首先是主题输入框：

TextFormField( controller: _scriptNameController, maxLength: 30, inputFormatters: [ LengthLimitingTextInputFormatter(30), ], decoration: const InputDecoration( labelText: '剧本名称', hintText: '例如：窗边的女人', counterText: '', ), validator: (value) { if (!_touchedFields.contains('scriptName')) return null; final trimmed = value?.trim() ?? ''; if (trimmed.isEmpty) return '剧本名称不能为空'; if (trimmed.length < 2) return '至少输入2个字'; return null; }, onTapOutside: (_) => FocusScope.of(context).unfocus(), )

这里counterText设置为空字符串，是为了关掉默认的“0/30”字数计数显示，这个计数器在实际界面上很碍眼。如果想保留计数反馈，也可以留着，看个人偏好。

跨字段的人数校验我单独放在提交函数里，因为TextFormField的validator只能拿到当前字段的值，拿不到其他组件状态。我在页面顶部用int变量维护currentPlayers和totalPlayers，提交时先判断再提示。

void _submit() { FocusScope.of(context).unfocus(); final currentValidate = _formKey.currentState!.validate(); if (!currentValidate) return; if (currentPlayers > totalPlayers) { ScaffoldMessenger.of(context).showSnackBar( const SnackBar(content: Text('当前人数不能大于组队总人数')), ); return; } final teamName = _scriptNameController.text; final preparedTime = '${_selectedDate} ${_selectedTime}'; // 组装 TeamDraft 对象并回调给父级 widget.onTeamCreated(TeamDraft( scriptName: teamName, ... )); }

这里有个细节：_submit被调用时先unfocus掉键盘焦点。一方面是为了让输入法收起、显示完整界面，另一方面也是为了让失焦逻辑把最后的“已访问”状态落定，这样validate()的结果才准确。

3.3 提交与回调：数据怎么带出去

表单提交之后，不能只是弹个提示完事。我通过widget.onTeamCreated把组队草稿对象传回上一级页面，上一级页面拿到数据后，先刷新列表页的占位数据，再执行上传接口。这种“表单只负责收集、由调用方决定下一步”的设计，让表单页保持纯粹，后续即使要换上传逻辑，也不影响表单本身。

为了演示方便，我定义了一个轻量数据类：

class TeamDraft { final String scriptName; final String city; final String store; final String preparedTime; final int currentPlayers; final int totalPlayers; final List<String> tags; final String remark; ... }

不要把这个类设计得太重，也别在表单页里写toJson之类的序列化逻辑。数据类的生命周期很短，表单页收集完成之后它只负责把值传递出去，后续的序列化和网络请求是数据层的事情。

3.4 真机适配：OpenHarmony上的键盘与安全区

表单页在OpenHarmony真机上跑起来之后，第一个要面对的硬问题就是键盘。TextFormField点击弹出输入法时，整个页面会被压缩，如果没有滚动容器，就会出现RenderFlex overflowed的黄色警告条，界面也会被挤得变形。

解决办法刚才提过，最外层用ListView包裹。但这里还有一个进阶问题：用户点击底部字段时，即使页面可以滚动，输入框也可能被键盘完全遮住。Flutter自带一个行为是scrollPadding，默认值是EdgeInsets.all(20.0)，但针对较深的页面，这个值可能不够。

我最终的写法是给ListView设置了keyboardDismissBehavior: ScrollViewKeyboardDismissBehavior.onDrag，再给Padding预留了一个安全区高度。同时利用MediaQuery.viewInsetsOf(context)动态计算键盘高度，给列表底部追加对应的占位空间：

Padding( padding: EdgeInsets.only( bottom: MediaQuery.viewInsetsOf(context).bottom, ), child: ListView( keyboardDismissBehavior: ScrollViewKeyboardDismissBehavior.onDrag, ... ), )

这段代码的意思是，键盘弹起时，底部自动增加与键盘同高的空白，让最下面的提交按钮可以被滚到键盘上方。这个技巧在做任何含表单的Flutter页面时都建议直接抄走，不只是OpenHarmony端。

4. 上线前必须过一遍的坑位清单

表单开发过程中我踩了好几个本可以提前避开的坑，这里整理成一个清单，按坑的严重程度排个序。你要是照着这个做，能省不少时间。

4.1 我在这个表单里踩过的四个坑

第一个坑是showDatePicker在OpenHarmony端的兼容问题。前面提到过，这个系统级控件在不同版本上样式不稳定，甚至有一次直接卡在日历加载界面。我的结论是：凡是依赖系统控件实现的UI能力，都要在OpenHarmony真机上提前测试，不能只在上层模拟器上跑一遍就以为没问题。最终的解决方案是自己做一个底部弹层接管日期和时间选择。

第二个坑是下拉菜单路由问题。DropdownButtonFormField点击展开时，弹出的菜单在OpenHarmony上会显示在窗口正中央，而不是在输入框附近。这个问题跟Flutter对OpenHarmony弹窗的Route适配有关，严格说是引擎层还没完全对齐。我最后为了避免体验割裂，把这几个下拉字段也换成了自定义底部弹层选择器。如果你不想大改，可以先查查你用的Flutter版本是否已经修复这个issue，但我的建议是自定义组件一劳永逸。

第三个坑是文本输入框的字体和视觉不一致。OpenHarmony系统默认字体和Android生态有细微差别，同一个TextStyle在两种平台上渲染出来的字重和字距不完全一样。这个问题对用户来说很直观，如果你不做适配，用户会觉得这个App“跟系统风格不搭”。好在这一版我全站都做了字体归一化处理，所以在表单页直接沿用即可。

第四个坑是AutofillGroup的兼容性。我在测试表单时想着加上自动填充功能，结果在OpenHarmony上发现自动填充服务并没有完全生效，还引发了几个输入框的焦点跳转异常。后来我干脆移除了AutofillGroup，等底层能力完善后再考虑。这类平台能力差异，建议在跨端开发时先保守处理。

4.2 问题排查速查表

为了方便你后续自查，我把开发过程里可能遇到的几个高频问题整理成一张表，按“现象 -> 原因 -> 处理方案”给出参考。

这张表是我在开发过程中真实遇到过的问题。虽然不能覆盖所有情况，但如果你也是Flutter for OpenHarmony的新手，大概率会遇到其中的两三个。

5. 表单做完之后，下一步做什么

发起组队表单能正常提交了，但离完整的“组队闭环”还差不少。这一节我聊聊表单做完之后的延伸工作，也算给系列后续内容埋个引子。

5.1 数据校验的后置化与服务端配合

表单的前端校验只解决“格式对不对”，解决不了“能不能创建”。比如用户输入了一个已满员的队伍人数上限，或者同一个剧本在同一个时间已经被别人占了，这些逻辑必须靠服务端兜底。我的建议是前端校验尽量友好，服务端校验尽量严格，两者配合而不是互相当替身。

在具体操作上，提交按钮在请求发出后要进入loading状态并禁用，防止用户反复点击造成重复提交。这个状态我用一个_isSubmitting布尔值控制，请求完成后无论成功失败都要恢复。别看这是一个很小的细节，我在多个项目里都见过因为漏了这步导致用户连点两次，结果同一局被创建了两遍的情况。

5.2 状态管理的后续演进方向

现在表单页的状态管理方式是“页面内StatefulWidget + 回调”，这对单页场景完全够用。但等App功能继续增加，比如用户个人主页要显示“我发起的组队”，或者消息系统要实时提示“有人加入了你的队伍”，那这个组队数据的来源就不能再靠页面回调一层层传了，而是需要一个全局的数据仓库。

到那个时候可以考虑引入类似Provider或Riverpod这类状态管理方案。具体选型，我个人的习惯是先看项目规模再决定，不做无谓的重量化改造。状态管理工具的引入要跟着业务复杂度走，不要一开始就套一个重型框架，那样开发反而会被框架绑住手脚。

表单这个环节，在用户眼里可能只是“填一下、点个按钮”的事，但背后涉及到的校验规则、交互细节、平台适配，每一环都值得认真打磨。希望这一篇能帮你在做Flutter for OpenHarmony的表单时少走弯路，哪怕是只避开了我在4.1节里说的某一个坑，这篇文章也算值了。