📦 安装

$ npm install @element-plus-ui/pro-form

$ yarn add @element-plus-ui/pro-form

$ pnpm add @element-plus-ui/pro-form

✨ 布局组件

• ProForm 通用型表单组件，自身挂载了表单项组件及以下布局组件
• ProSearchBar 搜索栏表单组件，配合其它组件单独使用，如：table
• ProStepsForm 分布式表单组件，一般在数据量比较多的情况下使用
• ProDialogForm 组合了 ElDialog 和 ProForm 组件，可通过 trigger 来控制显隐, 减少繁琐的状态管理
• ProDrawerForm 组合了 ElDrawer 和 ProForm 组件，可通过 trigger 来控制显隐, 减少繁琐的状态管理

✨ 表单项组件(一般配合布局组件一起使用)

这些组件本质上是 ElFormItem 和 组件 的结合，我们可以把他们当成一个 ElFormItem 来使用，并且支持各种 props

每个表单项都支持 fieldProps 属性来支持设置输入组件的 props。 我们支持了 placeholder 的透传，你可以直接在组件上设置 placeholder

对于表单项的生成，除了使用以下组件外，还支持通过 columns 属性进行配置，如果你想要自定义表单元素，你仍然可以用 ElForm 原有（ElFormItem + 自定义组件）的方式来自定义，三者可以混合使用

• ProFormText 用于输入各类文本
• ProFormTextarea 用于输入多行文本
• ProFormNumber 用于输入数子
• ProFormPassword 用于输入密码
• ProFormDate 日期选择器用于输入日期
• ProFormDateMonth 日期 + 月选择器，用于输入日期和月
• ProFormDateMonths 日期 + 月选择器，用于输入多个日期和月
• ProFormDateMonthRange 日期 + 月区间选择器，用于输入一个日期 + 月的区间
• ProFormDateRange 日期区间选择器用于输入一个日期区间
• ProFormDates 用于选择多个日期
• ProFormDateTime 日期 + 时间选择器，用于输入日期和时间
• ProFormDateTimeRange 日期 + 时间区间选择器，用于输入一个日期 + 时间的区间
• ProFormDateWeek 日期 + 周选择器，用于输入日期和周
• ProFormDateYear 日期 + 年选择器，用于输入日期和年
• ProFormDateYears 日期 + 年选择器，用于输入多个日期和年
• ProFormTime 时间选择器用于输入时间
• ProFormTimeRange 时间区间选择器用于输入一个时间区间
• ProFormRadio 支持 request 和 valueEnum 两种方式来生成子项
• ProFormRadioButton 支持 request 和 valueEnum 两种方式来生成子项
• ProFormCheckbox 支持 request 和 valueEnum 两种方式来生成子项
• ProFormCheckboxButton 支持 request 和 valueEnum 两种方式来生成子项
• ProFormRate 用于评分
• ProFormSelect 支持 request 和 valueEnum 两种方式来生成子项
• ProFormSlider 当用户需要在数值区间 / 自定义区间内进行选择时，可为连续或离散值
• ProFormSwitch 用于输入互斥的两个选项，一般是 true 和 false
• ProFormColor 用于颜色选择
• ProFormCascader 级联选择器逐级查看并选择，支持 request 和 valueEnum 两种方式来生成子项
• ProFormTimeSelect 用于选择或输入日期
• ProFormTreeSelect 支持 request 和 valueEnum 两种方式来生成子项
• ProFormUploadImage 用于图片上传和展示
• ProFormUploadAvatar 用于头像上传和展示
• ProFormVirtualizedSelect 虚拟化选择器，支持 request 和 valueEnum 两种方式来生成子项

ProForm

在 ElForm 的基础上，新增了以下属性和事件

| 属性 | 描述 | 类型 | 默认值 | | ---- | ------------- | ------------------------------------ | ------ | | v-model | 绑定的数据实体. | Record<string, any> | - | | title | 标题. | string | - | | grid | 开启栅格化模式. | boolean | false | | variant | 表单变体. | Form / SearchBar/ StepsForm/ DialogForm / DrawerForm | Form | | colProps | 开启 grid 模式时，需配置的布局参数. | ColProps | {} | | rowProps | 开启 grid 模式时，需配置的布局参数. | RowProps | {} | | columns | 以配置的方式生成表单项. | Array<ColumnConfig> | [] | | params | 请求参数. | Record<string, any> | {} | | request | 发起网络请求，返回值会覆盖给 v-model. | (params) => Promise<data> | - | | readonly | 是否只读. | boolean | false | | emptyText | readonly=true 并且值为空时，需要显示的占位文本. | string | - | | labelStyle | 表单项标签样式. | CSSProperties | {} | | submitter | 提交器，用于配置相关按钮. | SubmitterConfig | - | | @reset | 监听重置事件. | (entity) => void | - | | @submit | 监听提交事件，若返回值为 true 则继续执行后续验证事件. | (entity) => void \| boolean | - | | @finish | 监听表单验证成功，在 submit 事件之后执行. | (entity) => void \| boolean \| Promise<boolean> | - | | @failed | 监听表单验证失败，在 submit 事件之后执行. | (entity) => void | - | | @values-change | 监听表单绑定的数据发生变化. | (entity, key) => void | - |

重置和提交按钮事件权重规则：

• submitter.submitButtonProps.onClick > submitter.onSubmit > @submit

• submitter.submitButtonProps.onClick > submitter.onReset > @reset

案例：

<template>
  <pro-form
    ref="formRef"
    :label-style="{ fontWeight: 600 }"
    :readonly="false"
    :required="false"
    :columns="formItems"
    :request="getFormData"
    :grid="true"
    :col-props="{ span: 24 }"
    :submitter="{
      hideResetButton: false,
      fillMode: 'full',
      submitButtonProps: {
        onClick: () => console.log('自定义提交事件')
      },
      onSubmit: entity => {
        console.log('局部绑定的提交事件，通过返回值控制是否继续', entity);
        return true;
      }
    }"
    @reset="entity => console.log('全局绑定的重置事件', entity)"
    @submit="
      entity => {
        console.log('全局绑定的提交事件，返回值为 false 关闭内部验证功能', entity);
        return false;
      }
    "
    @finish="entity => console.log('表单验证成功', entity)"
    @failed="entity => console.log('表单验证失败', entity)"
    @values-change="(entity, key) => console.log('监听绑定的值发生变化', entity, key)"
  >
  </pro-form>
</template>

<script setup lang="ts">
  import { ProForm, ProFormColumn } from "@element-plus-ui/pro-form";
  import { ref, watch } from "vue";

  const formRef = ref();
  const formItems = ref<ProFormColumn[]>([
    {
      label: "姓名:",
      prop: "user.name",
      required: true,
      order: 0,
      valueType: "text",
      hidden: (data: any) => {
        return data.switch === true;
      }
    },{
      label: "年龄:",
      prop: "age",
      valueType: "number",
      tooltip: "测试",
      rules: [{ type: "number", trigger: "change" }]
    },{
      label: "星级:",
      valueType: "rate",
      prop: "rate",
      fieldProps: {
        scoreTemplate: "{value} 级"
      }
    },{
      label: "开关:",
      prop: "switch",
      valueType: "switch",
      fieldProps: {}
    }
  ]);

  const form = ref({
    id: "1001",
    switch: false,
    rate: 3,
    age: 9
  });

  const getFormData = async (params: Record<string, any>) => {
    return {
      user: {
        name: "拔都"
      },
      age: 50
    };
  };
</script>

ProSearchBar

事件绑定及权重与 ProForm 组件相同

| 属性 | 描述 | 类型 | 默认值 | | ---- | ------------- | ------------------------------------ | ------ | | v-model | 绑定的数据实体. | Record<string, string \| number \| boolean \| any[]> | - | | layout | 布局方式. | horizontal / vertical / inline | horizontal | | columns | 以配置的方式生成表单项. | Array<ColumnConfig> | [] | | colSpan | 栅格占据的列数. | number | 3 | | preserve | 是否能够查询收起的数据，如果设置为 false，收起后的表单数据将会丢失. | boolean | true | | labelStyle | 表单项标签样式. | CSSProperties | {} | | collapsed | 是否展开. | boolean | false | | extraTools | 额外的工具集配置，权限低于插槽. | Array<ButtonConfig> / () => VNode | [] | | searchBefore | 触发搜索的前置行为. | (data) => boolean | - | | submitter | 提交器，用于配置相关按钮. | SubmitterConfig | - | | defaultCollapsed | 默认是否展开. | boolean | false | | defaultColsNumber | 默认显示列数. | number | 3 |

案例：

<template>
  <pro-search-bar
    v-model="formData"
    :columns="columns"
    :collapse="collapse"
    :submitter="[
      {
        title: '查找',
        type: 'primary',
        onClick: data => {
          console.log('自定义配置提交器搜索按钮', data);
        }
      }
    ]"
    :extra-tools="[
      {
        title: '批量导入',
        onClick: data => console.log('批量导入', data)
      },{
        title: '批量导出',
        onClick: data => console.log('批量导出', data)
      }
    ]"
    @collapse="onCollapse"
    @search="onSearch"
  >
    <!-- 自定义额外工具触发器，只有在 extra-tools 配置为多项时，才会生效 -->
    <template #extra-tools-trigger>
      <pro-icon name="More" />
    </template>
    <!-- 自定义表单项 -->
    <el-form-item label="姓名:">
      <el-input v-model="formData.name" />
    </el-form-item>
  </pro-search-bar>
</template>

<script setup lang="ts">
  import { ProSearchBar, ProFormColumn } from "@element-plus-ui/pro-form";
  import { ProIcon } from "@element-plus-ui/pro-icon";
  import { ref } from "vue";

  const formData = ref({
    name: ""
  });

  const collapse = ref(false);

  /**
   * 定义表单项
   */
  const columns = ref<ProFormColumn[]>([
    {
      label: "手机号:",
      prop: "phone",
      valueType: "text"
    },{
      label: "出生日期:",
      prop: "date",
      valueType: "date"
    }
  ]);

  /**
   * 监听展开收起变化
   */
  const onCollapse = (v: boolean) => {
    console.log("是否展开：", v);
  };

  /**
   * 默认全局搜索事件，权重低于局部配置的事件
   * @param entity
   */
  const onSearch = (entity: Record<string, any>) => {
    console.log("数据：", entity);
  };
</script>

ProStepsForm

我们提供了三种方式来生成表单，首先是通过 ProStepForm 组件以插槽的形式生成，这种方式权限也是最高的，其次是通过 steps 属性进行配置，如果在steps 配置中，未定义 columns，那么会使用全局 columns。

| 属性 | 描述 | 类型 | 默认值 | | ---- | ------------- | ------------------------------------ | ------ | | active | 当前激活的步骤，透传到 stepsProps 中. | number | 0 | | steps | 步骤配置和表单定义. | string[] / StepConfig[] | - | | columns | 表单定义，需要使用二维数组来生成多个表单，否则会生成一个普通表单. | Array<ColumnConfig[] | ColumnConfig> | - | | hideStepsBar | 是否隐藏步骤栏. | boolean | false | | stepsProps | ElSteps 组件 Props 配置. | StepsProps | - |

案例：

<template>
  <ProStepsForm
    :submitter="{
      fillMode: 'aequilate'
    }"
    :steps="[
      {
        title: '基础信息',
        columns: [
          {
            label: '姓名:',
            prop: 'name',
            required: true,
            valueType: 'text'
          },{
            label: '年龄:',
            prop: 'age',
            valueType: 'number',
            tooltip: '测试'
          },{
            label: '出生日期:',
            valueType: 'date'
          }
        ]
      },
      {
        title: '状态管理',
        columns: [
          {
            label: '是否通过',
            valueType: 'switch'
          },{
            label: '爱好:',
            prop: 'test',
            valueType: 'radio',
            valueEnum: {
              1: '钓鱼',
              2: '王者',
              3: '台球',
              4: '阅读'
            }
          }
        ]
      }
    ]"
    @finish="async v => {
      console.log(v, '全局触发第二步成功');
      return true;
    }"
    @failed="v => console.log(v, '全局触发第二步失败')"
  >
    <ProStepsForm.StepForm
      title="基础信息"
      :columns="[
        {
          label: '姓名:',
          prop: 'name',
          required: true,
          order: 0,
          valueType: 'text'
        },{
          label: '年龄:',
          prop: 'age',
          valueType: 'number',
          tooltip: '测试'
        },{
          label: '出生日期:',
          valueType: 'date'
        }
      ]"
      @finish="async v => {
        console.log(v, '第一步成功');
        return true;
      }"
      @failed="v => console.log(v, '第一步失败')"
    >
      <!-- 通过插槽的方式定义的表单项，权重大于 columns，所以在第一项显示 -->
      <ProForm.Cascader label="选择器" :order="0" />
    </ProStepsForm.StepForm>
    <ProStepsForm.StepForm title="项目信息">
      <ProForm.Text label="项目名称:" />
      <ProForm.Date label="启动日期:" />
    </ProStepsForm.StepForm>
  </ProStepsForm>
</template>

<script setup lang="ts">
  import { ProForm, ProStepsForm } from "@element-plus-ui/pro-form";
</script>

ProDialogForm

是 ElDiaLog 和 ProForm 组件的组合，除了以下属性外，还继承了 ProForm 的 Props，以下不再过多列举，如有需要，可查阅 ProFormAPI

| 属性 | 描述 | 类型 | 默认值 | | ---- | ------------- | ------------------------------------ | ------ | | v-model:open | 是否打开. | boolean | false | | width | 宽度，透传到 dialogProps 中. | number / string | 50% | | trigger | 用于触发 Dialog 打开，一般是 button，减少 open 的使用. | ButtonConfig / () => VNode | - | | titleSize | 标题大小. | number | 16 | | titleColor | 标题颜色. | string | #303133 | | titleWeight | 标题粗细. | number / string | 600 | | dialogProps | ElDialog 组件 Props 配置。注意：不支持 modelValue，请使用全局的 open. | DialogProps | {} |

案例：

<template>
  <el-button @click="open = true">创建用户</el-button>
  <pro-dialog-form
    v-model:open="open"
    title="创建用户"
    :grid="true"
    :col-props="{ span: 24 }"
    :trigger="{ title: '以 trigger 方式控制显隐', type: 'primary' }"
    :columns="[
      {
        label: '年龄',
        order: 1,
        valueType: 'number'
      }
    ]"
  >
    <!-- 自定义 -->
    <el-form-item label="姓名">
      <el-input />
    </el-form-item>
    <!-- 使用表单日期字段组件 -->
    <pro-form-date label="出生日期" :order="3" />
  </pro-dialog-form>
</template>

<script setup lang="ts">
  import { ProDialogForm, ProFormDate } from "@element-plus-ui/pro-form";
  import { ref } from "vue";
  const open = ref(false);
</script>

ProDrawerForm

是 ElDrawer 和 ProForm 组件的组合，除了以下属性外，还继承了 ProForm 的 Props，以下不再一一列举，如有需要，可查阅 ProFormAPI

| 属性 | 描述 | 类型 | 默认值 | | ---- | ------------- | ------------------------------------ | ------ | | v-model:open | 是否打开. | boolean | false | | width | 宽度，透传到 drawerProps 中.. | number / string | 50% | | trigger | 用于触发 Drawer 打开，一般是 button，减少 open 的使用. | ButtonConfig / () => VNode | - | | titleSize | 标题大小. | number | 16 | | titleColor | 标题颜色. | string | #303133 | | titleWeight | 标题粗细. | number / string | 600 | | drawerProps | ElDrawer 组件 Props 配置。注意：不支持 modelValue，请使用全局的 open. | DrawerProps | {} |

案例：

<template>
  <el-button @click="open = true">创建用户</el-button>
  <pro-drawer-form
    v-model:open="open"
    title="创建用户"
    :grid="true"
    :col-props="{ span: 24 }"
    :trigger="{ title: '以 trigger 方式控制显隐', type: 'primary' }"
    :columns="[
      {
        label: '年龄',
        order: 1,
        valueType: 'number'
      }
    ]"
  >
    <!-- 自定义 -->
    <el-form-item label="姓名">
      <el-input />
    </el-form-item>
    <!-- 使用表单日期字段组件 -->
    <pro-form-date label="出生日期" :order="3" />
  </pro-drawer-form>
</template>

<script setup lang="ts">
  import { ProDrawerForm, ProFormDate } from "@element-plus-ui/pro-form";
  import { ref } from "vue";
  const open = ref(false);
</script>

ProFormFields

ProForm 自带的 Filed, 与 ProField 组件的 type 一一对应, 除了以下新增的属性之外, 同时也继承了 ElFormItem 和 ProField 对应的组件 Props.

可以这样理解，ProFormText 是 ElFormItem + ElInput 的产物，所以我们给 ProFormText 设置的 props 其实是 ElFormItem 的，fieldProps 才是包含的组件的，要切记.

对于一些继承的属性，以下不再过多列举，如有需要, 可前往 ElFormItem 和 ProField 组件文档处进行查阅

| 属性 | 描述 | 类型 | 默认值 | | ---- | ------------- | ------------------------------------ | ------ | | order | 表单项排序，数值越大越靠后. | number | - |

案例：

<template>
  <pro-form :model="entity" :grid="true" :col-props="{ span: 24 }">
    <!-- 使用对应的字段组件生成表单项 -->
    <pro-form-text label="姓名：" v-model="entity.name" />
    <pro-form-number label="年龄：" v-model="entity.age" :field-props="{max: 100}"/>
    <!-- 以对象取值的方式指定渲染的表单项字段 -->
    <ProForm.Date label="出生日期：" v-model="entity.date" />
    <ProForm.Textarea label="介绍：" v-model="entity.desc" />
    <!-- 使用原有的方式自定义 -->
    <el-form-item label="自定义：">
      <el-input v-model="entity.name" />
    </el-form-item>
  </pro-form>
</template>

<script setup lang="ts">
  import { ProForm, ProFormText, ProFormNumber } from "@element-plus-ui/pro-form";
  import { ref } from "vue";

  const entity = ref({
    name: "",
    age: 10,
    date: "",
    desc: ""
  });
</script>

StepConfig

除了以下属性，同时还继承了 ElStepProps 和 ProFormProps

| 属性 | 描述 | 类型 | 默认值 | | ---- | ------------- | ------------------------------------ | ------ | | columns | 表单项定义. | ColumnConfig | [] |

ColumnConfig

除了以下属性外，还继承了 ElFormItemProps，以下不再过多列举

| 属性 | 描述 | 类型 | 默认值 | | ---- | ------------- | ------------------------------------ | ------ | | key | 唯一标识. | string / number | - | | order | 对表单项进行排序，数值越大越靠后. | number | - | | labelStyle | label 样式设置. | CSSProperties | | tooltip | label 提示语. | string | - | | valueType | 值类型，同 ProField 组件的 type 属性值相同 | ProFieldType | text | | valueEnum | 要生成的选项集数据，支持多种数据结构，优先级低于 request. | ProFieldValueEnum | - | | separator | 多值之间的分隔符，如日期区间、多选项. | string | - | | emptyText | readonly=true 时，并且值为空，提供的占位文本. | string | - | | marker | 需要显示的标记. | ProFieldMarker | none | | request | 从服务器获取数据. | () => Promise<ValueEnum> | - | | placeholder | 输入框占位文本，透传到 fieldProps 中. | string / [string] / [string, string] | - | | mappingEnumValue | 当 valueEnum 数据中，未明确指定 value 时，需要映射的目标对象. | lable / index | lable | | fieldProps | 当前 valueType 渲染的组件 Props 配置. | FieldProps | {} | | hidden | 是否隐藏当前表单项. | boolean / (entity) => boolean | false | | readonly | 是否只读. | boolean | false |

属性 valueType、valueEnum、request、marker、mappingEnumValue、fieldProps 使用方式与 ProField 组件完全相同，在这不再过多描述，如有需要可前往 ProField 文档处进行查阅

ButtonConfig

在 ElButtonProps 的基础上新增了以下属性

| 属性 | 描述 | 类型 | 默认值 | | ---- | ------------- | ------------------------------------ | ------ | | title | 按钮标题文本. | string | - |

SubmitterConfig

除了支持 boolean、ButtonConfig[]、(props, doms: VNode[]) => VNode | Array<VNode> 类型外，还支持以下对象类型配置

| 属性 | 描述 | 类型 | 默认值 | | ---- | ------------- | ------------------------------------ | ------ | | align | 水平排列位置. | left / right / center | right | | reverse | 是否反转按钮前后顺序. | boolean | false | | fillMode | 提交器按钮填充模式. | auto / full / aequilate | auto | | hideResetButton | 是否隐藏重置按钮. | boolean | false | | resetButtonTitle | 重置按钮文本设置. | string | 重置/取消/上一步 | | submitButtonTitle | 提交按钮文本设置. | string | 提交/确定/查询 | | resetButtonProps | 重置按钮 Props 配置. | ButtonConfig | {} | | submitButtonProps | 提交按钮 Props 配置. | ButtonConfig | {} | | render | 自定义渲染提交器，一般配合 JSX 或 Vue 的 h 函数使用. | (props, doms: VNode[]) => VNode \| Array<VNode> | - | | onReset | 监听事件，权限大于全局 v-on 绑定的事件. | Function | - | | onSubmit | 监听提交事件，权限大于全局 v-on 绑定的事件. | Function | - |

案例：

• 在 template 中使用

<template>
  <!-- 通过 submitter.render 自定义提交器, 可以配置其它属性配合使用 -->
  <pro-form
    :submitter="{
      fillMode: 'aequilate',
      reverse: true,
      hideResetButton: false,
      submitButtonProps: {
        onClick: () => console.log('自定义提交事件')
      },
      onSubmit: entity => {
        console.log('局部绑定的提交事件，通过返回值控制是否继续', entity);
        return true;
      },
      render: (props, doms: VNode[]) => {
        return [...doms, h(ElButton, '按钮3'), h(ElButton, '按钮4')];
      }
    }"
  />
</template>

<script setup lang="ts">
  import { ProForm } from "@element-plus-ui/pro-form";
  import { ElButton } from "element-plus";
  import { h, VNode } from "vue";
</script>

• 在 JSX/TSX 中使用

<template>
  <!-- 通过函数类型自定义提交器 -->
  <pro-form :submitter="renderSubmitter"/>
</template>

<script setup lang="tsx">
  import { ProForm } from "@element-plus-ui/pro-form";
  import { ElButton } from "element-plus";
  import { VNode } from "vue";

  const renderSubmitter = (_props: Record<string, any>, doms: VNode[]) => {
    return [
      doms[0], 
      <ElButton onClick={() => console.log("点击按钮2")}>按钮2</ElButton>,
      <ElButton onClick={() => console.log("点击按钮3")}>按钮3</ElButton>
    ];
  };
</script>

• 通过插槽自定义(权重最大), 并使用提交器相关配置进行布局

<template>
  <pro-form 
    :submitter="{
      fillMode: 'aequilate',
      reverse: true,
    }"
  >
    <template #submitter="{ doms }">
      <!-- 使用内部重置按钮 -->
      <component :is="doms[0]" />
      <!-- 自定义按钮 -->
      <el-button type="primary">确定</el-button>
    </template>
  </pro-form>
</template>

<script setup lang="ts">
  import { ProForm } from "@element-plus-ui/pro-form";
</script>