介绍
用于数据录入、校验,支持输入框、单选框、复选框、文件上传等类型,需要与
组件搭配使用。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`来避免这个问题。
效果图: