Data Form 数据表单

该组件用于快速生成数据表单，内部封装了表单渲染、表单验证、文件处理等逻辑，只需传入fields和model属性即可。

全局配置

在全局配置组件属性。

DataForm组件属性配置

app.provide(DATA_FORM_KEY, {
  labelWidth: 'auto',
  labelPosition: 'right',
  // others props...
});

业务注入

在全局注入权限校验和处理文件相关业务。

注入权限校验业务

// 假设当前登录用户拥有以下权限标识
const authoritys = ['docAdmin'];
app.provide(CHECK_AUTHORITY_KEY, authority => authoritys.includes(authority));

注入文件上传地址

app.provide(FILE_UPLOAD_URL_KEY, '/api/file/upload');

注入文件上传header

app.provide(FILE_UPLOAD_HEADER_KEY, {
  Authorization: import.meta.env.VITE_AUTHORIZATION,
  'Blade-Auth': import.meta.env.VITE_BLADE_AUTH,
});

注入文件上传data

app.provide(FILE_UPLOAD_DATA_KEY, {
  action: 'upload',
  rename: true,
  belongOrgId: 'ruralLivingEnv',
  folder: `${new Date().getFullYear()}-${new Date().getMonth() + 1}`,
  flag: true,
});

注入处理文件上传response业务

app.provide(HANDLE_FILE_RESPONSE_KEY, response => {
  return response.data.fileUrl;
});

注入处理文件地址业务

app.provide(HANDLE_FILE_URLS_KEY, urls => {
  return (
    urls
      ?.split(',')
      ?.map(
        url =>
          `${import.meta.env.VITE_FILE_URL}/ruralLivingEnv/fileControll/downLoadFile?swfName=${url}`,
      ) ?? []
  );
});

基础用法

注意

如果表单组件中使用了富文本编辑器，在不使用的时候需要及时销毁表单组件，例如在ElDialog组件中使用，推荐设置destroy-on-close属性为true。

操作按钮

表单内部封装了提交、重置、返回、查询、新增、批量删除六个常用按钮，监听相应事件后自动渲染。

自定义按钮

除了使用组件内部封装好的按钮，你还可以通过buttons属性传入自定义按钮，更多按钮属性请查看DataFormButton。

权限校验

表单内部封装了权限校验逻辑，使用前需要在全局注入权限校验相关方法。内置按钮可以通过()设置权限标识，多个权限标识用|分隔。字段配置项和自定义按钮可以通过authority属性设置权限标识。如果权限标识校验没有通过，则对应的内容不会被渲染。

加密表单项2.1.0

组件提供了加密表单项对数据进行加密展示，加密表单项无法编辑，通过传入解密逻辑可以实现表单项解密后可编辑功能。

提示

加密表单项功能内部基于Verify组件实现，使用前需要在全局配置好验证码组件的相关属性。

行内表单

通过inline属性，你可以用该组件来生成搜索栏，因为搜索栏本质上也是一个表单。

网格布局

传入二维数组形式的fields可以生成网格布局的表单，默认平分宽度，可以通过span属性控制每个表单项的宽度，span为24表示占满整行。

注意

如果是行内表单，则网格布局不会生效。

设置默认值

在某些业务场景，例如修改详情功能，表单可能需要设置默认值，并且某些字段仅作为修改接口的参数，并不需要渲染在页面上。你可以通过model属性来实现表单数据的双向绑定，并且不设置fieldType字段实现把相关字段放在表单数据中，但是不进行渲染。

动态表单

可以通过字段配置项或自定义按钮的watchEffect实现表单内容的动态切换，注意需要动态切换的fields或buttons必须是响应式数据。

表单校验

表单内部封装了校验逻辑，只有required属性为true的表单项才会自动生成校验规则。你可以通过给buttons属性中的按钮设置validate属性来开启表单校验，表单内置的提交和查询按钮validate属性默认为true。

自定义校验规则

你可以通过rules属性给每个表单项传入自定义校验规则，rules支持传入数组，并按顺序同时校验多个自定义规则。框架提供了一些常用校验规则可以直接使用。

自定义表单项

通过设置fieldType为slot，你可以自定义表单项的内容。

属性&事件&插槽透传

Data Form基于ElForm封装，所以你可以传入ElForm的所有属性和事件，并且在字段配置属性fields中，根据fieldType的不同，你可以透传属性和事件给对应的渲染组件，具体fieldType对应的渲染组件请查看fieldType可选值。

属性

属性名	说明	类型	默认值
model	表单数据	`T`	—
fields	字段配置信息	`DataFormFields<T>`	[]
inline	行内表单模式	`boolean`	false
buttons	表单操作按钮	`DataFormButtons<T>`	[]
show-reset	是否显示重置按钮	`boolean`	false

DataFormField

属性名	说明	类型	默认值
prop	字段名称	`string`	—
fieldType	表单项字段类型	`FormItemFieldType` `'input' \| 'textarea' \| 'phone' \| 'idcard' \| 'ciphertext' \| 'cipherPhone' \| 'cipherIdcard' \| 'select' \| 'cascader' \| 'radio' \| 'checkbox' \| 'date' \| 'dateRange' \| 'time' \| 'timeRange' \| 'datetime' \| 'datetimeRange' \| 'switch' \| 'number' \| 'numberRange' \| 'rate' \| 'color' \| 'image' \| 'audio' \| 'video' \| 'file' \| 'dict' \| 'dictId' \| 'grid' \| 'gridCode' \| 'gridId' \| 'location' \| 'verify' \| 'richText' \| 'slot'`	—
fieldIndex	表单项展示位置	`number`	—
span	表单项占据的列数	`number`	24 / 行内表单项数
authority	权限标识	`string` / `string[]`	—
show	是否展示	`boolean`	true
style	表单项样式	`string` / `CSSProperties`	—
watchEffect	表单项副作用，通常用于实现动态表单功能	`Function`	—
tooltip2.1.0	表单项提示信息	`string`	—
placement2.1.0	表单项提示信息出现的位置	`FormItemPlacement`	top

除了上述属性，你还可以透传对应渲染组件的所有属性和事件。

fieldType值对应渲染组件

字段类型	说明	对应的渲染组件
`input`	输入框	ElInput
`textarea`	文本域	ElInput
`phone`2.1.2	输入框(带手机号校验)	ElInput
`idcard`2.1.2	输入框(带身份证校验)	ElInput
`ciphertext`2.1.0	加密输入框	ElInput、LivVerify
`cipherPhone`2.1.2	加密输入框(带手机号校验)	ElInput、LivVerify
`cipherIdcard`2.1.2	加密输入框(带身份证校验)	ElInput、LivVerify
`select`	选择器	LivSelect
`date`	日期选择器	ElDatePicker
`dateRange`2.2.0	日期范围选择器	ElDatePicker
`time`	时间选择器	ElTimePicker
`timeRange`2.2.0	时间范围选择器	ElTimePicker
`datetime`2.2.0	日期时间选择器	ElDatePicker
`datetimeRange`2.2.0	日期时间范围选择器	ElDatePicker
`radio`	单选框	LivRadio
`checkbox`	多选框	LivCheckbox
`number`	数字输入框	ElInputNumber
`numberRange`	数组范围	LivNumberRange
`rate`	评分	ElRate
`switch`	开关	ElSwitch
`clolor`	拾色器	ElColorPicker
`image` `audio` `video` `file`	图片/音频/视频/文件上传	ElUpload
`dict` `dictId`	字典选择器	DictSelect
`grid` `gridId` `gridCode`	网格选择器	LivGridCascader
`location`2.1.0	地图选点	LivLocationPicker
`verify`2.1.2	验证码	LivVerify
`richText`	富文本编辑器	LivRichText
`slot`	插槽	—

DataFormButton

属性名	说明	类型	默认值
name	按钮名称	`string`	—
authority	按钮权限	`string` / `string[]`	—
order	按钮顺序	`number`	—
show	是否显示按钮	`boolean`	true
validate	是否需要校验表单	`boolean`	false
onClick	按钮点击事件	`Function`	—
watchEffect	按钮副作用	`Function`	—

除了上述属性，你还可以透传ElButton的所有属性和事件。

事件

事件名	说明	类型
submit	点击提交按钮时触发	`Function`
rest	点击重置按钮时触发	`Function`
back	点击返回按钮时触发	`Function`
search	点击查询按钮时触发	`Function`
add	点击新增按钮时触发	`Function`
batchDelete	点击批量删除按钮时触发	`Function`

类型声明

import type { MaybeRef } from 'vue';
import type { ComponentExposed } from 'vue-component-type-helpers';
import type {
  ButtonProps as ElButtonProps,
  FormInstance as ElFormInstance,
  FormProps as ElFormProps,
} from 'element-plus';
import type { Writable } from 'element-plus/es/utils';
import type {
  CascaderFormItemField,
  CheckboxFormItemField,
  CiphertextFormItemField,
  ColorFormItemField,
  DateFormItemField,
  DateRangeFormItemField,
  DatetimeFormItemField,
  DatetimeRangeFormItemField,
  DictFormItemField,
  GridFormItemField,
  InputFormItemField,
  LocationFormItemField,
  NumberFormItemField,
  NumberRangeFormItemField,
  RadioFormItemField,
  RateFormItemField,
  RenderlessFormItemField,
  RichTextFormItemField,
  SelectFormItemField,
  SlotFormItemField,
  SwitchFormItemField,
  TextareaFormItemField,
  TimeFormItemField,
  TimeRangeFormItemField,
  UploadFormItemField,
  VerifyFormItemField,
} from '../../form-item';
import type { TwoDimensionArrayable } from '@liv-web/utils';
import DataForm from './data-form.vue';

/**
 * 表单组件属性
 * @template T 表单的数据类型
 */
export interface DataFormProps<T = Record<string | number | symbol, any>, U = DataFormFields<T>> {
  /**
   * 表单数据
   * @template T 表单的数据类型
   */
  model: T;
  /**-
   * 表单字段配置项
   * @template U 表单配置项类型
   */
  fields?: U;
  /**
   * 行内表单模式
   * @defaultValue false
   */
  inline?: boolean;
  /**
   * 表单操作按钮
   * @remarks 如果表单inline属性为true，则按钮展示在最后一个表单项右侧。如果inline属性为false，则按钮居中展示在最后一个表单项底部
   * @template T 表单的数据类型
   * @defaultValue []
   */
  buttons?: DataFormButtons<T>;
  /**
   * 是否显示重置按钮
   * @remarks 组件内置的重置按钮已经实现了重置表单逻辑，设置`showReset`属性为`true`即可，也可以手动传入组件的@reset方法以覆盖表单的重置逻辑
   * @defaultValue false
   */
  showReset?: boolean;
  /**
   * 表单提交按钮点击事件
   * @remarks 传入该属性后会自动渲染提交按钮，并且会自动触发表单校验，校验通过后才会触发{@link onSubmit}属性传入的回调方法
   * @template T 表单的数据类型
   * @param form 表单数据
   * @param formRef 表单实例
   */
  onSubmit?: (form: T, formRef: ElFormInstance | null) => void | Promise<any>;
  /**
   * 表单查询按钮点击事件
   * @remarks 传入该属性后会自动渲染搜索按钮
   * @template T 表单的数据类型
   * @param form 表单数据
   * @param formRef 表单实例
   */
  onSearch?: (form: T, formRef: ElFormInstance | null) => void | Promise<any>;
  /**
   * 表单重置按钮点击事件
   * @remarks 传入该属性后会自动渲染重置按钮
   * @template T 表单的数据类型
   * @param form 表单数据
   * @param formRef 表单实例
   */
  onReset?: (form: T, formRef: ElFormInstance | null) => void | Promise<any>;
  /**
   * 表单新增按钮点击事件
   * @remarks 传入该属性后会自动渲染新增按钮
   * @template T 表单的数据类型
   * @param form 表单数据
   * @param formRef 表单实例
   */
  onAdd?: (form: T, formRef: ElFormInstance | null) => void | Promise<any>;
  /**
   * 表单批量删除按钮点击事件
   * @remarks 传入该属性后会自动渲染批量删除按钮
   * @template T 表单的数据类型
   * @param form 表单数据
   * @param formRef 表单实例
   */
  onBatchDelete?: (form: T, formRef: ElFormInstance | null) => void | Promise<any>;
  /**
   * 表单返回按钮点击事件
   * @remarks 传入该属性后会自动渲染返回按钮
   * @template T 表单的数据类型
   * @param form 表单数据
   * @param formRef 表单实例
   */
  onBack?: (form: T, formRef: ElFormInstance | null) => void | Promise<any>;
}

/**
 * 数据表单组件实例
 * @template T 表单的数据类型
 * @template U 表单配置项类型
 */
export type DataFormInstance<
  T extends Record<string | number | symbol, any> = Record<string | number | symbol, any>,
  U extends DataFormFields<T> = DataFormFields<T>,
> = ComponentExposed<typeof DataForm<T, U>>;

/**
 * 表单字段配置项
 * @template T 表单的数据类型
 */
export type DataFormField<T = Record<string | number | symbol, any>> =
  | RenderlessFormItemField<T>
  | InputFormItemField<T>
  | TextareaFormItemField<T>
  | CiphertextFormItemField<T>
  | SelectFormItemField<T>
  | CascaderFormItemField<T>
  | RadioFormItemField<T>
  | CheckboxFormItemField<T>
  | DateFormItemField<T>
  | DateRangeFormItemField<T>
  | TimeFormItemField<T>
  | TimeRangeFormItemField<T>
  | DatetimeFormItemField<T>
  | DatetimeRangeFormItemField<T>
  | SwitchFormItemField<T>
  | NumberFormItemField<T>
  | NumberRangeFormItemField<T>
  | RateFormItemField<T>
  | ColorFormItemField<T>
  | UploadFormItemField<T>
  | DictFormItemField<T>
  | GridFormItemField<T>
  | LocationFormItemField<T>
  | RichTextFormItemField<T>
  | VerifyFormItemField<T>
  | SlotFormItemField<T>;

/**
 * 表单组件字段配置项集合
 * @template T 表单的数据类型
 */
export type DataFormFields<T = Record<string | number | symbol, any>> = TwoDimensionArrayable<
  MaybeRef<DataFormField<T>>
>;

/**
 * 表单操作按钮
 * @template T 表单的数据类型
 */
export interface DataFormButton<T = Record<string | number | symbol, any>>
  extends Partial<Writable<ElButtonProps>> {
  /**
   * 按钮名称
   */
  name: string;
  /**
   * 按钮权限
   */
  authority?: string | string[];
  /**
   * 展示顺序
   * @remarks 组件内置的提交、搜索、重置、新增、批量删除、返回按钮order分别为10、20、30、40、50、60，如果想要让自定义按钮显示在提交和重置按钮之间，order可以设置为10~30之间，如果不设置order则默认展示在内置按钮后面
   */
  order?: number;
  /**
   * 是否显示按钮
   * @defaultValue true
   */
  show?: boolean;
  /**
   * 是否需要校验表单
   * @remarks 如果为true，点击按钮会自动触发表单校验，并且校验通过后才会执行{@link onClick}事件
   * @defaultValue false
   */
  validate?: boolean;
  /**
   * 唯一标识
   * @remark 主要用于组件内部区分不同按钮
   */
  key?: string | symbol;
  /**
   * 按钮点击事件
   * @template T 表格的数据类型
   * @param form 表单数据
   * @param formRef 表单实例
   */
  onClick?: (form: T, formRef: ElFormInstance | null) => void | Promise<any>;
  /**
   * 按钮副作用
   * @remarks 可以在回调函数中拿到表单数据及实例，并动态修改按钮配置
   * @template T 表单的数据类型
   */
  watchEffect?: (form: T, formRef: ElFormInstance | null) => void;
}

/**
 * 表单操作按钮集合
 * @template T 表单的数据类型
 */
export type DataFormButtons<T = Record<string | number | symbol, any>> = DataFormButton<T>[];

/**
 * 数据表单组件包含透传属性在内的全部属性
 * @template T 表单的数据类型
 */
export type DataFormFullProps<T> = Partial<ElFormProps & DataFormProps<T>>;

Data Form 数据表单 ​

全局配置 ​

业务注入 ​

基础用法 ​

操作按钮 ​

自定义按钮 ​

权限校验 ​

加密表单项2.1.0 ​

行内表单 ​

网格布局 ​

设置默认值 ​

动态表单 ​

表单校验 ​

自定义校验规则 ​

自定义表单项 ​

属性&事件&插槽透传 ​

属性 ​

DataFormField ​

fieldType值对应渲染组件 ​

DataFormButton ​

事件 ​