BasicForm 表单组件、使用方法、属性列表、表单验证

# 介绍

对 Antdv 的 Form 表单 (opens new window) 组件进行封装，通过非常便捷的配置完成表单渲染和表单验证。

请勿觉着 BasicForm 封装的太多，其实非常灵活，就像 Table 一样，只需编写 JS 即可渲染整个表单，其中：事件、属性、自定义、异步完全没有问题，复杂任意场景都可以通过“插槽”自定义，没有不能实现的表单。如果您的表单很大，可以异步加载，编写多个 BasicForm 或分多个 vue 组件，不存在任何性能瓶颈。您用起来试下，您就会爱上她。

v5.1.0 及之前版本： Antdv 2.x Form 表单 (opens new window)

# 使用

# 最简单示例

展示一个最简单表单的示例，只有一个输入框

<template>
  <div class="m-4">
    <BasicForm
      :labelWidth="100"
      :schemas="schemas"
      :showActionButtonGroup="true"
      :submitButtonOptions="{ text: '提交' }"
      :actionColOptions="{ span: 5 }"
      @submit="handleSubmit"
  </div>
</template>
<script lang="ts">
  import { defineComponent } from 'vue';
  import { BasicForm, FormSchema } from '/@/components/Form';
  import { useMessage } from '/@/hooks/web/useMessage';
  const schemas: FormSchema[] = [
      field: 'field',
      component: 'Input',
      label: '字段标签',
      colProps: {
        span: 8,
      defaultValue: '123',
      componentProps: {
        placeholder: '这是一个输入框',
        onChange: (e: ChangeEvent) => {
          console.log('change', e);
  export default defineComponent({
    components: { BasicForm },
    setup() {
      const { createMessage } = useMessage();
      return {
        schemas,
        handleSubmit: (values: any) => {
          createMessage.success('表单值: ' + JSON.stringify(values));
  });
</script>

# useForm 示例

页面表单推荐使用方法，方便传值和调用内部方法。

<template>
  <div class="m-4">
    <BasicForm @register="register" @submit="handleSubmit" />
  </div>
</template>
<script lang="ts">
  import { defineComponent } from 'vue';
  import { BasicForm, FormSchema, useForm } from '/@/components/Form/index';
  import { useMessage } from '/@/hooks/web/useMessage';
  const schemas: FormSchema[] = [
      field: 'field',
      component: 'Input',
      label: '字段标签',
      colProps: {
        span: 8,
      defaultValue: '123',
      componentProps: {
        placeholder: '这是一个输入框',
        onChange: (e: ChangeEvent) => {
          console.log('change', e.target.value);
  export default defineComponent({
    components: { BasicForm },
    setup() {
      const { createMessage } = useMessage();
      // 参数 props 内的值可以是 computed 或者 ref 类型
      const [register, methods] = useForm({
        labelWidth: 120,
        schemas,
        showActionButtonGroup: true,
        submitButtonOptions: {
          text: '提交',
        actionColOptions: {
          span: 5,
        // 是否禁用表单所有控件
        disabled: false,
      });
      return {
        register,
        schemas,
        handleSubmit: (values: any) => {
          // 更新字段值
          values.field = '456';
          methods.setFieldsValue(values);
          // 获取字段值
          const vals = methods.getFieldsValue();
          createMessage.success('表单值: ' + JSON.stringify(vals));
  });
</script>

# register

register 用于注册 useForm ，如果需要使用 useForm 提供的 api，必须将 register 传入组件的 @register

<template>
  <BasicForm @register="register" @submit="handleSubmit" />
</template>
<script>
  export default defineComponent({
    components: { BasicForm },
    setup() {
      const [register] = useForm();
      return {
        register,
  });
</script>

# methods

getFieldsValue

类型: () => Recordable;

说明: 获取表单值

setFieldsValue

类型: <T>(values: T) => Promise<void>

说明: 设置表单字段值

resetFields

类型: ()=> Promise<any>

说明: 重置表单值

validateFields

类型: (nameList?: NamePath[]) => Promise<any>

说明: 校验指定表单项

validate

类型: (nameList?: NamePath[]) => Promise<any>

说明: 校验整个表单

submit

类型: () => Promise<void>

说明: 提交表单

scrollToField

类型: (name: NamePath, options?: ScrollOptions) => Promise<void>

说明: 滚动到对应字段位置

clearValidate

类型: (name?: string | string[]) => Promise<void>

说明: 清空校验

setProps

类型: (formProps: Partial<FormProps>) => Promise<void>

说明: 设置表单 Props

removeSchemaByFiled

类型: (field: string | string[]) => Promise<void>

说明: 根据 field 删除 Schema

appendSchemaByField

类型: ( schema: FormSchema, prefixField: string | undefined, first?: boolean | undefined ) => Promise<void>

说明: 插入到指定 filed 后面，如果没传指定 field，则插入到最后,当 first = true 时插入到第一个位置

updateSchema

类型: (data: Partial<FormSchema> | Partial<FormSchema>[]) => Promise<void>

说明: 更新表单的 schema, 只更新函数所传的参数

e.g

updateSchema({ field: 'filed', componentProps: { disabled: true } });
updateSchema([
  { field: 'filed', componentProps: { disabled: true } },
  { field: 'filed1', componentProps: { disabled: false } },
]);

# 属性

# ColEx 布局类型

常用属性：span、offset、plus、xs、sm、md、lg、xl、xxl

详细见 src/components/Form/src/types/index.ts (opens new window)

# fieldMapToTime 日期转换

将表单内时间区域的值映射成 2 个字段

如果表单内有时间区间组件，获取到的值是一个数组，但是往往我们传递到后台需要是 2 个字段

useForm({
  fieldMapToTime: [
    // data为时间组件在表单内的字段，startTime，endTime为转化后的开始时间于结束时间
    // 'YYYY-MM-DD'为时间格式，参考moment
    ['datetime', ['startTime', 'endTime'], 'YYYY-MM-DD'],
    // 支持多个字段
    ['datetime1', ['startTime1', 'endTime1'], 'YYYY-MM-DD HH:mm:ss'],
});
// fieldMapToTime没写的时候表单获取到的值
  datetime: [Date(),Date()]
//  ['datetime', ['startTime', 'endTime'], 'YYYY-MM-DD'],之后
    datetime: [Date(),Date()],
    startTime: '2020-08-12',
    endTime: '2020-08-15',

# FormSchema 控件设置

RenderCallbackParams

export interface RenderCallbackParams {
  schema: FormSchema;
  values: any;
  model: any;
  field: string;

componentProps

• 当值为对象类型时,该对象将作为 component 所对应组件的的 props 传入组件

• 当值为一个函数时候

参数有 4 个

schema : 表单的整个 schemas

formActionType : 操作表单的函数。与 useForm 返回的操作函数一致

formModel : 表单的双向绑定对象，这个值是响应式的。所以可以方便处理很多操作

tableAction : 操作表格的函数，与 useTable 返回的操作函数一致。注意该参数只在表格内开启搜索表单的时候有值，其余情况为 null ,

• 简单例子，值改变的时候操作表格或者修改表单内其他元素的值，实现 组件联动 ：

{
  component: 'Input',
  componentProps: ({ schema, tableAction, formActionType, formModel }) => {
    return {
      // xxxx props
      onChange: (e: ChangeEvent) => {
        const { reload } = tableAction
        reload()
        // or
        formModel.xxx = '123'

HelpComponentProps

export interface HelpComponentProps {
  maxWidth: string;
  // 是否显示序号
  showIndex: boolean;
  // 文本列表
  text: any;
  // 颜色
  color: string;
  // 字体大小
  fontSize: string;
  icon: string;
  absolute: boolean;
  // 定位
  position: any;

# ComponentType 组件类型

表单组件的组件类型 src/components/Form/src/componentMap.ts (opens new window)

export type ComponentType =
  | 'Input'
  | 'InputGroup'
  | 'InputPassword'
  | 'InputSearch'
  | 'InputTextArea'
  | 'InputNumber'
  | 'InputCountDown'
  | 'Select'
  | 'TreeSelect'
  | 'RadioButtonGroup'
  | 'RadioGroup'
  | 'Checkbox'
  | 'CheckboxGroup'
  | 'AutoComplete'
  | 'Cascader'
  | 'DatePicker'
  | 'MonthPicker'
  | 'RangePicker'
  | 'WeekPicker'
  | 'TimePicker'
  | 'Switch'
  | 'StrengthMeter'
  | 'Upload'
  | 'IconPicker'
  | 'Render'
  | 'Slider'
  | 'Rate'
  | 'None'
  | 'Divider'
  | 'FormGroup';

详细用法，可看本文： 内置组件

# 自定义组件

ComponentType 内置组件，无法满足所有需求，这是您可以自定义渲染组件内容

# slot 插槽方式

自定义渲染内容

<template>
  <div class="m-4">
    <BasicForm @register="register">
      <template #customSlot="{ model, field }">
        <a-input v-model:value="model[field]" />
      </template>
    </BasicForm>
  </div>
</template>
<script lang="ts">
  import { defineComponent } from 'vue';
  import { BasicForm, FormSchema, useForm } from '/@/components/Form';
  export default defineComponent({
    name: 'FormDemo',
    components: { BasicForm },
    setup() {
      const schemas: FormSchema[] = [
          field: 'field1',
          component: 'Input',
          defaultValue: '123',
          label: '字段1',
          slot: 'customSlot',
      const [register] = useForm({
        labelWidth: 100,
        actionColOptions: {
          span: 24,
        schemas,
      });
      return {
        register,
  });
</script>

# render 函数式

自定义渲染内容

<template>
  <div class="m-4">
    <BasicForm @register="register" @submit="handleSubmit" />
  </div>
</template>
<script lang="ts">
  import { defineComponent, h } from 'vue';
  import { BasicForm, FormSchema, useForm } from '/@/components/Form/index';
  import { useMessage } from '/@/hooks/web/useMessage';
  import { Input } from 'ant-design-vue';
  const schemas: FormSchema[] = [
      field: 'field1',
      component: 'Input',
      label: '字段1',
      colProps: {
        span: 8,
      rules: [{ required: true }],
      // 通过函数渲染一个 Input
      render: ({ model, field }) => {
        return h(Input, {
          placeholder: '请输入',
          value: model[field],
          onChange: (e: ChangeEvent) => {
            model[field] = e.target.value;
        });
      field: 'field2',
      component: 'Input',
      label: '字段2',
      colProps: {
        span: 8,
      rules: [{ required: true }],
      // 指定 Input 的 slot
      renderComponentContent: () => {
        return {
          suffix: () => 'suffix',
  export default defineComponent({
    components: { BasicForm },
    setup() {
      const { createMessage } = useMessage();
      const [register, { setProps }] = useForm({
        labelWidth: 100,
        schemas,
        showActionButtonGroup: true,
        submitButtonOptions: {
          text: '提交',
        actionColOptions: {
          span: 8,
      });
      return {
        register,
        schemas,
        handleSubmit: (values: any) => {
          createMessage.success('表单值: ' + JSON.stringify(values));
        setProps,
  });
</script>

# 新建组件方式

方式 1

在 src/components/Form/src/componentMap.ts (opens new window) 内，添加需要的组件，并在上方 ComponentType 添加相应的类型 key

这种写法适用与适用频率较高的组件

componentMap.set('componentName', 组件);
// ComponentType
export type ComponentType = xxxx | 'componentName';

方式 2

使用 useComponentRegister 进行注册

这种写法只能在当前页使用，页面销毁之后会从 componentMap 删除相应的组件

import { useComponentRegister } from '/@/components/Form';
import { StrengthMeter } from '@/components/StrengthMeter';
useComponentRegister('StrengthMeter', StrengthMeter);

# 显示禁用

自定义表单控件的：显示/禁用（ifShow/show/dynamicDisabled）

区别：ifShow 是否渲染组件；show 正常渲染组件，确定是否显示（display: none）

<template>
  <div class="m-4">
    <BasicForm @register="register" />
  </div>
</template>
<script lang="ts">
  import { defineComponent } from 'vue';
  import { BasicForm, FormSchema, useForm } from '/@/components/Form/index';
  const schemas: FormSchema[] = [
      field: 'field1',
      component: 'Input',
      label: '字段1',
      colProps: {
        span: 8,
      show: ({ values }) => {
        return !!values.field5;
      field: 'field2',
      component: 'Input',
      label: '字段2',
      colProps: {
        span: 8,
      ifShow: ({ values }) => {
        return !!values.field6;
      field: 'field3',
      component: 'DatePicker',
      label: '字段3',
      colProps: {
        span: 8,
      dynamicDisabled: ({ values }) => {
        return !!values.field7;
  export default defineComponent({
    components: { BasicForm },
    setup() {
      const [register, { setProps }] = useForm({
        labelWidth: 120,
        schemas,
        actionColOptions: {
          span: 24,
      });
      return {
        register,
        schemas,
        setProps,
  });
</script>

# 表单验证

{
  label: t('员工工号'),
  field: 'employee.empNo',
  component: 'Input',
  componentProps: {
    maxlength: 32,
  required: false, // 如果只是必填，可以这样简写，否则使用 rules
  rules: [
    // 是否必填
    { required: false },
    // 长度校验
    { min: 4, max: 20, message: t('请输入长度在 4 到 20 个字符之间') },
    // 邮箱校验
    { type: 'email', message: t('请填写正确的邮箱地址') }
    // 正则表达式校验
    { pattern: /^[\u0391-\uFFE5\w]+$/, message: t('不能输入特殊字符') },
    // 自定义验证，举例：远程验证工号是否存在
      validator(_rule, value) {
        return new Promise((resolve, reject) => {
          if (!value || value === '') return resolve();
          checkEmpNo(record.value.employee?.empNo || '', value)
            .then((res) => (res ? resolve() : reject(t('员工工号已存在'))))
            .catch((err) => reject(err.message || t('验证失败')));
        });
    // 高级示例：跨字段校验，如：密码与确认密码是否相同
      field: 'newPassword',
      label: '新密码',
      component: 'StrengthMeter',
      componentProps: {
        placeholder: '新密码',
      rules: [
          required: true,
          message: '请输入新密码',
      field: 'confirmNewPassword',
      label: '确认密码',
      component: 'InputPassword',
      dynamicRules: ({ values }) => {
        return [
            required: true,
            validator: (_, value) => {
              if (!value) {
                return Promise.reject('密码不能为空');
              if (value !== values.newPassword) {
                return Promise.reject('两次输入的密码不一致!');
              return Promise.resolve();
  ifShow: () => op.value === 'add' || op.value === 'edit',

更多： Antdv Form 校验规则 (opens new window) v5.1.0 及之前版本： Antdv 2.x Form 校验规则 (opens new window)

更多高级用法可研究 async-validator (opens new window) 。

# 表单插槽

Slots

# 内置组件

# Select 下拉选择

在 Antdv 的 Select 选择器 (opens new window) 基础之上封装，支持：字典数据、远程API数据、单选或多选。

v5.1.0 及之前版本： Antdv 2.x Select 选择器 (opens new window)

# 使用

const schemas: FormSchema[] = [
    label: '下拉框',
    field: 'testSelect',
    component: 'Select',
    componentProps: {
      // 数据源1：固定数据
      options: [
        { label: '选项1', value: '11' },
        { label: '选项2', value: '22' },
      // 数据源2：动态数据
      // api: testDataSelectApi
      // params: {},
      // 数据源3：字典数据
      // dictType: 'sys_menu_type',
      allowClear: true,
      mode: 'multiple', // 多选

# 属性

其它属性： Antdv Select 属性 (opens new window) v5.1.0 及之前版本： Antdv 2.x Select 属性 (opens new window)

OptionsItem

# TreeSelect 下拉选择树

在 antdv 的 TreeSelect 选择器 (opens new window) 基础之上封装，支持：字典数据、远程API数据、单选或多选。

v5.1.0 及之前版本： Antdv 2.x TreeSelect 选择器 (opens new window)

# 使用

const schemas: FormSchema[] = [
    label: '用户选择',
    field: 'testUser.userCode',
    fieldLabel: 'testUser.userName',
    component: 'TreeSelect',
    componentProps: {
      // 数据源1：固定数据
      treeDataSimpleMode: false,
      treeData: [
          id: '1',
          name: 'tree 1',
          disabled: true,
          children: [
            { id: '1-1', name: 'tree 1-1' },
            { id: '1-2', name: 'tree 1-2' },
          id: '2',
          name: 'tree 2',
          disabled: true,
          children: [
            { id: '2-1', name: 'tree 2-1' },
            { id: '2-2', name: 'tree 2-2' },
      // 数据源2：动态数据
      // api: officeTreeData,
      // params: { isLoadUser: true, userIdPrefix: '' },
      // canSelectParent: false,
      // 数据源3：字典数据
      // dictType: 'sys_menu_type',
      allowClear: true,

# 属性

其它属性： Antdv TreeSelect 属性 (opens new window) v5.1.0 及之前版本： Antdv 2.x TreeSelect 属性 (opens new window)

# ListSelect 列表选择树

列表选择，展现为可搜索的输入选择框，点击后弹出对话框，体现列表形式选择数据。

相比 TreeSelect 性能更好，支持大数据，异步加载组件和数据、单选或多选。

# 使用

const schemas: FormSchema[] = [
    label: '列表选择',
    field: 'customCode',
    fieldLabel: 'customName',
    component: 'ListSelect',
    componentProps: {
      // 内置列表选择类型：
      // 1）userSelect：用户选择；
      // 2）empUserSelect：员工选择（含组织机构信息）
      // 3）自定义，详见下一节
      selectType: 'userSelect',

# 扩展选择 selectType

上面介绍了，默认内置列表选择类型，本节主要介绍如何自定义业务选择。

1. 复制 /src/components/ListSelect/src/selectType/userSelect.ts 文件
2. 到当前目录下，重命名为 customSelect.ts 该文件名为 ListSelect 的 selectType 参数值
3. 修改 customSelect.ts 文件内容，自定义您的业务选择列表的 searchForm 和 tableColumns
4. 修改 export default 中的 itemCode 和 itemName 为选择后返回的字段名
5. 用法：

const schemas: FormSchema[] = [
    label: '用户选择',
    field: 'userCode',
    fieldLabel: 'userName',
    component: 'ListSelect',
    componentProps: {
      // 指定自定义的选择类型
      selectType: 'customSelect',

# 属性

# RadioGroup 单选按钮组

在 Antdv 的 Radio 单选框 (opens new window) 基础之上封装，支持：字典数据。

v5.1.0 及之前版本： Antdv 2.x Radio 选择器 (opens new window)

# 使用

const schemas: FormSchema[] = [
    label: '按钮组',
    field: 'menuType',
    component: 'RadioGroup',
    componentProps: {
      // 数据源1：固定数据
      options: [
        { label: '选项1', value: '11' },
        { label: '选项2', value: '22' },
      // 数据源2：字典数据
      // dictType: 'sys_menu_type',

# 属性

# RadioButtonGroup 按钮风格

在 Antdv 的 Radio 单选框 (opens new window) 基础之上封装，支持：字典数据。

v5.1.0 及之前版本： Antdv 2.x Radio 选择器 (opens new window)

# 使用

const schemas: FormSchema[] = [
    label: '按钮组',
    field: 'menuType',
    component: 'RadioButtonGroup',
    componentProps: {
      // 数据源1：固定数据
      options: [
        { label: '选项1', value: '11' },
        { label: '选项2', value: '22' },
      // 数据源2：字典数据
      // dictType: 'sys_menu_type',

# 属性

# CheckboxGroup 复选框组

在 Antdv 的 Checkbox 多选框 (opens new window) 基础之上封装，支持：字典数据。

v5.1.0 及之前版本： Antdv 2.x Checkbox 多选框 (opens new window)

# 使用

const schemas: FormSchema[] = [
    label: '按钮组',
    field: 'menuType',
    component: 'CheckboxGroup',
    componentProps: {
      // 数据源1：固定数据
      options: [
        { label: '选项1', value: '11' },
        { label: '选项2', value: '22' },
      // 数据源2：字典数据
      // dictType: 'sys_menu_type',

# 属性

# RangePicker 日期范围

使用 Antdv 的 DatePicker 日期选择框 (opens new window) 组件，常用于搜索栏的日期范围查询条件。

v5.1.0 及之前版本： Antdv 2.x DatePicker 日期选择框 (opens new window)

const searchForm: FormProps = {
  baseColProps: { lg: 6, md: 8 },
  labelWidth: 90,
  schemas: [
      label: t('创建时间'),
      field: 'dateRange',
      component: 'RangePicker',
      componentProps: {},
  // 定义自动转换规则[ [ 日期控件定义字段名, [ 开始日期查询参数, 结束日期查询参数 ] ] ]
  fieldMapToTime: [['dateRange', ['beginDate', 'endDate']]],

# Upload 图片/文件上传

支持表单附件上传和编辑表格附件上传，可参考： testData/form.vue (opens new window)

# 使用

表单附件上传：

const inputFormSchemas: FormSchema[] = [
    label: t('图片上传'),
    field: 'dataMap',
    component: 'Upload',
    componentProps: {
      loadTime: computed(() => record.value.__t),
      bizKey: computed(() => record.value.id),
      bizType: 'testData_image',
      uploadType: 'image',
    colProps: { lg: 24, md: 24 },
    label: t('文件上传'),
    field: 'dataMap',
    component: 'Upload',
    componentProps: {
      loadTime: computed(() => record.value.__t),
      bizKey: computed(() => record.value.id),
      bizType: 'testData_file',
      uploadType: 'all',
    colProps: { lg: 24, md: 24 },
// 不可缺少，放在设置 record.value 代码后，用于更新上传列表
record.value = (res.testData || {}) as TestData;
record.value.__t = new Date().getTime();

编辑表格附件上传：

<template>
  <BasicTable>
    <template #testDataChildUpload="{ record: childRecord }">
      <BasicUpload
        v-model:value="childRecord.dataMap"
        :bizKey="childRecord.id"
        :bizType="'testDataChild_file'"
        :uploadType="'all'"
        :loadTime="record.__t"
    </template>
  </BasicTable>
</template>
<script lang="ts" setup>
  const testDataChildColumns: BasicColumn[] = [
      title: t('文件上传'),
      dataIndex: 'upload',
      width: 160,
      align: 'left',
      // 个性化列，可定义插槽（如样式，增加控件等）
      slots: { customRender: 'testDataChildUpload' }, // 5.1.0 及之前
      slot: 'testDataChildUpload', // 5.2.0+ （Antdv 3.x 不再使用 slots）
  ]);
</script>

# 属性

UploadType

# 事件

# Text 文本显示

支持 HTML、数据字典、文本内容的展示。

# 使用

const schemas: FormSchema[] = [
    label: '文本内容',
    field: 'testInput',
    component: 'Text',
    componentProps: {
      dictType: 'sys_yes_no',
      isHtml: false,

# 属性

# Divider 分隔符

使用 Antdv 的 Divider 分割线 (opens new window) 组件。 Divider 类型用于在 schemas 中占位，将会渲染成一个分割线（始终占一整行的版面），可以用于较长表单的版面分隔。请只将 Divider 类型的 schema 当作一个分割线，而不是一个常规的表单字段。

v5.1.0 及之前版本： Antdv 2.x Divider 分割线 (opens new window)

• 仅在 showAdvancedButton 为 false 时才显示（也就是说如果启用了表单收起和展开功能时不会显示）
• 使用 schema 中的 label 以及 helpMessage 来渲染分割线中的提示内容或标题
• 使用 componentProps 来设置除 type 之外的属性，如：dashed是否虚线、orientation标题的位置

const inputFormSchemas: FormSchema[] = [
    label: '',
    field: 'detailInfo',
    component: 'Divider',
    colProps: { lg: 24, md: 24 },

# FormGroup 子表单

FormGroup 类型与 Divider 类似，将会渲染成一个带表单子标题的分割线（占一整行的版面）不是一个常规的表单字段。

const inputFormSchemas: FormSchema[] = [
    label: t('详细信息'),
    field: 'detailInfo',
    component: 'FormGroup',
    colProps: { lg: 24, md: 24 },