介绍
用于数据录入、校验，支持输入框、单选框、复选框、文件上传等类型，需要与
组件搭配使用。2.5 版本开始支持此组件。
引入
代码演示
基础用法
在表单中，每个
代表一个表单项，使用 Field 的 `rules` 属性定义校验规则。
校验规则
通过 `rules` 定义表单校验规则，可用字段见
。
表单项类型 - 开关
在表单中使用
。
表单项类型 - 复选框
在表单中使用
。
表单项类型 - 单选框
在表单中使用
。
表单项类型 - 步进器
在表单中使用
。
表单项类型 - 评分
在表单中使用
。
表单项类型 - 滑块
在表单中使用
。
表单项类型 - 文件上传
在表单中使用
。
表单项类型 - 选择器
在表单中使用
。
表单项类型 - 时间选择器
在表单中使用
。
表单项类型 - 省市区选择器
在表单中使用
。
表单项类型 - 日历
在表单中使用
。
API
Props
| 参数 | 说明 | 类型 | 默认值 | |
|---|---|---|---|---|
| label-width | 表单项 label 宽度，默认单位为px | number 、 string | 6.2em | |
| label-align | 表单项 label 对齐方式，可选值为 center right | string | left | |
| input-align | 输入框对齐方式，可选值为 center right | string | left | |
| error-message-align | 错误提示文案对齐方式，可选值为 center right | string | left | |
validate-trigger v2.5.2 | 表单校验触发时机，可选值为 onChange、onSubmit，详见下表 | string | onBlur | |
| colon | 是否在 label 后面添加冒号 | boolean | false | |
disabled v2.12.2 | 是否禁用表单中的所有输入框 | boolean | false | |
readonly v2.12.2 | 是否将表单中的所有输入框设置为只读 | boolean | false | |
| validate-first | 是否在某一项校验不通过时停止校验 | boolean | false | |
scroll-to-error v2.5.2 | 是否在提交表单且校验不通过时滚动至错误的表单项 | boolean | false | |
show-error v2.6.0 | 是否在校验不通过时标红输入框 | boolean | true | |
show-error-message v2.5.8 | 是否在校验不通过时在输入框下方展示错误提示 | boolean | true | |
submit-on-enter v2.8.3 | 是否在按下回车键时提交表单 | boolean | true |
> 表单项的 API 参见：
Rule 数据结构
使用 Field 的 `rules` 属性可以定义校验规则，可选属性如下:
| 键名 | 说明 | 类型 | |
|---|---|---|---|
| required | 是否为必选字段，当值为空字符串、空数组、undefined、null 时，校验不通过 | boolean | |
message v2.5.3 | 错误提示文案 | string 、 (value, rule) => string | |
validator v2.5.3 | 通过函数进行校验 | (value, rule) => boolean 、 Promise | |
pattern v2.5.3 | 通过正则表达式进行校验 | RegExp | |
trigger v2.5.2 | 本项规则的触发时机，可选值为 onChange、onBlur | string | |
formatter v2.5.3 | 格式化函数，将表单项的值转换后进行校验 | (value, rule) => any |
validate-trigger 可选值
通过 `validate-trigger` 属性可以自定义表单校验的触发时机。
| 值 | 描述 | |
|---|---|---|
| onSubmit | 仅在提交表单时触发校验 | |
| onBlur | 在提交表单和输入框失焦时触发校验 | |
| onChange | 在提交表单和输入框内容变化时触发校验 |
Events
| 事件名 | 说明 | 回调参数 | |
|---|---|---|---|
| submit | 提交表单且验证通过后触发 | values: object | |
| failed | 提交表单且验证不通过后触发 | errorInfo: { values: object, errors: object[] } |
方法
通过 ref 可以获取到 Form 实例并调用实例方法，详见
。
| 方法名 | 说明 | 参数 | 返回值 | |
|---|---|---|---|---|
| submit | 提交表单，与点击提交按钮的效果等价 | - | - | |
| validate | 验证表单，支持传入 name 来验证单个或部分表单项 | name?: string 、 string[] | Promise | |
| resetValidation | 重置表单项的验证提示，支持传入 name 来重置单个或部分表单项 | name?: string 、 string[] | - | |
scrollToField v2.8.3 | 滚动到对应表单项的位置，默认滚动到顶部，第二个参数传 false 可滚动至底部 | name: string, alignToTop: boolean | - |
Slots
| 名称 | 说明 | |
|---|---|---|
| default | 表单内容 |
常见问题
点击表单中的普通按钮为什么会触发表单提交？
在表单中，除了提交按钮外，可能还有一些其他的功能性按钮，如发送验证码按钮。在使用这些按钮时，要注意将`native-type`设置为`button`，否则会触发表单提交。
这个问题的原因是浏览器中 button 标签 type 属性的默认值为`submit`，导致触发表单提交。我们会在下个大版本中将 type 的默认值调整为`button`来避免这个问题。
效果图：
