默认主题
表单

示例

请选择
0100
基本用法

表单需要Form嵌套FormItem进行使用,FormItem中可以包含任意组件或原生元素。同时我们可以指定FormItem的表单验证规则:

  1. FormItem添加model属性,指定需要验证的字段名。如果不指定,则不会进行任何验证
  2. FormItem添加rules属性,指定需要验证的规则。如果不指定,则不会进行任何验证。内置的验证规则如下:
    1. required {Boolean}:必须填写
    2. digits {Boolean}: 请输入数字
    3. email {Boolean}: 请输入正确的邮箱地址
    4. url {Boolean}: 请输入正确的网址

      该规则可以验证IP地址,但是会排除192.168.X.X | 192.254.X.X | 172.16.0.0 - 172.31.255.255 | 10.X.X.X | 172.X.X.X这类保留IP地址

    5. date {Boolean}:请输入正确的日期
    6. dateISO {Boolean}:请输入正确的日期(YYYY-MM-DD)
    7. number {Boolean}:请输入正确的数
    8. maxLength {Number}:如果检验的值是数组:最多选择n项;如果检验的值是字符串:最多输入n个字符
    9. minLength {Number}:同上(检验最少长度)
    10. rangeLength {Array<Number>}:同上,检验长度的范围
    11. max {Number}:请输入不大于n的数
    12. min {Number}:请输入不小于n的数
    13. range {Array<Number>}:请输入min到max之间的数
    14. step {Number}:请输入步长为n的数
    15. equalTo {String}:两次输入不一致
  3. FormItem添加messages属性,指定验证失败时展示的错误内容。默认内容如上所示
  4. FormItem添加classNames属性,指定验证失败时错误元素需要额外添加的className,默认不添加

表单验证通过会触发submit事件(不通过不会触发),我们可以绑定该事件来提交数据。或者我们也可以手动调用Formvalidate()方法来验证,该函数为异步函数,返回truefalse来标示验证是否通过。另外,验证失败时,可以通过FormgetFirstInvalidFormItem()方法来获取第一条出错的FormItem

验证的字段名必须是当前上下文对象上的直接属性名,在循环中我们必须通过索引来拼接取值路径字符串,例如:"users.0.phone"

React下,需要往子组件注入当前上下文_context,因为FormItem需要从当前上下文获取待验证的值,详见下面index.jsx示例文件

index.vdt
index.styl
index.js
index.vue (Vue)
index.jsx (React)
自定义验证规则

当内置的验证规则不能满足需求时,我们还可以自定义验证规则。有如下两种方式添加规则:

  1. 通过Form.addMethod()静态方法添加全局验证规则,由于是全局的,我们可以在任意地方的 FormItem中使用该规则。使用方法见API说明
  2. 通过FormItemrules属性,定义局部规则,该规则只对该FormItem有效

本例中,我们添加一条全局规则letter用来验证只能输入字母,同时添加一条局部规则unique来验证所有输入必须不同

验证方法中param,即为使用该规则时传入的参数,例如本例中的letter: truetrue会作为param参数传给验证方法。当然我们还可以指定任意值,只要不是false就行,因为false代表不验证

index.vdt
index.styl
index.js
index.vue (Vue)
index.jsx (React)
自定义label

通过label扩展点,我们可以定义更复杂的label,而不仅仅只是文本,当Form添加了starOnRequired属性时,必填的FormItem标签前面将自动添加*

index.vdt
index.styl
index.js
index.vue (Vue)
index.jsx (React)
可变规则

规则rules的值是响应式的,这意味着我们可以实时改变验证规则。

例如本例中,用户可以不输入姓名,但如果输入了“姓”,就必须输入“名”,反之亦然。

index.vdt
index.styl
index.js
index.vue (Vue)
index.jsx (React)
异步验证

要完成异步验证(例如:通过后端接口判断用户名是否重复),只需要在验证规则函数中返回Promise即可

index.vdt
index.styl
index.js
index.vue (Vue)
index.jsx (React)
请选择
表单布局

通过layout指定表单布局:horizontal, vertical, inline

index.vdt
index.js
index.vue (Vue)
index.jsx (React)

属性

Form

属性 说明 类型 默认值
labelWidth 定义所有子孙FormItem组件的label宽度 String | Number undefined
layout 指定表单布局方式 "horizontal" | "vertical" | "inline" "horizontal"
starOnRequired FormItem必填时,是否在label前面展示* Boolean false

FormItem

属性 说明 类型 默认值
model 指定需要验证的属性名称 String undefined
rules 指定验证规则 Object {}
messages 指定验证失败时错误提示文案 Object {}
classNames 指定验证失败时添加的className Object {}
label 指定表单每一项前面展示的标题 String undefined
htmlFor 指定labelfor属性 String undefined
hideLabel 是否隐藏label,默认会展示label,即使该属性为空,也会展示占位元素 Boolean false
isDirty 组件是否被污染,组件只有被污染后,才会进行表单验证 Boolean false
force 如果组件被污染,让FormItem更新时,强制验证。你也可以配合isDirty属性,指定强制验证的时机 #6 Boolean false
fluid FormItem的宽度默认是被子元素撑开的,添加该属性可以渲染100%的宽度 Boolean false

扩展点

FormItem

名称 说明
label 扩展前面的标题label
content 扩展后面的内容,也可以使用children代替
append 往后面追加的内容

事件

Form

事件名 说明 参数
submit 当表单提交并且所有规则都验证通过时触发 1. Event
2. Form实例

方法

Form

方法名 说明 参数 返回值
validate 验证表单所有规则 - Promise: .then(valid => {})validtrue验证成功,否则失败
reset 重置表单 - undefined
getFirstInvalidFormItem 获取第一条出错的FormItem - FormItem

静态方法

Form

Form还提供了一个静态方法,用于全局添加验证规则,通过Form.addMethod()调用

方法名 说明 参数 返回值
addMethod 添加全局验证规则,这样在所有FormItem中如果需要使用该规则,只需要在rules中写上该规则名即可 1. name 指定规则名称,不能重复
2. method 指定该规则的验证函数,该函数返回truefalse来标识验证成功或失败,如果返回字符串,则直接当做错误文案展示,该函数将传入3个参数:1. 当前验证的值,2. 当前验证的FormItem实例,3. 当前规则的参数,即使用该规则时指定的值
3. message 验证失败时的错误提示文案,该值可以为字符串或者函数,如果为函数,传入参数同method,用于个性化文案提示
4. className 验证失败时添加的类名
undefined