# Form 表单
# Form 概述
具有数据收集、校验和提交功能的表单，包含复选框、单选框、输入框、下拉选择框等元素。
TIP
注意：非 template/render 模式下，需使用 h-form。
注意：form-item中设置v-if时，需要增加key属性且保证唯一，防止form-item间相互复用，导致校验不到位重置不到位等情况。
注意：W3C 标准中有如下规定 (opens new window)：
When there is only one single-line text input field in a form, the user agent should accept Enter in that field as a request to submit the form.
即：当一个 form 元素中只有一个输入框时，在该输入框中按下回车应提交该表单。如果希望阻止这一默认行为，可以在 <h-form> 标签上添加 @submit.native.prevent。
# Form 代码示例
# 行内表单
设置属性 inline，表单元素可以水平排列。
# 表单控件
在 Form 内，每个表单域由 Form-item 组成，可包含的控件有：Input、Radio、Checkbox、Switch、Select、Slider、DatePicker、TimePicker、Cascader、Transfer、InputNumber、Rate、Upload。
给 Form-item 设置属性 label 可以显示表单域的标签，需要给 Form 设置 label-width。
# 对齐方式
设置属性 label-position，可以改变表单域标签的位置，left 为左对齐，right 为右对齐，top 会置于表单域顶部。
# 表单验证-validRules验证
三种方式：form表单的rules属性、formitem的rules属性（不建议）、formItem的validRules属性
优先级：validRules > formItem.rules > form.rules,同时,优先级高的会覆盖优先级低的
注意：验证时formItem上需要有prop属性
| 默认支持验证 | 验证提示消息 |
|---|---|
| intege 整数 intege1 正整数 intege2 负整数 num 数字 num1 非负整数 num2 非正整数 decmal 浮点数 decmal1 正浮点数 decmal2 负浮点数 decmal4 非负浮点数 decmal5 非正浮点数 email 邮件 url url chinese 仅中文 ascii 仅ACSII字符 zipcode 邮编 mobile 手机 ip4 ip地址 picture 图片 rar 压缩文件 date 日期 qq QQ号码 tel 电话号码的函数(包括验证国内区号,国际区号,分机号) username 用来用户注册。匹配由数字、26个英文字母或者下划线组成的字符串 letter 字母 letter_u 大写字母 letter_l 小写字母 | integeMessage : "输入值不是整数" intege1Message : "输入值不是正整数" intege2Message : "输入值不是负整数" emailMessage : "邮件地址不正确" zipcodeMessage : "邮编输入格式不正确" dateMessage : "日期格式不正确" qqMessage : "QQ号码格式不正确" telMessage : "电话号码格式不正确" mobileMessage : "移动电话格式不正确" decmalMessage : "输入值不是浮点数" decmal1Message : "输入值不是正浮点数" decmal2Message : "输入值不是负浮点数" decmal4Message : "输入值不是非负浮点数" decmal5Message : "输入值不是非正浮点数" colorMessage : "只能输入颜色格式" urlMessage : "只能输入url格式" asciiMessage : "只能输入ACSII字符格式" ip4Message : "只能输入ip4地址格式" pictureMessage : "只能输入图片格式" rarMessage : "只能输入压缩文件格式" numMessage : "输入值不是数字" num1Message : "请输入0或正整数" num2Message : "请输入0或负整数" letterMessage : "只能输入字母格式" letter_uMessage : "只能输入大写字母格式" letter_lMessage : "只能输入小写字母格式" usernameMessage :"只能输入由数字、26个英文字母或者下划线组成的字符串" requiredMessage : "当前输入不能为空" |
注1：formItem上配置必填，只需添加required属性
注2：formItem由组合组件构成时，必填标识在label左侧
注3：默认提供的验证触发方式为 blur
注4：FromItem.rules 配置校验请参考 async-validator 库
# 表单验证-rules验证
可以通过在 form/formItem 上设置 rules 属性进行自定义验证
formItem 设置 rules 如下：ruleValidate: { required: true, message: '姓名不能为空', trigger: 'blur' }
注意：对 inputNumber 组件进行校验时，需要配置 type:"number"
示例展示的是密码的二次确认及模拟的一个异步验证。
# 表单验证-rules验证(依赖async-validator)
Form 组件基于 async-validator (opens new window) 实现的数据验证，给 Form 设置属性 rules，同时给需要验证的 Form-item 设置属性 prop 指向对应字段即可。
完整的验证规则请参照开源项目 async-validator。
# 动态增减表单项
当需要动态维护 Form-item 时，也可以直接给 Form-item 设置属性 rules 来单独为该域做验证。
动态设置 Form-item 的 prop 属性时，会依据上层的 Form 组件的 model 来获取，查看示例代码。
Form-item 还可以独立设置 required、error 等属性，详见 API。
# 是否显示校验错误信息
showMessage 表示是否显示校验信息
:showMessage = false 可写在 form 或者 formItem 上
# 表单方法
validateField:对部分表单字段进行校验的方法，参数1为需校验的 prop，参数 2 为检验完回调，返回错误信息
# 表单排列(几列显示)
form 组件中 cols: 内置元素按几列显示,不超过 12 列，当 cols=0 时，隐藏该 form
formItem 组件中 cols: 当 form 组件设置 cols 时生效，表示当前元素占几列,不超过 form 中的 col,超过则失效按1列显示,当 cols=0 时，隐藏该 formItem
# 表单变色以及出错光标定位
当表单验证失败时，验证失败的表单会变成红色并出现错误提示。
在提交表单验证，失败后光标会自动定位到第一个出错的表单，并弹出错误提示。
# Form API
# Form props
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| model | 表单数据对象 | Object | - |
| rules | 表单验证规则，具体配置查看 async-validator (opens new window)注：formItem由组合组件构成时，必填标识在label左侧;同时,对inputNumber组件进行校验时，需要配置type:"number" | Object | - |
| inline | 是否开启行内表单模式 | Boolean | false |
| label-position | 表单域标签的位置，可选值为 left、right、top | String | right |
| label-width | 表单域标签的宽度，所有的 Form-item 都会继承 Form 组件的 label-width 的值,注：设置label时必须设置label-width | Number | - |
| showMessage | 是否显示校验错误信息 | Boolean | true |
| hideTipOnFocus | 此属性控制表单验证提示信息tip，当设置为true时，表单控件获取焦点将隐藏tip错误提示信息 | Boolean | false |
| cols | 几列显示(仅能0-12) | String | Number | - |
| errorFocus | 点击提交或者确认按钮时，当表单有验证不成功的时候，让第一个错误输入框获取焦点（限于能获取焦点的表单组件）(此属性只在1.0.9或以上版本有效) 建议不要与showTipsOnlyFocus一起使用 | Boolean | false |
| compareModel | 设置表单对比数据对象，用来对比使用，设置此属性后，在表单内数据发生变化时，数据字体变红(此属性只在1.0.9或以上版本有效) | Object | 无 |
| placement | form下所有可弹框组件的弹出框方向,级联选择除外(此属性只在1.0.15或以上版本有效) | top-start/top | null |
| label-wrap | form label是否换两行显示，多余部分不显示（不显示省略号）(此属性只在1.0.20或以上版本有效) | Boolean | - |
| onlyBlurRequire | 是否只在失去焦点的时候触发校验(v1.0.27) | Boolean | false |
| closeRuleChangeValidate | 关闭rule改变时的校验(v1.0.34) | Boolean | false |
| showTipsOnlyFocus | 仅在获取焦点时显示tips，焦点离开tips消失红框标注(v1.0.56) 建议不要与errorFocus一起使用 | Boolean | false |
| hoverValidate | 当鼠标hover在当前form-item项时,当出现当前表单项的错误提示tips,当鼠标移出当前项时，错误提示消失。(v1.0.75) 注意：支持blur, change验证时，出现错误提示。 设置showTipsOnlyFocus 只能在当前表单项聚焦的时候，有效。 表单项边框错误提示不变，消失的是tips提示。 | Boolean | false |
| hidePopperTime | 多少毫秒内关闭错误的tips提示（单位：ms） (v1.3.1) 优先级：form-item(hidePopperTime) > form(hidePopperTime) 注意： 当hidePopperTime小于等于0， 则设置失效 | Number | - 单位： ms |
# Form methods
| 方法名 | 说明 | 参数 |
|---|---|---|
| validate | 对整个表单进行校验，参数为检验完的回调，会返回一个 Boolean 表示成功与失败 | callback |
| validateField | 对部分表单字段进行校验的方法，参数1为需校验的 prop，参数2为检验完回调，返回错误信息 | callback |
| resetFields | 对整个表单进行重置，将所有字段值重置为空并移除校验结果,入参为true，表示不能对readonly字段清空，入参为false，可以对readonly字段清空，默认false(入参属性仅在1.0.24及其以上使用) | 无 |
| firstNodeFocused | 使form表单第一项且可获取焦点的表单组件获取焦点，请在表单存在时调用(v1.0.25) | 无 |
| resetValidate | 表单校验结果重置(v1.0.33) | 无 |
| resetValidateField | 单个formItem校验结果重置，参数1为formItem 的 prop(v1.0.33) | prop |
| resetValidateTips | 关闭表单项的错误提示(v1.0.75) 注意：表单项边框错误提示不变，消失的是tips提示。 | prop |
# FormItem props
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| prop | 对应表单域 model 里的字段 | String | - |
| label | 标签文本 | String | - |
| tipWidth | 错误提示信息tip的宽度 | Number | - |
| label-width | 表单域标签的的宽度,注：设置label时必须设置label-width | Number | - |
| required | 是否必填，如不设置，则会根据校验规则自动生成,注：formItem由组合组件构成时，必填标识在label右侧 | Boolean | - |
| validRules | 表单验证规则(优先级最高) | Array,String | - |
| rules | 表单验证规则,例：ruleValidate: { required: true, message: '姓名不能为空', trigger: 'blur' },注:对inputNumber组件进行校验时，需要配置type:"number"; | Object | Array | - |
| showMessage | 是否显示校验错误信息 | Boolean | true |
| cols | 几列显示(仅能0-12且小于form.cols) | String | Number | - |
| label-wrap | formItem label是否换两行显示，多余部分不显示（不显示省略号）(此属性只在1.0.20或以上版本有效) | Boolean | - |
| onlyBlurRequire | 是否只在失去焦点的时候触发校验,多选和单选按钮组无法失去焦点，故不支持此属性(v1.0.29) | Boolean | false |
| labelTitle | 鼠标移入label上时提示文字(v1.0.30) | String | -- |
| msgOffset | 设置校验信息相对form-item内容区域左边框向右偏移的距离(v1.0.31) | String | Number | 0 |
| strictly | 父组件 required 属性是否不受子组件影响(v1.0.43) | Boolean | false |
| marginLeftForce | 设置 margin-left 使用 !important (v1.0.43.patch1) | Boolean | false |
| showCloseIcon | 是否显示提示信息中的可关闭图标(v1.0.46) | Boolean | false |
| upward | 错误信息朝上显示(v1.0.59) | Boolean | false |
| isNotValid | 是否对当前项不校验及重置(v1.0.61) | Boolean | false |
| dependencies | 是否校验前置项，需开启required，传入前置项的prop，例：['name','age']，form上绑定on-check-failed事件，(v1.0.67) | Array | - |
| transfer | 是否将弹层放置于 body 内，建议添加此属性，它将不受父级样式影响，从而达到更好的效果(v1.0.67) 注意：由于层级z-index关系，在msgbox弹框内设置，建议在含有下拉框的表单组件设置transfer(比如：select、date等含有下拉面板的组件) 注意：在msgbox的form表单的form-item里面设置transfer属性，弹框不作处理关闭，会存在当前表单校验的错误提示未关闭的问题。（1.0.85） | Boolean | false |
| transferzIndex | 自定义设置formItem的下拉提示的z-index值 (v1.0.85) 注意：transferzIndex属性需要搭配transfer一起使用 | Number | 800 1001 （在msgbox里面） |
| hidePopperTime | 当前表单项在多少毫秒内关闭错误的tip提示信息 (v1.3.1) 优先级：form-item(hidePopperTime) > form(hidePopperTime) 注意： 当hidePopperTime小于等于0， 则设置失效 | Number | - 单位： ms |
# FormItem slot
| 名称 | 说明 |
|---|---|
| 无 | 内容 |
| label | label 内容 |