EyForm组件示例(推荐使用)

TIP

开发过程切勿使用直接修改配置的方式修改元素属性，而应该采用依赖注入并配合setElProps,setFormProps等方式修改元素属性

常规使用form组件时我们需要完整定义value的值和在template写繁多的组件,当组件之间发生联动时需要使用watch或事件触发解。

本组件则是将这部分都封装了起来。在配置中完成实现各个组件，并将联动主逻辑实现在配置当中，使得整体代码更易阅读、维护。

基本使用 formGroup

在EyForm中你依旧可以保留ant-design-vue中form组件的配置

value: 该值如果没有默认值可直接设置为{}组件内部会处理，免去开发者设置初始value的时间

form-group：用配置form表单数组，formGroupItem具体配置见表

formGroupItem.formProps:对应ant-design-vue中form-item配置

formGroupItem.elProps:对应ant-design-vue中表单元素配置

<template>
  <div>
    <EyForm
      ref="refEyForm"
      v-model:value="formModel"
      :label-col="{ style: { width: '150px' } }"
      style="max-width: 600px"
      :form-group="formGroup"
    >
      <template #buttons>
        <a-button type="primary" @click="submit">提交</a-button>
        <a-button @click="() => refEyForm?.resetFields()">重置</a-button>
      </template>
    </EyForm>
  </div>
</template>

<script setup lang="ts">
import { reactive, ref } from 'vue';
import { EyForm } from 'ey-admin';
// 只需配置formGroup完成表单渲染
import { formGroup } from './config';
import type { EyFormInstance } from 'ey-admin';

const formModel = ref({});
const refEyForm = ref<EyFormInstance>();
async function submit() {
  await refEyForm.value!.validateFields();
  const dealData = refEyForm.value!.getFormData();
  // 可获取由内部处理后处理后的值
  console.log('🚀 ~ submit ~ dealData:', dealData);
}
</script>

<style scoped></style>

import type { FormGroupItem } from 'ey-admin';

export const formGroup: FormGroupItem[] = [
  {
    key: 'place',
    label: '地点',
    renderKey: 'renderSelect',
    elProps: {
      api,
      alwaysLoad: true,
    },
  },
  {
    label: '钟爱颜色',
    key: 'loveColor',
    renderKey: 'renderSelect',
    formProps: {
      required: true,
    },
    elProps: {
      fieldNames: {
        label: 'labelabc',
      },
      style: {
        width: '100%',
      },
    },
    options: [
      { labelabc: '红色', value: '1' },
      { labelabc: '蓝色', value: '2' },
    ],
  },
  {
    key: 'name',
    label: '姓名',
    renderKey: 'renderInput',
    formProps: {
      required: true,
    },
  },

  {
    key: 'age',
    label: '年龄',
    renderKey: 'renderInputNumber',
  },
  {
    key: 'job',
    label: '职业',
  },
];
export function api() {
  return new Promise(resolve => {
    setTimeout(() => {
      resolve({
        data: [
          { label: '咖啡厅', value: '1' },
          { label: '餐厅', value: '2' },
          { label: '图书馆', value: '3' },
        ],
      });
    }, 1000);
  });
}

隐藏代码

依赖注入——表单项动态关联 depends

结合[depends]属性,在列表formGroupItem中使用depend即可完成动态关联

可用设置包括 setFormProp,setFormProps,setElProp,setElProps,toogle

具体使用查看depends && formGroupItem.depend

如下：

• 选中北京则不展示城市选项
• 省份选中广东、湖南则各自展示其城市
• 员工选择是则证件号必填，选择否则证件号为非必填

<template>
  <EyForm
    ref="daform"
    v-model:value="formModel"
    :label-col="{ style: { width: '150px' } }"
    style="max-width: 600px"
    :form-group="formGroup"
    :depends="depends"
  />
</template>

<script setup lang="ts">
import { ref, toRefs } from 'vue';
import { EyForm } from 'ey-admin';
import { formGroup } from './config';

const formModel = ref({
  province: undefined,
  city: undefined,
  isStaff: 1,
});

const depends = {
  province: [],
  city: [formModel],
  idNumber: [formModel],
};
</script>

<style scoped></style>

import type { FormGroupItem } from 'ey-admin';
const provinceCity = {
  gd: [
    { label: '广州', value: 1 },
    { label: '深圳', value: 2 },
  ],
  hn: [{ label: '长沙', value: 1 }],
};
export const formGroup: FormGroupItem[] = [
  {
    key: 'province',
    label: '省',
    renderKey: 'renderSelect',
    elProps: {
      options: [
        { label: '北京', value: 'bj' },
        { label: '广东', value: 'gd' },
        { label: '湖南', value: 'hn' },
      ],
    },
    formProps: {
      required: true,
    },
  },
  {
    key: 'city',
    label: '市',
    renderKey: 'renderSelect',
    elProps: {
      options: [
        { label: '广州', value: 1 },
        { label: '深圳', value: 2 },
      ],
    },
    depend({ toogle, setElProp, formData }, [dep]: any[]) {
      toogle(dep.province !== 'bj');
      // 设置options
      const cityOptions = provinceCity[dep.province as string];
      if (cityOptions) {
        setElProp('options', cityOptions);
        formData.city = undefined;
      }
    },
  },
  {
    key: 'isStaff',
    label: '是否员工',
    renderKey: 'renderRadio',
    options: [
      { label: '是', value: 1 },
      { label: '否', value: 0 },
    ],
  },
  {
    key: 'idNumber',
    label: '证件号',
    formProps: {
      required: true,
    },
    depend({ setFormProp }, [dep]: any) {
      setFormProp('required', !!dep.isStaff);
    },
  },
];

隐藏代码

栅格布局 grid

gird: grid布局实现在不同屏幕下响应式展示、主要用于表单搜索项

formGroupItem.colDouble: 将当前表单项两倍于其他表单项展示，如下方【时间范围】

<template>
  <EyForm ref="daform" v-model:value="formModel" grid :form-group="formGroup">
    <template #buttons>
      <a-button type="primary" @click="submit">搜索 </a-button>
      <a-button @click="() => daform?.resetFields()">重置</a-button>
    </template>
  </EyForm>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { EyForm } from 'ey-admin';
import dayjs from 'dayjs';
import { formGroup } from './config';
import type { EyFormInstance } from 'ey-admin';

const formModel = ref({
  timeRange: [dayjs(1714838400000), dayjs(1717516800000)],
});

const daform = ref<EyFormInstance>();
async function submit() {
  daform.value!.validateFields().then(() => {
    console.log(daform.value!.getFormData());
  });
}
</script>

<style scoped></style>

import type { FormGroupItem } from 'ey-admin';
export const formGroup: FormGroupItem[] = [
  {
    key: 'id',
    label: 'id',
    renderKey: 'renderInput',
  },
  {
    key: 'name',
    label: '姓名',
    renderKey: 'renderInput',
  },
  {
    key: 'age',
    label: '年龄',
    renderKey: 'renderInputNumber',
  },
  {
    label: '国家',
    key: 'country',
    renderKey: 'renderSelect',
    options: [
      { label: '中国', value: '1' },
      { label: '俄罗斯', value: '2' },
    ],
    formProps: {
      required: true,
    },
  },
  {
    key: 'timeRange',
    label: '时间范围',
    renderKey: 'renderRangePicker',
    colDouble: true,
    elProps: {
      allowClear: true,
      picker: 'date',
    },
  },
];

隐藏代码

值转化 formatter

通常用于创建时展示字段与提交字段不同时

如下是

• 将字符串转为数字

• 将的dayjs转为 string与时间戳

• 将选中的数组转字符串

formatter当前值 'dateToString'| 'dateToTime' | 'numToString'| 'stringToNum'

<template>
  <EyForm
    ref="daform"
    v-model:value="formModel"
    :label-col="{ style: { width: '120px' } }"
    :form-group="formGroup"
  >
    <template #buttons>
      <a-button type="primary" @click="submit">搜索</a-button>
      <a-button @click="() => daform?.resetFields()">重置</a-button>
    </template>
  </EyForm>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { EyForm } from 'ey-admin';
import dayjs from 'dayjs';
import { formGroup } from './config';
import type { EyFormInstance } from 'ey-admin';

const formModel = ref({
  numToString: 123,
  stringToNum: '1',
  dateToString: [dayjs(1714838400000), dayjs(1717516800000)],
  dateToTime: [dayjs(1714838400000), dayjs(1717516800000)],
  dateToString1: dayjs(1714838400000),
  dateToTime1: dayjs(1714838400000),
});

const daform = ref<EyFormInstance>();
async function submit() {
  await daform.value!.validateFields();
  console.log(daform.value!.getFormData());
}
</script>

<style scoped></style>

import type { FormGroupItem } from 'ey-admin';
export const formGroup: FormGroupItem[] = [
  {
    label: 'numToString',
    key: 'numToString',
    renderKey: 'renderInputNumber',
    formatter: 'numToString',
  },
  {
    label: 'stringToNum',
    key: 'stringToNum',
    renderKey: 'renderSelect',
    formatter: 'stringToNum',
    elProps: {
      options: [
        { label: '中国', value: '1' },
        { label: '俄罗斯', value: '2' },
      ],
    },
  },
  {
    label: 'dateToString',
    key: 'dateToString',
    renderKey: 'renderRangePicker',
    formatter: 'dateToString',
    colDouble: true,
    elProps: {
      allowClear: true,
      picker: 'date',
    },
  },
  {
    label: 'dateToTime',
    key: 'dateToTime',
    renderKey: 'renderRangePicker',
    formatter: 'dateToTime',
    colDouble: true,
    elProps: {
      allowClear: true,
      picker: 'date',
    },
  },
  {
    label: 'dateToString1',
    key: 'dateToString1',
    renderKey: 'renderDatePicker',
    formatter: 'dateToString',
    colDouble: true,
    elProps: {
      allowClear: true,
      picker: 'date',
    },
  },
  {
    label: 'dateToTime1',
    key: 'dateToTime1',
    renderKey: 'renderDatePicker',
    formatter: 'dateToTime',
    colDouble: true,
    elProps: {
      allowClear: true,
      picker: 'date',
    },
  },
];

隐藏代码

TIP

dateToString默认使用的是'YYYY-MM-DD'格式，如有其他形式请使用TimePicker自带属性配置

插槽使用

未应对一些特殊情况，ey-from表单支持用户使用插槽的形式来操作自己的form表单

<template>
  <div>
    <EyForm
      ref="refEyForm"
      v-model:value="formModel"
      :label-col="{ style: { width: '150px' } }"
      style="max-width: 600px"
      :form-group="formGroup"
    >
      <template #special>
        <FormItem label="插槽">
          <Space>
            <InputNumber v-model:value="formModel.special1" />
            <FormItemRest>
              <InputNumber
                placeholder="这是2倍的计算结果"
                :value="formModel.doubleSpecial"
                disabled
              />
            </FormItemRest>
          </Space>
        </FormItem>
      </template>
      <template #buttons>
        <a-button type="primary" @click="submit">提交</a-button>
        <a-button @click="() => refEyForm?.resetFields()">重置</a-button>
      </template>
    </EyForm>
  </div>
</template>

<script setup lang="ts">
import { ref, watch } from 'vue';
import { EyForm } from 'ey-admin';
// 只需配置formGroup完成表单渲染
import { FormItem, FormItemRest, InputNumber, Space } from 'ant-design-vue';
import { formGroup } from './config';
import type { EyFormInstance } from 'ey-admin';

type TFormModel = {
  age?: number;
  job: string;
  special1?: number;
  doubleSpecial?: number;
};

const formModel = ref<TFormModel>({
  age: undefined,
  special1: undefined,
  doubleSpecial: undefined,
  job: '',
});

watch(
  () => formModel.value.special1,
  val => {
    formModel.value.doubleSpecial = val ? val * 2 : 0;
  },
);

const refEyForm = ref<EyFormInstance>();
async function submit() {
  refEyForm.value!.validateFields();
}
</script>

<style scoped></style>

import type { FormGroupItem } from 'ey-admin';

export const formGroup: FormGroupItem[] = [
  {
    key: 'age',
    label: '年龄',
    renderKey: 'renderInputNumber',
  },
  {
    key: 'job',
    label: '职业',
  },
  {
    key: 'special',
    label: '插槽项',
  },
];

隐藏代码

显示转化

比如编辑时后端传一个string，前端需要显示用number,则使用showFormatter:stringToNumber

或者在formatter为numberToString时自动进行显示转换

WARNING

敬请期待

特殊字段释意

formGroupItem.renderKey

render后面接着的类型就是要渲染的form表单类型

renderInput | renderInputNumber | renderTextarea | renderSelect | renderMonthPicker | renderDatePicker | renderRangePicker | renderCheckbox | renderRadio | renderSwitch

formGroupItem.elProps

对应renderKey渲染元素的props，例如下方renderKey为renderInput，那么此时elProps即为input组件的属性

注意：renderSelect值是renderSelect时对应的时EySelect组件而不是ant-design-vue中的select

export const formGroup: FormGroupItem[] = [
    {
    key: 'name',
    label: '姓名',
    renderKey: 'renderInput',
    formProps: {
      required: true,
    },
    elProps:{
      disabled:true
    }
  },
]

grid

eyFom保留antDesign原始布局，即添加layout属性（horizontal | vertical | inline）即可设置对应布局。

在此基础上添加grip布局,只需为form加入grid属性即可，该属性常用于表格之类的搜索栏使用，使得搜索框可对应页面响应式变化

开启grid布局之后,可在每个item中配置colspan属性自定义效果，若配置了colspanDouble属性则会占据两个默认配置位置

grid默认相关配置如下：

 const colspan = { xs: 24, sm: 24,  md: 8, lg: 8, xl: 6, xxl: 4, xxxl: 4 }

depends && formGroupItem.depend

depends

TIP

注意键值应是表单对应的key,而值应该是有响应式数据组成的数组

我们可以如下用depends注入对应的依赖对象到eyform，对应props类型如下

  depends: {
    type: Object as PropType<
      Record<string, (Ref<any> | (() => UnwrapNestedRefs<any>))[]>
    >,
    default: () => ({}),
  },

当依赖项中的值变化时，若formGroupItem配有depend字段，则会自动执行

const formModel = reactive({
  province: undefined,
  city: undefined,
  isStaff: 1,
});
const { province } = toRefs(formModel);
const depends = {
  city: [province],
  idNumber: [() => formModel.isStaff], 
};

formGroupItem.depend

第一项会返回setFormProp,setFormProps,setElProp,setElProps,toogle

toogle传入boolean控制显隐

setElProp,setFormProp使用setElProp(key,value),setFormProp(key,value)控制单个属性

setElProps,setFormProps有个回调函数，传入当前配置与依赖项数组，用户的返回值即为设置的属性

depend({ setFormProp }, [isStaff]) {
  // 设置form的必选属性
  setFormProp('required', !!isStaff);
}

API

Attributes

成员	说明	类型	默认值
value	初始化数据	Record<string, any>	{}
formGroup	表单项配置	Array<FormGroupItem>	-
grid	开启栅格布局	boolean	false
gripInlineBtn	栅格布局中按钮和输入框是否位于同一行	boolean	false
formProps	用于 v-bind 绑定 antDForm 表单组件 props	FormProps	{}
rowProps	row 相关配置	RowProps	{}
depends	表单依赖项	Record<string, (Ref<any> | (() => UnwrapNestedRefs<any>))[]>	{}

FormGroupItem

成员	说明	类型	默认值
key	表单中的key（唯一标识）	string	-
renderKey	表单要渲染的元素	renderKey 详细类型见文档说明	renderInput
formatter	要转化输出的值	formatterKey | ((data: unknown) => unknown)	-
label	表单label	string	-
formProps	对应ant-design-vue中form-item的值	FormItemProps	-
options	ey-select中的options选项	SelectProps['options']	-
elProps	对于renderKey元素的属性	T	-
colProps	grid布局时候可使用	ColProps	-
colDouble	默认布局时使用双倍的col值	boolean	-
depend	formitem的依赖项	(FormGroupItemDepend: TFormGroupItemDepend, deps: unknown[]) => void	-

Exposes

事件名	说明	类型
getFormData	获取处理后的form值	Function
其他说明	其他则与ant-design-vue的form完全相同,点击查看文档