useForm属性

useForm 中存在一些方法和属性，例如“固定标题长度”、“获取表单值”、“清空表单验证”等

`userForm` 其它属性介绍

1. 固定label标题的宽度

通过labelCol或者labelWidth来控制标题的宽度

页面效果
示例代码

“姓名、年龄”左侧的距离，就是标题所占的宽度

labelCol、labelWidth效果一致，只用一种方法即可

<template>
  <!-- 自定表单 -->
  <BasicForm @register="registerForm" @submit="handleSubmit" style="margin-top: 50px" />
</template>

<script lang="ts" setup>
  //引入依赖
  import { useForm, BasicForm, FormSchema } from '/@/components/Form';

  //自定义表单字段
  const formSchemas: FormSchema[] = [
    {
      label: '姓名',
      field: 'name',
      component: 'Input',
    },
    {
      label: '年龄',
      field: 'password',
      component: 'InputNumber',
    },
    {
      label: '生日',
      field: 'birthday',
      component: 'DatePicker',
    },
    {
      label: '头像',
      field: 'avatar',
      component: 'JImageUpload',
    },
  ];

  /**
   * BasicForm绑定注册;
   */
  const [registerForm] = useForm({
    //注册表单列
    schemas: formSchemas,
    showResetButton: false,
    submitButtonOptions: { text: '提交', preIcon: '' },
    actionColOptions: { span: 17 },
    //使用labelCol的样式参数来控制标题宽度
    labelCol: { style: { width: '150px' } },
    //字体对齐方式（left:左对齐，right：右对齐），默认右对齐
    labelAlign:'right'
  });

  /**
   * 点击提交按钮的value值
   * @param values
   */
  function handleSubmit(values: any) {
    console.log('提交按钮数据::::', values);
  }
</script>

<style scoped>
  /** 时间和数字输入框样式 */
  :deep(.ant-input-number) {
    width: 100%;
  }

  :deep(.ant-picker) {
    width: 100%;
  }
</style>

2. 标题与字段布局

通过userForm中的参数labelCol和wrapperCol可以实现自适应宽度

2.1 效果及代码展示

页面效果
示例代码

页面宽度大于1200px时的展示效果

页面小于576px时的展示效果

响应式布局用法，其他参数请参考2.2 labelCol和wrapperCol参数

<!-- 标题与字段布局 -->
<template>
  <!-- 自定表单 -->
  <BasicForm @register="registerForm" style="margin: 50px 50px 0 50px" />
</template>

<script lang="ts" setup>
  //引入依赖
  import { useForm, BasicForm, FormSchema } from '/@/components/Form';

  //自定义表单字段
  const formSchemas: FormSchema[] = [
    {
      label: '姓名',
      field: 'name',
      component: 'Input',
    },
    {
      label: '年龄',
      field: 'password',
      component: 'InputNumber',
    },
    {
      label: '生日',
      field: 'birthday',
      component: 'DatePicker',
    },
    {
      label: '头像',
      field: 'avatar',
      component: 'JImageUpload',
    },
  ];

  /**
   * BasicForm绑定注册;
   */
  const [registerForm] = useForm({
    //注册表单列
    schemas: formSchemas,
    showActionButtonGroup: false,
    actionColOptions: { span: 12 },
    //控制标题宽度占比
    labelCol: {
      xs: 2,
      sm: 2,
      md: 2,
      lg: 9,
      xl: 3,
      xxl: 2,
    },
    //控制组件宽度占比
    wrapperCol: {
      xs: 15,
      sm: 14,
      md: 16,
      lg: 17,
      xl: 19,
      xxl: 20,
    },
  });
</script>

<style scoped>
  /** 时间和数字输入框样式 */
  :deep(.ant-input-number) {
    width: 100%;
  }

  :deep(.ant-picker) {
    width: 100%;
  }
</style>

2.2 `labelCol`和`wrapperCol` 属性

成员	说明	类型
flex	flex 布局填充	string
offset	栅格左侧的间隔格数，默认值为0	number
order	栅格顺序，`flex` 布局模式下有效，默认值为0	number
pull	栅格向左移动格数，默认值为0	number
push	栅格向右移动格数，默认值为0	number
span	栅格占位格数，为 0 时相当于 `display: none`	number
xs	`<576px` 响应式栅格	number
sm	`≥576px` 响应式栅格	number
md	`≥768px` 响应式栅格	number
lg	`≥992px` 响应式栅格	number
xl	`≥1200px` 响应式栅格	number
xxl	`≥1600px` 响应式栅格	number

3. 表单布局

表单有两种不同的布局方式，我们可以通过参数layout改变表单布局。

页面效果
示例代码

layout属性支持vertical（标题在上，组件在下），horizontal（左侧为标题，右侧为组件）

布局为vertical时的效果

布局为horizontal时的效果

代码示例

<!-- 表单布局 -->
<template>
  <!-- 自定义表单 -->
  <BasicForm @register="registerForm" style="margin: 50px 50px 0 50px" />
</template>

<script lang="ts" setup>
  //引入依赖
  import { useForm, BasicForm, FormSchema } from '/@/components/Form';

  //自定义表单字段
  const formSchemas: FormSchema[] = [
    {
      label: '会议名称',
      field: 'name',
      component: 'Input',
    },
    {
      label: '参会地点',
      field: 'meetingLocation',
      component: 'Input',
    },
    {
      label: '参与人数',
      field: 'numberOfPart',
      component: 'InputNumber',
    },
    {
      label: '会议纪要',
      field: 'meetingMinutes',
      component: 'JUpload',
    },
  ];

  /**
   * BasicForm绑定注册;
   */
  const [registerForm] = useForm({
    //注册表单列
    schemas: formSchemas,
    //不显示查询和重置按钮
    showActionButtonGroup: false,
    //默认row行配置,当 layout 为 horizontal 生效
    rowProps: { gutter: 24, justify: 'center', align: 'middle' },
    //全局col列占比(每列显示多少位)，和schemas中的colProps属性一致
    baseColProps: { span: 12 },
    //row行的样式
    baseRowStyle: { width: '100%' },
    //表单布局属性，支持（vertical,horizontal），默认为horizontal
    layout: 'horizontal',
  });
</script>

<style scoped>
  /** 时间和数字输入框样式 */
  :deep(.ant-input-number) {
    width: 100%;
  }

  :deep(.ant-picker) {
    width: 100%;
  }
</style>

4. 操作按钮

场景一：不需要按钮的时候，将按钮隐藏。
场景二：自定义操作按钮并处理自己的逻辑

页面效果
示例代码

不需要按钮的时候，将按钮隐藏。

查询按钮和重置按钮都存在

隐藏查询按钮

隐藏重置按钮

通过useForm hook里面的setProps可动态更改属性

自定义操作按钮并处理自己的逻辑

查询按钮、重置按钮自定义事件

通过submitFunc、resetFunc 来自定义操作按钮点击后的逻辑

<!-- 操作按钮 -->
<template>
  <div style="margin: 20px auto; text-align: center">
    <!-- 通过setProps 可以设置 userForm 中的属性 -->
    <!--  showActionButtonGroup 显示或者隐藏查询、重置按钮  -->
    <a-button @click="setProps({ showActionButtonGroup: false })" class="mr-2"> 隐藏操作按钮 </a-button>
    <a-button @click="setProps({ showActionButtonGroup: true })" class="mr-2"> 显示操作按钮 </a-button>
    <!--  showActionButtonGroup 显示或者隐藏重置按钮  -->
    <a-button @click="setProps({ showResetButton: false })" class="mr-2"> 隐藏重置按钮 </a-button>
    <a-button @click="setProps({ showResetButton: true })" class="mr-2"> 显示重置按钮 </a-button>
    <!--  showActionButtonGroup 显示或者隐藏查询按钮  -->
    <a-button @click="setProps({ showSubmitButton: false })" class="mr-2"> 隐藏查询按钮 </a-button>
    <a-button @click="setProps({ showSubmitButton: true })" class="mr-2"> 显示查询按钮 </a-button>
  </div>
  <!-- 自定义表单 -->
  <BasicForm @register="registerForm" @submit="handleSubmit" style="margin-top: 50px; margin-left: 50px" />
</template>

<script lang="ts" setup>
  //引入依赖
  import { useForm, BasicForm, FormSchema } from '/@/components/Form';
  import { CollapseContainer } from '/@/components/Container';

  /**
   * BasicForm绑定注册;
   * setProps方法可以动态设置useForm中的属性
   */
  const [registerForm, { setProps }] = useForm({
    //自定义查询按钮的文本和图标
    submitButtonOptions: { text: '查询', preIcon: '' },
    //自定义重置按钮的文本和图标
    resetButtonOptions: { text: '重置', preIcon: '' },
    //操作按钮的位置
    actionColOptions: { span: 17 },
    //提交按钮的自定义事件
    submitFunc: customSubmitFunc,
    //重置按钮的自定义时间
    resetFunc: customResetFunc,
    //显示操作按钮
    showActionButtonGroup: true,
  });

  /**
   * 重置按钮点击事件
   */
  async function customResetFunc() {
    console.log('重置按钮点击事件，此处处理重置按钮的逻辑');
  }

  /**
   * 查询按钮点击事件
   */
  async function customSubmitFunc() {
    console.log('查询按钮点击事件，此处处理查询按钮的逻辑');
  }

  /**
   * 点击提交按钮的value值
   * @param values
   */
  function handleSubmit(values: any) {
    console.log('提交按钮数据::::', values);
  }
</script>

<style scoped></style>

5. 表单大小、收缩、文本聚焦、禁用

页面效果
示例代码

默认聚焦“来访人员”，input框为蓝色

表单最大展示效果

表单禁用效果

表单紧凑展示效果

通过useForm hook里面的setProps可动态更改属性

<!-- 操作禁用表单 -->
<template>
  <div style="margin: 20px auto; text-align: center">
    <!-- 通过setProps 可以设置 userForm 中的属性 -->
    <!-- 表单大小，默认为 default   -->
    <a-button @click="setProps({ size: 'large' })" class="mr-2"> 更改大小为最大 </a-button>
    <a-button @click="setProps({ size: 'default' })" class="mr-2"> 还原大小 </a-button>
    <a-button @click="setProps({ size: 'small' })" class="mr-2"> 更改大小为最小 </a-button>
    <!--  disabled表单禁用  -->
    <a-button @click="setProps({ disabled: true })" class="mr-2"> 禁用表单 </a-button>
    <a-button @click="setProps({ disabled: false })" class="mr-2"> 解除禁用 </a-button>
    <!--  compact 是否为紧凑表单  -->
    <a-button @click="setProps({ compact: true })" class="mr-2"> 紧凑表单 </a-button>
    <a-button @click="setProps({ compact: false })" class="mr-2"> 还原正常间距 </a-button>
  </div>
  <!-- 自定义表单 -->
  <BasicForm @register="registerForm" @submit="handleSubmit" style="margin-top: 50px; margin-left: 50px" />
</template>

<script lang="ts" setup>
  //引入依赖
  import { useForm, BasicForm, FormSchema } from '/@/components/Form';
  import { CollapseContainer } from '/@/components/Container';

  //自定义表单字段
  const formSchemas: FormSchema[] = [
    {
      field: 'visitor',
      label: '来访人员',
      component: 'Input',
    },
    {
      field: 'accessed',
      label: '来访日期',
      component: 'DatePicker',
    },
    {
      field: 'phone',
      label: '来访人手机号',
      component: 'Input',
    },
  ];

  /**
   * BasicForm绑定注册;
   * setProps方法可以动态设置useForm中的属性
   */
  const [registerForm, { setProps }] = useForm({
    schemas: formSchemas,
    //隐藏操作按钮
    showActionButtonGroup: false,
    //默认聚焦第一个，只支持input
    autoFocusFirstItem: true,
  });
</script>

<style scoped></style>

6. 表单验证与清空验证

页面效果
示例代码

触发表单验证

清空表单验证

只验证来访人员

只清空来访人员验证

通过useForm hook里面的方法可以实现验证全部或者取消验证所有不满足的组件

<!-- 操作禁用表单 -->
<template>
  <div style="margin: 20px auto; text-align: center">
    <!-- all 触发或清空所有验证，visitor 只触发或者清空来访人员验证 -->
    <a-button @click="triggerFormRule('all')" class="mr-2"> 触发表单验证 </a-button>
    <a-button @click="cancelFormRule('all')" class="mr-2"> 清空表单验证 </a-button>
    <a-button @click="triggerFormRule('visitor')" class="mr-2"> 只验证来访人员 </a-button>
    <a-button @click="cancelFormRule('visitor')" class="mr-2"> 只清空来访人员验证 </a-button>
  </div>
  <!-- 自定义表单 -->
  <BasicForm @register="registerForm" @submit="handleSubmit" style="margin-top: 50px; margin-left: 50px" />
</template>

<script lang="ts" setup>
  //引入依赖
  import { useForm, BasicForm, FormSchema } from '/@/components/Form';

  //自定义表单字段
  const formSchemas: FormSchema[] = [
    {
      field: 'visitor',
      label: '来访人员',
      component: 'Input',
      required: true,
    },
    {
      field: 'accessed',
      label: '来访日期',
      component: 'DatePicker',
      required: true,
    },
    {
      field: 'phone',
      label: '来访人手机号',
      component: 'Input',
      required: true,
    },
  ];

  /**
   * BasicForm绑定注册;
   * setProps方法可以动态设置useForm中的属性
   * clearValidate 清除所有验证，支持取消验证其中几个字段 如 clearValidate(['visitor',...])
   * validate 验证所有
   * validateFields 验证其中几个字段，如validateFields(['visitor',...])
   */
  const [registerForm, { clearValidate, validateFields, validate }] = useForm({
    schemas: formSchemas,
    //隐藏操作按钮
    showActionButtonGroup: false,
    //默认聚焦第一个，只支持input
    autoFocusFirstItem: true,
  });

  /**
   * 触发表单验证
   * @param type all 所有验证 visitor 只验证来访人员
   */
  async function triggerFormRule(type) {
    if (type == 'all') {
      //触发所有验证
      await validate();
    } else {
      //触发来访人员验证
      //visitor 来访人员的对应formSchemas field字段
      await validateFields(['visitor']);
    }
  }

  /**
   * 触发表单验证
   * @param type all 所有验证 visitor 只验证来访人员
   */
  async function cancelFormRule(type) {
    if (type == 'all') {
      //取消全部验证
      await clearValidate();
    } else {
      //只取消来访人员的验证
      //visitor 来访人员的对应formSchemas field字段
      await clearValidate(['visitor']);
    }
  }
</script>

<style scoped>
  /** 时间和数字输入框样式 */
  :deep(.ant-input-number) {
    width: 100%;
  }

  :deep(.ant-picker) {
    width: 100%;
  }
</style>

7. 表单值操作

页面效果
示例代码

① 获取所有字段值
② 表单验证通过后获取所有字段值
③ 表单验visitor来访人员通过后获取的值

清空表单值

更新表单值

通过useForm hook里面的方法，可以获取、更新、清空值操作

<!-- 操作表单值 -->
<template>
  <div style="margin: 20px auto; text-align: center">
    <a-button @click="getFormValue" class="mr-2"> 获取表单值 </a-button>
    <a-button @click="clearFormValue" class="mr-2"> 清空表单值 </a-button>
    <a-button @click="updateFormValue" class="mr-2"> 更新表单值 </a-button>
  </div>
  <!-- 自定义表单 -->
  <BasicForm @register="registerForm" @submit="handleSubmit" style="margin-top: 50px; margin-left: 50px" />
</template>

<script lang="ts" setup>
  //引入依赖
  import { useForm, BasicForm, FormSchema } from '/@/components/Form';

  //自定义表单字段
  const formSchemas: FormSchema[] = [
    {
      field: 'visitor',
      label: '来访人员',
      component: 'Input',
      required: true,
    },
    {
      field: 'accessed',
      label: '来访日期',
      component: 'DatePicker',
      required: true,
    },
    {
      field: 'phone',
      label: '来访人手机号',
      component: 'Input',
      required: true,
    },
  ];

  /**
   * BasicForm绑定注册;
   * getFieldsValue 获取所有表单值
   * validate 验证通过之后的表单值,支持验证其中几个字段，validate(['visitor',...])
   * setFieldsValue 更新表单值，如 setFieldsValue({'visitor':'李四',...})
   * resetFields 清除所有表单值
   */
  const [registerForm, { getFieldsValue, setFieldsValue, resetFields, validate }] = useForm({
    schemas: formSchemas,
    //隐藏操作按钮
    showActionButtonGroup: false,
    //默认聚焦第一个，只支持input
    autoFocusFirstItem: true,
  });

  /**
   * 获取表单值
   */
  async function getFormValue() {
    //获取所有值
    let fieldsValue = await getFieldsValue();
    console.log('fieldsValue:::', fieldsValue);
    //表单验证通过后获取所有字段值
    fieldsValue = await validate();
    console.log('fieldsValue:::', fieldsValue);
    //表单验`visitor来访人员`通过后获取的值
    fieldsValue = await validate(['visitor']);
    console.log('fieldsValue:::', fieldsValue);
  }

  /**
   * 清空表单值
   */
  async function clearFormValue() {
    await resetFields();
  }

  /**
   * 更新表单值
   */
  async function updateFormValue() {
    await setFieldsValue({ visitor: '李四' });
  }
</script>

<style scoped>
  /** 时间和数字输入框样式 */
  :deep(.ant-input-number) {
    width: 100%;
  }

  :deep(.ant-picker) {
    width: 100%;
  }
</style>

8. 动态更新/重置字段属性

页面效果
示例代码

正常

触发更新字段属性

触发重置字段属性，注意重置字段属性会将schemas对应的字段全部删除，在添加您配置的字段属性

通过useForm hook里面的方法，可以动态更新、重置字段值

<!-- 操作表单schemas配置 -->
<template>
  <div style="margin: 20px auto; text-align: center">
    <a-button @click="updateFormSchemas" class="mr-2"> 更新字段属性 </a-button>
    <a-button @click="resetFormSchemas" class="mr-2"> 重置字段属性 </a-button>
  </div>
  <!-- 自定义表单 -->
  <BasicForm @register="registerForm" @submit="handleSubmit" style="margin-top: 50px; margin-left: 50px" />
</template>

<script lang="ts" setup>
  //引入依赖
  import { useForm, BasicForm, FormSchema } from '/@/components/Form';

  //自定义表单字段
  const formSchemas: FormSchema[] = [
    {
      field: 'visitor',
      label: '来访人员',
      component: 'Input',
      componentProps: {
        disabled: true,
      },
    },
    {
      field: 'accessed',
      label: '来访日期',
      component: 'DatePicker',
      ifShow: false,
    },
    {
      field: 'phone',
      label: '来访人手机号',
      component: 'Input',
      required: true,
    },
  ];

  /**
   * BasicForm绑定注册;
   * updateSchema 更新字段属性，支持schemas里面所有的配置
   * updateSchema([{ field: 'visitor', componentProps: { disabled: false },}, ... ]);
   * resetSchema 重置字段属性，支持schemas里面所有的配置
   * resetSchema([{  field: 'visitor',label: '来访人员',component: 'Input',},... ]);
   */
  const [registerForm, { updateSchema, resetSchema }] = useForm({
    schemas: formSchemas,
    //隐藏操作按钮
    showActionButtonGroup: false,
    //默认聚焦第一个，只支持input
    autoFocusFirstItem: true,
  });

  /**
   * 清除表单配置
   */
  async function resetFormSchemas() {
    await resetSchema([
      {
        //字段必填
        field: 'visitor',
        label: '来访人员',
        component: 'Input',
      },
    ]);
  }

  /**
   * 更新表单配置
   */
  async function updateFormSchemas() {
    //支持更新schemas里面所有的配置
    await updateSchema([
      {
        //字段必填
        field: 'visitor',
        componentProps: {
          disabled: false,
        },
      },
      {
        field: 'accessed',
        ifShow: true,
      },
    ]);
  }
</script>

<style scoped>
  /** 时间和数字输入框样式 */
  :deep(.ant-input-number) {
    width: 100%;
  }

  :deep(.ant-picker) {
    width: 100%;
  }
</style>

9. 动态增减表单项

动态增加、减少表单项。

页面效果
示例代码

效果1

效果2

通过useForm hook里面的方法，可以动态增加、减少表单项

<!-- 动态增减表单 -->
<template>
  <!-- 自定义表单 -->
  <BasicForm @register="registerForm" style="margin-top: 50px; margin-left: 50px" @submit="handleSubmit">
    <!--  添加input的插槽  -->
    <template #addForm="{ field }">
      <a-button v-if="Number(field) === 0" @click="addField" style="width: 50px">+</a-button>
      <a-button v-if="Number(field) > 0" @click="delField(field)" style="width: 50px">-</a-button>
    </template>
  </BasicForm>
  <!--  <div style="margin: 20px auto; text-align: center">
    <a-button @click="addField">添加表单项</a-button>
  </div>-->
</template>

<script lang="ts" setup>
  //引入依赖
  import { useForm, BasicForm, FormSchema } from '/@/components/Form';
  import { CollapseContainer } from '/@/components/Container';
  import { ref } from '@vue/runtime-core';

  //自定义表单字段
  const formSchemas: FormSchema[] = [
    {
      field: 'name1',
      label: '姓名1',
      component: 'Input',
      // ifShow:false,
      colProps: {
        span: 8,
      },
    },
    {
      field: 'age1',
      label: '年龄1',
      component: 'InputNumber',
      // ifShow:false,
      colProps: {
        span: 8,
      },
    },
    {
      field: '0',
      component: 'Input',
      // ifShow:false,
      label: ' ',
      colProps: {
        span: 8,
      },
      slot: 'addForm',
    },
  ];

  /**
   * BasicForm绑定注册;
   * appendSchemaByField:增加表单项（字段）
   *
   * removeSchemaByFiled:减少表单项（字段）
   */
  const [registerForm, { appendSchemaByField, removeSchemaByFiled }] = useForm({
    schemas: formSchemas,
    showResetButton: false,
    // showSubmitButton:false
    submitButtonOptions: { text: '提交', preIcon: '' },
    actionColOptions: { span: 17 },
  });

  //组件个数
  let n = ref<number>(2);

  /**
   * 添加字段
   * appendSchemaByField类型: ( schema: FormSchema, prefixField: string | undefined, first?: boolean | undefined ) => Promise<void>
   * 说明: 插入到指定 filed 后面，如果没传指定 field，则插入到最后,当 first = true 时插入到第一个位置
   */
  async function addField() {
    //添加表单字段，里面为schemas对应的属性，可自行配置
    await appendSchemaByField(
      {
        field: `name${n.value}`,
        component: 'Input',
        label: '字段' + n.value,
        colProps: {
          span: 8,
        },
      },
      ''
    );
    await appendSchemaByField(
      {
        field: `sex${n.value}`,
        component: 'InputNumber',
        label: '字段' + n.value,
        colProps: {
          span: 8,
        },
      },
      ''
    );

    await appendSchemaByField(
      {
        field: `${n.value}`,
        component: 'Input',
        label: ' ',
        colProps: {
          span: 8,
        },
        slot: 'addForm',
      },
      ''
    );
    n.value++;
  }

  /**
   * 删除字段
   * 类型: (field: string | string[]) => Promise<void>
   * 说明: 根据 field 删除 Schema
   * @param field 当前字段名称
   */
  function delField(field) {
    //移除指定字段
    removeSchemaByFiled([`name${field}`, `sex${field}`, `${field}`]);
    n.value--;
  }

  /**
   * 点击提交按钮的value值
   * @param values
   */
  function handleSubmit(values: any) {
    console.log('提交按钮数据::::', values);
  }
</script>

<style scoped>
  /** 数字输入框样式 */
  :deep(.ant-input-number) {
    width: 100%;
  }
</style>

10. 自定义表单顶部区域和底部区域

当底部按钮不满足需求时，可以自定义底部区域。
例：在员工档案中，我们存在保存、保存草稿、重置

页面效果
示例代码

使用插槽formHeader（自定义表单头部区域）、formFooter（自定义表单底部区域）

<!-- 自定义页脚 -->
<template>
  <!-- 自定义表单 -->
  <BasicForm @register="registerForm" @submit="handleSubmit" style="margin-top: 50px; margin-left: 50px">
    <template #formHeader>
      <div style="margin: 0 auto 20px">
        <span>我是自定义按钮</span>
      </div>
    </template>
    <template #formFooter>
      <div style="margin: 0 auto">
        <a-button type="primary" @click="save" class="mr-2"> 保存 </a-button>
        <a-button type="primary" @click="saveDraft" class="mr-2"> 保存草稿 </a-button>
        <a-button type="error" @click="reset" class="mr-2"> 重置 </a-button>
      </div>
    </template>
  </BasicForm>
</template>

<script lang="ts" setup>
  //引入依赖
  import { useForm, BasicForm, FormSchema } from '/@/components/Form';

  //自定义表单字段
  const formSchemas: FormSchema[] = [
    {
      label: '员工姓名',
      field: 'name',
      component: 'Input',
    },
    {
      label: '性别',
      field: 'sex',
      component: 'Select',
      //填写组件的属性
      componentProps: {
        options: [
          { label: '男', value: 1 },
          { label: '女', value: 2 },
          { label: '未知', value: 3 },
        ],
      },
      //默认值
      defaultValue: 3,
    },
    {
      label: '年龄',
      field: 'age',
      component: 'Input',
    },
    {
      label: '入职时间',
      subLabel: '( 选填 )',
      field: 'entryTime',
      component: 'TimePicker',
    },
  ];

  /**
   * BasicForm绑定注册;
   */
  const [registerForm, { validate, resetFields }] = useForm({
    schemas: formSchemas,
    //隐藏操作按钮
    showActionButtonGroup: false,
  });

  /**
   * 保存
   */
  async function save() {
    //使用useForm方法获取表单值
    let values = await validate();
    console.log(values);
  }

  /**
   * 保存草稿
   */
  async function saveDraft() {
    //使用useForm方法validate获取表单值
    let values = await validate();
    console.log(values);
  }

  /**
   * 重置
   */
  async function reset() {
    //使用useForm方法resetFields清空值
    await resetFields();
  }
</script>

<style scoped>
  /** 时间和数字输入框样式 */
  :deep(.ant-input-number) {
    width: 100%;
  }

  :deep(.ant-picker) {
    width: 100%;
  }
</style>

11. 弹出层中的表单

页面效果
示例代码

组件中用到了BasicModal

BasicModal弹窗

<!-- 弹出层表单 -->
<template>
  <div style="margin: 20px auto">
    <a-button type="primary" @click="openPopup" class="mr-2"> 打开弹窗 </a-button>
  </div>
  <!-- 自定义弹窗组件 -->
  <BasicModal @register="registerModal" title="弹出层表单">
    <!-- 自定义表单 -->
    <BasicForm @register="registerForm" />
  </BasicModal>
</template>

<script lang="ts" setup>
  //引入依赖
  import { useForm, BasicForm, FormSchema } from '/@/components/Form';
  import { BasicModal } from '/@/components/Modal';
  import { useModal } from '/@/components/Modal';

  //自定义表单字段
  const formSchemas: FormSchema[] = [
    {
      label: '员工姓名',
      field: 'name',
      component: 'Input',
    },
    {
      label: '性别',
      field: 'sex',
      component: 'Select',
      //填写组件的属性
      componentProps: {
        options: [
          { label: '男', value: 1 },
          { label: '女', value: 2 },
          { label: '未知', value: 3 },
        ],
      },
      //默认值
      defaultValue: 3,
    },
    {
      label: '年龄',
      field: 'age',
      component: 'Input',
    },
    {
      label: '入职时间',
      subLabel: '( 选填 )',
      field: 'entryTime',
      component: 'TimePicker',
    },
  ];

  //BasicModal绑定注册;
  const [registerModal, { openModal }] = useModal();

  /**
   * BasicForm绑定注册;
   */
  const [registerForm, { validate, resetFields }] = useForm({
    schemas: formSchemas,
    //隐藏操作按钮
    showActionButtonGroup: false,
  });

  /**
   * 打开弹窗
   */
  async function openPopup() {
    //详见 BasicModal模块
    openModal(true, {});
  }
</script>

<style scoped>
  /** 时间和数字输入框样式 */
  :deep(.ant-input-number) {
    width: 100%;
  }

  :deep(.ant-picker) {
    width: 100%;
  }
</style>

12. 查询区域

页面效果
示例代码

默认显示两行，超过两行折叠，并且显示展开收起按钮

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

fieldMapToNumber与fieldMapToTime用法一致，将表单内数值类型区域的值映射成2个字段

<!-- 查询区域 -->
<template>
  <!-- 自定义表单 -->
  <BasicForm @register="registerForm" @submit="handleSubmit" style="margin-top: 50px" />
</template>

<script lang="ts" setup>
  //引入依赖
  import { useForm, BasicForm, FormSchema } from '/@/components/Form';

  //自定义表单字段
  const formSchemas: FormSchema[] = [
    {
      field: 'name',
      label: '姓名',
      component: 'Input',
    },
    {
      field: 'hobby',
      label: '爱好',
      component: 'Input',
    },
    {
      field: 'birthday',
      label: '生日',
      component: 'DatePicker',
    },
    {
      field: 'joinTime',
      label: '入职时间',
      component: 'RangePicker',
      componentProps: {
        valueType: 'Date',
      },
    },
    {
      field: 'workYears',
      label: '工作年份',
      component: 'JRangeNumber',
    },
    {
      field: 'sex',
      label: '性别',
      component: 'Select',
      componentProps: {
        options: [
          {
            label: '男',
            value: '1',
          },
          {
            label: '女',
            value: '2',
          },
        ],
      },
    },
    {
      field: 'marital',
      label: '婚姻状况',
      component: 'RadioGroup',
      componentProps: {
        options: [
          {
            label: '未婚',
            value: '1',
          },
          {
            label: '已婚',
            value: '2',
          },
        ],
      },
    },
  ];

  /**
   * BasicForm绑定注册;
   */
  const [registerForm] = useForm({
    //注册表单列
    schemas: formSchemas,
    //是否显示展开收起按钮，默认false
    showAdvancedButton: true,
    //超过指定行数折叠，默认3行
    autoAdvancedCol: 3,
    //折叠时默认显示行数，默认1行
    alwaysShowLines: 2,
    //将表单内时间区域的值映射成 2个字段, 'YYYY-MM-DD'日期格式化
    fieldMapToTime: [['joinTime', ['joinTime_begin', 'joinTime_end'], 'YYYY-MM-DD']],
    //将表单内数值类型区域的值映射成 2个字段
    fieldMapToNumber: [['workYears', ['workYears_begin', 'workYears_end']]],
    //每列占比，默认一行为24
    baseColProps: { span: 12 },
  });

  /**
   * 点击提交按钮的value值
   * @param values
   */
  function handleSubmit(values: any) {
    console.log('提交按钮数据::::', values);
  }
</script>

<style scoped>
  /** 时间和数字输入框样式 */
  :deep(.ant-input-number) {
    width: 100%;
  }

  :deep(.ant-picker) {
    width: 100%;
  }
</style>

`useForm` api属性

属性	类型	默认值	可选值	说明
schemas	`Schema[]`	-	-	表单配置，见`BasicForm` 中的`schemas` 介绍
submitOnReset	`boolean`	`false`	-	重置时是否提交表单
labelCol	Partial`<ColEx>`	-	-	整个表单通用 LabelCol 配置
wrapperCol	Partial `<ColEx>`	-	-	整个表单通用 wrapperCol 配置
baseColProps	Partial `<ColEx>`	-	-	配置所有选子项的 ColProps，不需要逐个配置，子项也可单独配置优先与全局
labelWidth	`number` , `string`	-	-	扩展 form 组件，增加 label 宽度，表单内所有组件适用，可以单独在某个项覆盖或者禁用
labelAlign	`string`	-	`left`,`right`	label 布局
mergeDynamicData	`object`	-	-	额外传递到子组件的参数 values
autoFocusFirstItem	`boolean`	`false`	-	是否聚焦第一个输入框，只在第一个表单项为 input 的时候作用
compact	`boolean`	`false`	`true/false`	紧凑类型表单，减少 margin-bottom
size	`string`	`default`	`'default'` , `'small'` , `'large'`	向表单内所有组件传递 size 参数,自定义组件需自行实现 size 接收
disabled	`boolean`	`false`	`true/false`	向表单内所有组件传递 disabled 属性，自定义组件需自行实现 disabled 接收
autoSetPlaceHolder	`boolean`	`true`	`true/false`	自动设置表单内组件的 placeholder，自定义组件需自行实现
autoSubmitOnEnter	`boolean`	`false`	`true/false`	在input中输入时按回车自动提交
rulesMessageJoinLabel	`boolean`	`false`	`true/false`	如果表单项有校验，会自动生成校验信息，该参数控制是否将字段中文名字拼接到自动生成的信息后方
showAdvancedButton	`boolean`	`false`	`true/false`	是否显示收起展开按钮
emptySpan	`number` , Partial`<ColEx>`	0	-	空白行格,可以是数值或者 col 对象数
autoAdvancedCol	`number`	3	-	如果 showAdvancedButton 为 true，超过指定列数行默认折叠
alwaysShowLines	`number`	1	-	折叠时始终保持显示的行数
showActionButtonGroup	`boolean`	`true`	`true/false`	是否显示操作按钮组(查询/重置/展开/关闭)
actionColOptions	Partial`<ColEx>`	-	-	操作按钮外层 Col 组件配置，如果开启 showAdvancedButton，则不用设置，具体见下方 actionColOptions
showResetButton	`boolean`	`true`	-	是否显示重置按钮
resetButtonOptions	`object`		-	重置按钮配置ActionButtonOption
showSubmitButton	`boolean`	`true`	-	是否显示提交按钮
submitButtonOptions	`object`		-	确认按钮配置ActionButtonOption
resetFunc	() => Promise`<void>`		-	自定义重置按钮逻辑() => Promise`<void>;`
submitFunc	() => Promise`<void>`		-	自定义提交按钮逻辑() => Promise`<void>;`
fieldMapToTime	[string, [string, string], string?][]		-	用于将表单内时间区域的应设成 2 个字段,见下方说明

userForm 其它属性介绍​

1. 固定label标题的宽度​

2. 标题与字段布局​

2.1 效果及代码展示​

2.2 labelCol和wrapperCol 属性​

3. 表单布局​

4. 操作按钮​

5. 表单大小、收缩、文本聚焦、禁用​

6. 表单验证与清空验证​

7. 表单值操作​

8. 动态更新/重置字段属性​

9. 动态增减表单项​

10. 自定义表单顶部区域和底部区域​

11. 弹出层中的表单​

12. 查询区域​

useForm api属性​

`userForm` 其它属性介绍

1. 固定label标题的宽度

2. 标题与字段布局

2.1 效果及代码展示

2.2 `labelCol`和`wrapperCol` 属性

3. 表单布局

4. 操作按钮

5. 表单大小、收缩、文本聚焦、禁用

6. 表单验证与清空验证

7. 表单值操作

8. 动态更新/重置字段属性

9. 动态增减表单项

10. 自定义表单顶部区域和底部区域

11. 弹出层中的表单

12. 查询区域

`useForm` api属性