鸿蒙 uni-app x form 提交重置与表单校验实践

鸿蒙专家

在鸿蒙平台用 uni-app x 开发应用，登录、注册、资料编辑、订单提交等场景都离不开表单。鸿蒙 4.61 开始支持 form 组件，它的价值可以概括为一句话：统一收集表单数据、统一提交、统一重置。

一、form 组件能做什么

form 用来把 input、textarea、checkbox、radio、switch、slider 这些表单控件组织起来。开发者给控件设置 name，点击 form-type="submit" 的按钮后，组件会自动收集所有数据；点击 form-type="reset" 的按钮后，会自动重置所有控件。提交事件通过 @submit 获取，回调参数类型为 UniFormSubmitEvent，数据在 event.detail.value 中。

如果不用 form，通常需要给每个 input 绑定 v-model，给 checkbox、radio 绑定事件，提交时手动拼接数据，重置时手动清空绑定。form 把这些重复工作收敛到组件层面，适合表单较多的鸿蒙应用页面。

需要注意兼容边界：原文明确，鸿蒙 4.61 开始支持；form 支持 input、textarea、checkbox、radio、switch、slider 等子组件，但不支持这些组件之外的自定义组件。如果页面里混有自定义组件，需要自行获取值并提交。

二、基础提交与重置

最简场景只需要两个按钮和提交、重置事件。给 input 设置 name，提交时直接从 event.detail.value 读取对象：

2. <template>
3. <form @submit="onSubmit" @reset="onReset">
4.   <input name="name" placeholder="请输入姓名"></input>
5.   <input name="phone" type="number" placeholder="请输入手机号"></input>
6.   <button form-type="submit" type="primary">提交</button>
7.   <button form-type="reset">重置</button>
8. </form>
9. </template>
10. <script setup lang="uts">
11. const onSubmit = (event: UniFormSubmitEvent) => {
12.   console.log('表单数据:', event.detail.value)
13.   // { name: '张三', phone: '13800138000' }
14.   uni.showToast({ title: '提交成功', icon: 'success' })
15. }
16. const onReset = () => {
17.   console.log('表单重置')
18. }
19. </script>

复制代码

这里的关键不是页面样式，而是 name 与 form-type 的配合：name 决定提交数据里的字段名，form-type="submit" 触发收集，form-type="reset" 触发重置。

三、多控件表单的数据形态

当表单同时包含单选、多选、开关、滑动条和文本域时，每个控件仍然通过 name 参与收集。原文示例中，radio-group name="gender"、checkbox-group name="hobbies"、slider name="age"、switch name="notify"、textarea name="remark" 会一起进入 event.detail.value。提交结果可能形如：

{ name: '张三', gender: 'male', hobbies: ['reading', 'sports'], age: 25, notify: true, remark: '...' }

从这个示例可以推导出：radio-group 返回选中值，checkbox-group 返回数组，slider 返回数值，switch 返回布尔值，textarea 返回文本。对业务表单来说，提交侧不需要逐个控件取值，只要按 name 读取字段即可。

四、登录、注册、地址编辑中的典型用法

登录表单通常只包含 username 和 password 两个 input，password 使用 password 属性。提交后从 event.detail.value 解构用户名和密码，再交给业务逻辑处理。

注册表单会在提交时做一次协议确认。原文示例用 checkbox-group name="agree" 收集“我已阅读并同意《用户协议》”，在 onSubmit 中判断 data.agree 是否为空；如果为空，就提示“请同意用户协议”并 return，不再继续注册流程。

地址编辑表单则展示了 textarea 和 switch 的组合：收货人、手机号用 input，详细地址用 textarea，是否默认地址用 switch name="isDefault"。提交后读取 event.detail.value，并通过 uni.showToast 给出保存成功反馈。

五、提交前校验：先校验，再提交

form 负责收集和重置，但业务校验仍要写。推荐在 onSubmit 内先取 event.detail.value，再逐项判断。原文示例校验姓名非空、手机号长度为 11 位，只有通过后才输出数据并提示提交成功：

2. const onSubmit = (event: UniFormSubmitEvent) => {
3.   const data = event.detail.value
4.   if (!data.name || (data.name as string).trim().length == 0) {
5.     uni.showToast({ title: '请输入姓名', icon: 'none' })
6.     return
7.   }
8.   const phone = data.phone as string
9.   if (!phone || phone.length != 11) {
10.     uni.showToast({ title: '请输入正确的手机号', icon: 'none' })
11.     return
12.   }
13.   console.log('验证通过，提交数据:', data)
14.   uni.showToast({ title: '提交成功', icon: 'success' })
15. }

复制代码

这段逻辑可以复用到登录、注册、订单、地址等页面。校验失败时直接 return，避免脏数据进入接口请求。

六、综合表单的组织方式

原文最后给出了一个综合页面：外层用 scroll-view，内部用 form 同时承载“基本信息”和“偏好设置”。input、textarea 通过 :value 回显 formData，radio 通过 :checked 判断 formData.gender，checkbox 通过 formData.hobbies.indexOf(...) > -1 判断选中状态，slider 通过 :value 绑定 formData.age，switch 通过 :checked 绑定 formData.notify。提交和重置按钮仍然使用 form-type="submit" 与 form-type="reset"。提交后由 submitted 控制结果区域，resultText 展示提交结果。原文脚本部分在 type FormData = { 处截断，实际落地时需要补全 FormData 类型，以及 onSubmit、onReset 的具体处理。

七、实践注意点

1. 鸿蒙 4.61 开始支持 form，接入前先确认目标版本。
2. 能用 form 收集的数据，不必给每个控件手动 v-model 再拼接；给控件设置 name 更直接。
3. 重置依赖 form-type="reset"，提交依赖 form-type="submit"。
4. 自定义组件不会被 form 自动收集，需要自行获取值并提交。
5. 校验逻辑放在 onSubmit 里，先校验再请求接口。
6. 多控件表单提交后得到的是按 name 组织的数据对象，直接按字段读取即可。

整体来看，uni-app x 的 form 组件把鸿蒙平台表单开发中最琐碎的收集、提交、重置动作标准化了。对于登录、注册、资料编辑、地址管理等高频页面，先按 name 组织控件，再在 onSubmit 中做校验和业务处理，能减少大量样板代码。