一款基于当前最前沿的前端（Vue3 + Vite + Antdv）和后台（Spring boot）实现的低代码开发平台

## Forms 表单 > **组件名：uni-forms** > 代码块： `uForms`、`uni-forms-item` > 关联组件：`uni-forms-item`、`uni-easyinput`、`uni-data-checkbox`、`uni-group`。 uni-app的内置组件已经有了 `<form>`组件，用于提交表单内容。 然而几乎每个表单都需要做表单验证，为了方便做表单验证，减少重复开发，`uni ui` 又基于 `<form>`组件封装了 `<uni-forms>`组件，内置了表单验证功能。 `<uni-forms>` 提供了 `rules`属性来描述校验规则、`<uni-forms-item>`子组件来包裹具体的表单项，以及给原生或三方组件提供了 `binddata()` 来设置表单值。 每个要校验的表单项，不管input还是checkbox，都必须放在`<uni-forms-item>`组件中，且一个`<uni-forms-item>`组件只能放置一个表单项。 `<uni-forms-item>`组件内部预留了显示error message的区域，默认是在表单项的底部。 另外，`<uni-forms>`组件下面的各个表单项，可以通过`<uni-group>`包裹为不同的分组。同一`<uni-group>`下的不同表单项目将聚拢在一起，同其他group保持垂直间距。`<uni-group>`仅影响视觉效果。 > **注意事项** > 为了避免错误使用，给大家带来不好的开发体验，请在使用组件前仔细阅读下面的注意事项，可以帮你避免一些错误。 > - 组件需要依赖 `sass` 插件 ，请自行手动安装 > - `resetFields` 方法不会重置原生组件和三方组件的值 > - 如果配置 `validateTrigger` 属性为 `bind` 且表单域组件使用 `input` 事件触发会耗损部分性能，请谨慎使用 > - 组件支持 nvue ，需要在 `manifest.json > app-plus` 节点下配置 `"nvueStyleCompiler" : "uni-app"` > - 如使用过程中有任何问题，或者您对uni-ui有一些好的建议，欢迎加入 uni-ui 交流群：871950839 ### 安装方式 本组件符合[easycom](https://uniapp.dcloud.io/collocation/pages?id=easycom)规范，`HBuilderX 2.5.5`起，只需将本组件导入项目，在页面`template`中即可直接使用，无需在页面中`import`和注册`components`。 如需通过`npm`方式使用`uni-ui`组件，另见文档：[https://ext.dcloud.net.cn/plugin?id=55](https://ext.dcloud.net.cn/plugin?id=55) ### 基本用法 `uni-forms` 组件通常用来做表单校验和提交。每一个 `uni-forms-item` 是它的一个表单域组件，用来承载表单具体内容，`uni-forms-item` 中可以嵌套 `uni-easyinput`、`uni-data-checkbox` 和 uni-app内置的表单组件 ，不过 uni-app 的内置表单组件需要通过 `binddata` 或者 `uni-forms` 提供的 `setValue` 方法，将内容与 `uni-forms` 关联，才可完成表单的校验与提交（详见后文`表单校验` 部分） ```html <template> <view class=""> <uni-forms :modelValue="formData"> <uni-forms-item label="姓名" name="name"> <uni-easyinput type="text" v-model="formData.name" placeholder="请输入姓名" /> </uni-forms-item> <uni-forms-item required name="hobby" label="兴趣爱好"> <uni-data-checkbox multiple v-model="formData.hobby" :localdata="hobby"/> </uni-forms-item> </uni-forms> <button @click="submitForm">Submit</button> </view> </template> ``` ### 对齐方式 使用 `label-position` 属性可以设置所有表单域的位置，默认在左侧 ```html <template> <view class=""> <uni-forms :modelValue="formData" label-position="top"> <uni-forms-item label="姓名" name="name"> <uni-easyinput type="text" v-model="formData.name" placeholder="请输入姓名" /> </uni-forms-item> <uni-forms-item required name="hobby" label="兴趣爱好"> <uni-data-checkbox multiple v-model="formData.hobby" :localdata="hobby"/> </uni-forms-item> </uni-forms> </view> </template> ``` ## 表单校验 表单校验还可以直接通过 `uniCloud web 控制台` 快速根据 `schema` 自动生成表单维护界面，比如新建页面和编辑页面，自动处理校验规则，更多参考[DB Schema](https://uniapp.dcloud.io/uniCloud/schema) ### 如何使用 1. `uni-forms` 需要通过 `rules` 属性传入约定的校验规则，详细描述下文`校验规则说明`。 ```html <!-- rules 内容详见下方完整示例 --> <uni-forms ref="form" :rules="rules"> ... </uni-forms> ``` 2. `uni-forms` 需要绑定`modelValue`属性，值为表单的key\value 组成的对象。 ```html <!-- formData、rules 内容详见下方完整示例 --> <uni-forms ref="form" :modelValue="formData" :rules="rules"> ... </uni-forms> ``` 3. `uni-forms-item` 需要设置 `name` 属性为当前字段名，字段为 `String` 类型而非变量。 ```html <!-- formData、rules 内容详见下方完整示例 --> <uni-forms :modelValue="formData" :rules="rules"> <uni-forms-item label="姓名" name="name"> <uni-easyinput type="text" v-model="formData.name" placeholder="请输入姓名" /> </uni-forms-item> <uni-forms-item required name="hobby" label="兴趣爱好"> <uni-data-checkbox multiple v-model="formData.hobby" :localdata="hobby"/> </uni-forms-item> </uni-forms> ``` 4. 如果使用`uni-easyinput` 和 `uni-data-checkbox` 等关联组件，只需绑定 v-model，无需其他操作。 5. 如果使用原生 input、checkbox 或三方组件等，只需要给组件绑定 `binddata` 方法即可触发表单校验，无需绑定事件到 `methods` 中，见下方完整示例。 6. `binddata('name',$event.detail.value,'form')"` 方法接受三个值， - 第一个参数传入当前表单组件所在的 name，同当前父组件 `uni-forms-item` 绑定属性 `name` 的值 - 第二个参数传入需要校验的值，内置组件可以通过 `$event.detail.value` 获取到组件的返回值，自定义组件传入需要校验的值即可 - 第三个参数传入 `uni-forms` 组件绑定属性 `ref` 的值，通常在多表单的时候需要传入，用来区分表单，如页面中仅有一个 `uni-forms` 可忽略 7. 如果内置 `binddata` 方法无法满足需求，在当前页面的 `methods` 中复写此方法即可，复写此方法需要调用 `uni-forms` 的 `setValue` 来触发表单校验，见下方 `setValue`方法说明 **完整示例** ```html <template> <view> <uni-forms ref="form" :modelValue="formData" :rules="rules"> <uni-forms-item label="姓名" name="name"> <uni-easyinput type="text" v-model="formData.name" placeholder="请输入姓名" /> </uni-forms-item> <uni-forms-item label="邮箱" name="email"> <input class="input" v-model="formData.email" type="text" placeholder="请输入用户名" @input="binddata('email',$event.detail.value)" /> </uni-forms-item> </uni-forms> <button @click="submit">Submit</button> </view> </template> ``` ```javascript export default { data() { return { // 表单数据 formData: { name: 'LiMing', email: '[email protected]' }, rules: { // 对name字段进行必填验证 name: { rules: [{ required: true, errorMessage: '请输入姓名', }, { minLength: 3, maxLength: 5, errorMessage: '姓名长度在 {minLength} 到 {maxLength} 个字符', } ] }, // 对email字段进行必填验证 email: { rules: [{ format: 'email', errorMessage: '请输入正确的邮箱地址', }] } } } }, methods: { /** * 复写 binddata 方法，如果只是为了校验，无复杂自定义操作，可忽略此方法 * @param {String} name 字段名称 * @param {String} value 表单域的值 */ // binddata(name,value){ // 通过 input 事件设置表单指定 name 的值 // this.$refs.form.setValue(name, value) // }, // 触发提交表单 submit() { this.$refs.form.validate().then(res=>{ console.log('表单数据信息：', res); }).catch(err =>{ console.log('表单错误信息：', err); }) } } } ``` > **注意** > `modelValue` 对象目前有比较严格的格式要求： > - 尽量不要使用