Search Form 搜索表单

该组件用于快速生成搜索表单，内部封装了表单渲染、折叠展开、查询重置等逻辑，只需传入fields和model属性即可。

全局配置

在全局配置组件属性。

SearchForm组件属性配置

app.provide(SEARCH_FORM_KEY, {
  labelWidth: 'auto',
  labelPosition: 'right',
  column: 1,
  importOptions: {
    tip: '导入文件最大不能超过500KB',
    maxSize: 500 * 1024,
    extensions: ['xls', 'xlsx'],
  },
  // others props...
});

业务注入

在全局注入权限校验相关业务。

注入权限校验业务

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

基础用法

操作按钮

表单内部封装了查询、重置、新增、批量删除、导入、导出、下载导入模板七个常用按钮，监听相应事件后自动渲染。

自定义按钮

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

导入导出2.1.0

表单内部封装了统一的导入、导出、下载导入模板功能。可以通过import-options属性设置组件的导入配置，也可以在全局进行统一配置。

权限校验

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

动态表单

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

自定义表单项

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

属性&事件&插槽透传

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

属性

属性名	说明	类型	默认值
model	表单数据	`T`	—
fields	字段配置信息	`SearchFormFields<T>`	[]
column	表单列数	`number`	3
buttons	表单操作按钮	`SearchFormButtons<T>`	[]
show-reset	是否显示重置按钮	`boolean`	true
import-options2.1.0	导入配置	`ImportOptions`	—

SearchFormField

属性名	说明	类型	默认值
prop	字段名称	`string`	—
fieldType	表单项字段类型	`FormItemFieldType`	—
authority	权限标识	`string` / `string[]`	—
show	是否展示	`boolean`	true
style	表单项样式，该样式将绑定在表单项具体的实现组件上	`string` / `CSSProperties`	—
watchEffect	表单项副作用，通常用于实现动态表单功能	`Function`	—

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

fieldType值对应渲染组件

字段类型	说明	对应的渲染组件
`input`	输入框	ElInput
`phone`2.1.2	输入框(带手机号校验)	ElInput
`idcard`2.1.2	输入框(带身份证校验)	ElInput
`select`	选择器	LivSelect
`date`	日期选择器	ElDatePicker
`time`	时间选择器	ElTimePicker
`radio`	单选框	LivRadio
`checkbox`	多选框	LivCheckbox
`number`	数字输入框	ElInputNumber
`numberRange`	数组范围	LivNumberRange
`switch`	开关	ElSwitch
`dict` `dictId`	字典选择器	DictSelect
`grid` `gridId` `gridCode`	网格选择器	LivGridCascader
`slot`	—	—

SearchFormButton

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

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

事件

事件名	说明	类型
search	点击查询按钮时	`Function`
reset	点击重置按钮时触发	`Function`
add	点击新增按钮时触发	`Function`
batchDelete	点击批量删除按钮时触发	`Function`
import2.1.0	选中导入文件后触发	`Function`
template2.1.0	点击下载模板按钮时触发	`Function`
export	点击导出按钮时触发	`Function`

类型声明

import type {
  ButtonProps as ElButtonProps,
  FormInstance as ElFormInstance,
  FormProps as ElFormProps,
} from 'element-plus';
import type {
  CascaderFormItemField,
  CheckboxFormItemField,
  DateFormItemField,
  DateRangeFormItemField,
  DatetimeFormItemField,
  DatetimeRangeFormItemField,
  DictFormItemField,
  GridFormItemField,
  InputFormItemField,
  NumberFormItemField,
  NumberRangeFormItemField,
  RadioFormItemField,
  RenderlessFormItemField,
  SelectFormItemField,
  SlotFormItemField,
  SwitchFormItemField,
  TimeFormItemField,
  TimeRangeFormItemField,
} from '../../form-item';
import type { ComponentExposed } from 'vue-component-type-helpers';
import SearchForm from './search-form.vue';
import { Writable } from 'element-plus/es/utils';
import type { DataFormFields } from '../../data-form';

/**
 * 搜索表单组件属性
 * @template T 表单的数据类型
 */
export interface SearchFormProps<
  T = Record<string | number | symbol, any>,
  U = SearchFormFields<T>,
> {
  /**
   * 表单数据
   * @template T 表单的数据类型
   */
  model: T;
  /**
   * 表单字段配置项
   * @template U 表单配置项类型
   */
  fields?: U;
  /**
   * 表单列数
   * @defaultValue 3
   */
  column?: number;
  /**
   * 表单操作按钮
   * @remarks 如果表单inline属性为true，则按钮展示在最后一个表单项右侧。如果inline属性为false，则按钮居中展示在最后一个表单项底部
   * @template T 表单的数据类型
   * @defaultValue []
   */
  buttons?: SearchFormButton<T>[];
  /**
   * 是否显示重置按钮
   * @defaultValue true
   */
  showReset?: boolean;
  /**
   * 导入配置
   */
  importOptions?: ImportOptions;
  /**
   * 表单搜索按钮点击事件
   * @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 传入该属性后会自动渲染导入按钮
   * @param file 文件对象
   */
  onImport?: (file: File) => void | Promise<any>;
  /**
   * 表单导出按钮点击事件
   * @remarks 传入该属性后会自动渲染导出按钮
   * @template T 表单的数据类型
   * @param form 表单数据
   * @param formRef 表单实例
   */
  onExport?: (form: T, formRef: ElFormInstance | null) => void | Promise<any>;
  /**
   * 导入弹窗下载导入模板按钮点击事件
   * @remarks 传入该属性后会自动渲染下载导入模板按钮
   */
  onTemplate?: () => void | string | Promise<any> | DataFormFields<T>;
}

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

/**
 * 表单字段配置项
 * @template T 表单的数据类型
 */
export type SearchFormField<T = Record<string | number | symbol, any>> =
  | RenderlessFormItemField<T>
  | InputFormItemField<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>
  | DictFormItemField<T>
  | GridFormItemField<T>
  | SlotFormItemField<T>;

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

/**
 * 表单操作按钮
 * @template T 表单的数据类型
 */
export interface SearchFormButton<T = Record<string | number | symbol, any>>
  extends Partial<Writable<ElButtonProps>> {
  /**
   * 按钮名称
   */
  name: string;
  /**
   * 按钮权限
   */
  authority?: string | string[];
  /**
   * 展示顺序
   * @remarks 组件内置的新增、批量删除、导入、导出按钮`order`属性分别为10、20、30、40，如果想要让自定义按钮显示在新增和批量删除按钮之间，`order`属性可以设置为10~20之间，如果不设置`order`属性则默认展示在内置按钮后面
   */
  order?: number;
  /**
   * 展示位置
   * @remarks 组件内置的新增、批量删除、导入按钮`position`属性默认为`left`，导出按钮`position`属性默认为`right`
   * @defaultValue 'left'
   */
  position?: 'left' | 'right';
  /**
   * 是否显示按钮
   * @defaultValue true
   */
  show?: boolean;
  /**
   * 加载状态
   * @defaultValue false
   */
  loading?: boolean;
  /**
   * 是否需要校验表单
   * @remarks 如果为true，点击按钮会自动触发表单校验，并且校验通过后才会执行{@link onClick}事件，组件内置的查询按钮`validate`属性默认为`true`
   * @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;
}

/**
 * 表单内置导入按钮
 */
export interface SearchFormImportButton<T> extends Omit<SearchFormButton<T>, 'onClick'> {
  /**
   * 按钮点击事件
   */
  onClick?: () => void;
  /**
   *
   * @param file 选中的文件对象
   * @returns
   */
  handleImport?: (file: File) => void | Promise<any>;
}

/**
 * 表单内置下载模板按钮
 */
export interface SearchFormTemplateButton<T> extends Omit<SearchFormButton<T>, 'onClick'> {
  /**
   * 按钮点击事件
   */
  onClick?: () => void | string | Promise<any> | DataFormFields<T>;
}

/**
 * 表单内置按钮类型
 */
export type SearchFormInnerButton<T> =
  | SearchFormButton<T>
  | SearchFormImportButton<T>
  | SearchFormTemplateButton<T>;

/**
 * 导入配置
 */
export interface ImportOptions {
  /**
   * 提示说明文字
   */
  tip?: string;
  /**
   * 文件大小限制，单位为字节
   */
  maxSize?: number;
  /**
   * 允许上传的文件类型，例如`['xls', '.xlsx']`
   * @defaultValue ['xls', '.xlsx']
   */
  extensions?: string[];
  /**
   * 模板文件名
   * @remark 仅通过fields配置项在前端生成模板文件时生效
   */
  fileName?: string;
  /**
   * 表名称
   * @remark 仅通过fields配置项在前端生成模板文件时生效
   */
  sheetName?: string;
  /**
   * 忽略的字段
   * @remark 仅通过fields配置项在前端生成模板文件时生效
   */
  ignore?: string[];
}

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

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

Search Form 搜索表单 ​

全局配置 ​

业务注入 ​

基础用法 ​

操作按钮 ​

自定义按钮 ​

导入导出2.1.0 ​

权限校验 ​

动态表单 ​

自定义表单项 ​

属性&事件&插槽透传 ​

属性 ​

SearchFormField ​

fieldType值对应渲染组件 ​

SearchFormButton ​

事件 ​