Ant Design Vue-Form 学习 --持续更新

段干楚青
2023-12-01

Ant Design Vue

Form 表单

表单填写在日常工作中收录信息比较常用,
antd 中 form 用于创建一个实体收集信息,并且可以对输入的数据类型进行校验。

1. 表单排列

这里指的是 表单的标签和控件的排列方式

  • 水平
  • 垂直
  • 行内

2. 表单域

表单·一定会·包含表单域, 表单域 可以是

  • 输入控件
  • 标签
  • 下拉菜单
  • 文本域等等
    antd 封装了表单域 <Form.item />

注意点
1、如果使用 Form.create 处理表单使其具有自动收集数据并校验的功能,建议使用jsx。<.jsx>https://typescript.bootcss.com/jsx.html

  • 我不熟悉jsx语法,所以使用 template 方式使用form

2、如果不是使用Vue.use(Form)形式注册的Form组件,你需要自行在main.js文件中将$form挂载到Vue原型上。Vue.prototype.$form = Form

3. 使用

<template>
  <a-form :form="form">
    <a-form-item label="Note">
      <a-input 
      v-decorator="['note', { rules: [{ required: true, message: 'Please input your note!' }] }]"
      >
    </a-form-item>
  </a-form>
</template>

4.apis 释义

Form

1. :form=“form”

动态数据绑定,这个没啥说的,但是这里需要注意的data中的form的创建形式

  • 直接指定一个Object对象{}
  • 使用Form.create来创建
    • jsx方式 自己不熟悉,不用
    • template 方式使用。

我们先来说第二种,官方用的最多,上代码

///.....vue 实例
  data() {
    return {
      form: this.$form.createForm(this, { name: 'coordinated' }),
    };
  },
//...
- form -官方文档

formForm.create() 包装过的组件会自带 this.form 属性,如果使用 template 语法,可以使用 this.$form.createForm(this, options) 类型是 object 默认参数 无

- form -我的理解
  • data中的form 是一个经过antd($form.create)方法包装过的属性

  • 参数中的this 是 组件实例本身 与 其他配置中的this一样使用

    • Form.create(options) | this.$form.createForm(this, options)
    <template>
      <a-form :form="form" />
    </template>
    <script>
      export default {
        beforeCreate() {
          this.form = this.$form.createForm(this, options);
        },
      };
    </script>
    
- Form.create(options) | this.$form.createForm(this, options) --> options api 理解

参数 options

  • options: 只记录与 template 用法相关
    • name—设置表单域内字段id的前缀
    • validateMessages 默认校验信息,可用于把默认错误信息改为中文等,格式与 newMessages 返回值一致 Object { [nested.path]: String }
    • onValuesChange 任一表单域的值发生改变时的回调 (props, values) => void
- Form.create this.form 的apis

经过 Form.create 包装的组件将会自带 this.form 属性,this.form 提供的 API 如下:

注意:使用 getFieldsValue,getFieldValue,setFieldsValue 等时,应确保对应的 field 已经用 getFieldDecorator 或 v-decorator 注册过了。

如下:
<a-input
v-decorator="[‘note’, { rules: [{ required: true, message: ‘Please input your note!’ }] }]"
>

1.getFieldDecorator 用于和表单进行双向绑定,单文件 template 可以使用指令v-decorator进行绑定,详见下方描述
  • this.form.getFieldDecorator(id, options)v-decorator="[id, options]"
    经过 getFieldDecoratorv-decorator 包装的控件,表单控件会自动添加 value(或 valuePropName 指定的其他属性) onChange(或 trigger 指定的其他属性),数据同步将被 Form 接管,这会导致以下结果:
    1. 你不再需要也不应该用 onChange 来做同步,但还是可以继续监听 onChange 等事件。

    2. 你不能用控件的 value defaultValue 等属性来设置表单域的值,默认值可以用 getFieldDecoratorv-decorator 里的 initialValue。

    3. 你不应该用 v-model,可以使用 this.form.setFieldsValue 来动态改变表单值。

this.form.getFieldDecorator(id, options) //通过装饰id 此组件就是form.create装饰过的了

v-decorator="[id, options]"

  • 参数解释

    -id,必填!!!输入控件的唯一标志,支持嵌套式的写法?是不是 html 标签中 id 就可以作为唯一标志??>>测试!!

    • options.getValueFromEvent 可以把 onChange 的参数(如 event)转化为控件的值
      • 不再使用onChange作为同步方法,使用此配置项配置方法
    • options.initialValue 子节点的初始值,类型、可选值均由子节点决定
      • (注意:由于内部校验时使用 === 判断是否变化,建议使用变量缓存所需设置的值,而非直接使用字面量)
      • eg:{initialValue:value} value 是data中的变量或者父组件的变量
    • options.normalize 转换默认的 value 给控件
     <template>
      <a-form
        :autoFormCreate="
          (form) => {
            this.form = form;
          }
        "
      >
        <a-form-item
          fieldDecoratorId="fruits"
          :fieldDecoratorOptions="{ normalize: this.normalizeAll }"
        >
          <a-checkbox-group :options="options" />
        </a-form-item>
      </a-form>
    </template>
    
    <script>
    export default {
      data() {
        return {
          options: [
            { label: "All", value: "All" },
            { label: "Apple", value: "Apple" },
            { label: "Pear", value: "Pear" },
            { label: "Orange", value: "Orange" },
          ],
        };
      },
      methods: {
        normalizeAll(value, prevValue = [], allValues) {
          console.log(allValues);
          if (value.indexOf("All") >= 0 && prevValue.indexOf("All") < 0) {
            return ["All", "Apple", "Pear", "Orange"];
          }
          if (value.indexOf("All") < 0 && prevValue.indexOf("All") >= 0) {
            return [];
          }
          return value;
        },
      },
    };
    </script>
    
    
    • options.preserve即便字段不再使用,也保留该字段的值

    • options.rules 校验规则,参考下方:

      参数说明类型默认值
      enum枚举类型string-
      message校验文案string-
      min最小长度number-
      pattern正则表达式校验RegExp-
      required是否必选booleanfalse
      transform校验前转换字段值function ( value) => transformedValue:any-
      len字段长度number-
      max最大长度number-
      type内建校验类型,可选项string‘string’
      validator自定义校验(注意,callback必须被调用)function (rule, value, callback)
      whitespace必选时,空格是否会被视为错误booleanfalse
    • options.trigger 收集子节点的值的时机 触发的方法 类型 string 默认值'change'

    • options.validateFirst 当某一规则校验不通过时,是否停止剩下的规则的校验 类型 boolean默认值 false

    • options.validateTrigger 校验子节点值的时机 验证子节点时触发的方法 类型string|string[] 默认值'change'

    • options.valuePropName 子节点的值的属性,如 Switch 的是 'checked'类型 string默认值 'value'

      • 有的组件的值并不是通过 value 获取的,需要另外提供
      • <a-switch v-decorator="['switch', { valuePropName: 'checked' }]" />
2. getFieldError 获取某个输入控件的 Error 类型:-Function(name)
3. getFieldsError 获取一组输入控件的 Error ,如不传入参数,则获取全部组件的 Error 类型:-Function([names: string[]])
4. getFieldsValue 获取一组输入控件的值,如不传入参数,则获取全部组件的值 类型:-Function([fieldNames: string[]])
5. getFieldValue 获取一个输入控件的值 类型:-Function(fieldName: string)
6. isFieldsTouched 判断是否任一输入控件经历过 getFieldDecoratorv-decorator 的值收集时机 options.trigger 类型:(names?: string[]) => boolean
7. isFieldTouched 判断一个输入控件是否经历过 getFieldDecorator 或 v-decorator 的值收集时机 options.trigger 类型:(name: string) => boolean
8. isFieldValidating 判断一个输入控件是否在校验状态 类型:-Function(name)
9. resetFields 重置一组输入控件的值(为 initialValue)与状态,如不传入参数,则重置所有组件 类型:-Function([names: string[]])
10. setFields 设置一组输入控件的值与错误状态。 类型:-Function({ [fieldName]: { value: any, errors: [Error] } })
11. setFieldsValue 设置一组输入控件的值类型:-Function({ [fieldName]: value })
12. validateFields 校验并获取一组输入域的值与 Error,若 fieldNames 参数为空,则校验全部组件 类型:-Function([fieldNames: string[]], [options: object], callback: Function(errors, values))
13. validateFieldsAndScrollvalidateFields 相似,但校验完后,如果校验不通过的菜单域不在可见范围内,则自动滚动进可见范围 类型:-参考 validateFields
  • validateFields/validateFieldsAndScroll 用法:
const {
  form:{validateFields},
} = this
//1.简单模式 只有回调函数 callback 下方有示例
validateFields((errors,values)=>{
  //...错误信息,验证值
})
// 2.中等模式
validateFields(['field1', 'field2'], (errors, values) => {
  // ...验证表单域名 - 不传则校验全部
});
//3.全负荷模式
validateFields(['field1', 'field2'], options, (errors, values) => {
  // ... options校验规则
});
  • options.first 若为 true,则每一表单域的都会在碰到第一个失败了的校验规则后停止校验 类型:boolean 默认值 false
  • options.firstFields 指定表单域会在碰到第一个失败了的校验规则后停止校验 String[] []
  • options.force 对已经校验过的表单域,在 validateTrigger 再次被触发时是否再次校验 boolean f`alse
  • options.scroll 定义 validateFieldsAndScroll 的滚动行为, Object {}

validateFieldscallback 参数示例:

  • errors

    {
      "userName": {
        "errors": [
          {
            "message": "Please input your username!",
            "field": "userName"
          }
        ]
      },
      "password": {
        "errors": [
          {
            "message": "Please input your Password!",
            "field": "password"
          }
        ]
      }
    
    }
    
  • values

    {
      "userName": {
        "errors": [
          {
            "message": "Please input your username!",
            "field": "userName"
          }
        ]
      },
      "password": {
        "errors": [
          {
            "message": "Please input your Password!",
            "field": "password"
          }
        ]
      }
    }
    

2. hideRequiredMark 隐藏所有表单项的必选标记 Boolean false

3. labelAlign label 标签的文本对齐方式 'left' |'right' 'right' 1.5.0

4. layout 表单布局 'horizontal'|'vertical'|'inline' 默认:'horizontal'

5. labelCol label 标签布局,同 <a-col> 组件,设置 span offset 值,如 {span: 3, offset: 12}sm: {span: 3, offset: 12} 类型:object

6. wrapperCol 需要为输入控件设置布局样式时,使用该属性,用法同 labelCol object

7. selfUpdate 自定义字段更新逻辑,说明见下,需 1.3.17 版本以上 boolean false 1.3.17

8. colon 配置 Form.Itemcolon 的默认值 (只有在属性 layouthorizontal 时有效)类型boolean 默认值true 1.5.0

 类似资料: