@element-plus-ui/pro-form v1.0.0-beta.1

📦 安装

$ 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 的基础上，新增了以下属性和事件

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

• 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 组件相同

案例：

<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。

案例：

<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

案例：

<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

案例：

<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 组件文档处进行查阅

案例：

<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

ColumnConfig

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

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

ButtonConfig

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

SubmitterConfig

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

案例：

• 在 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>