Data Table 数据表格

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

全局配置

在全局配置组件属性。

DataTable组件属性配置

app.provide(DATA_TABLE_KEY, {
  showButtonCount: 3,
  border: false,
  stripe: true,
  // others props...
});

业务注入

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

权限校验业务注入

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

注入处理文件地址业务

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

注入处理缩略图地址业务

app.provide(HANDLE_THUMB_URLS_KEY, urls => {
  return (
    urls?.split(',')?.map(url => {
      const fileSuffix = url.split('.').pop();
      return `${import.meta.env.VITE_FILE_URL}/ruralLivingEnv/fileControll/downLoadFile?swfName=${url.replace(
        '.' + fileSuffix,
        '_thumb.' + fileSuffix,
      )}`;
    }) ?? []
  );
});

基础用法

组件内部默认开启了show-overflow-tooltip属性，当分配的宽度不足以单行显示时，会自动省略多余内容，并在鼠标悬停时显示tooltip。表格内图片默认开启了懒加载功能，只有滚动到对应位置才会加载图片。表格内图片和悬停预览默认展示缩略图，点击全屏预览会加载原图进行展示。

操作按钮

表格内部封装了详情、编辑、删除三个常用按钮，默认fixed在表单最右侧，监听相应事件后自动渲染，默认不渲染。

自定义按钮

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

权限校验

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

格式化内容

通过传入formatter属性可以对表格项的内容进行格式化处理。

加密表格列2.1.0

组件提供了加密表格项对数据进行加密展示，通过传入解密逻辑可以实现表格项的解密查看功能。

提示

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

特殊表格列

为了更方便的在表格中使用标签、按钮、开关等组件，组件内部对这些组件的部分属性进行了重写和扩展。

标签列

对ElTag的type属性进行了重写。

按钮列

扩展了name属性并对ElButton的type属性和click事件进行了重写。

开关列

对ElSwitch的beforeChange属性和onChange事件进行了重写。

自定义表格列

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

属性&事件&插槽透传

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

属性

属性名	说明	类型	默认值
data	表格数据	`T[]`	[]
fields	表格字段配置项集合	`DataTableFields<T>`	[]
buttons	右侧操作列按钮	`DataTableButtons<T>`	[]
show-button-count	右侧操作列按钮的个数	`number`	3

DataTableField

属性名	说明	类型	默认值
prop	字段名称	`string`	—
fieldType	表格列字段类型	`TableColumnFieldType`	—
authority	权限标识	`string` / `string[]`	—

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

fieldType值对应渲染组件

字段类型	说明	对应的渲染组件
`text`	文本	—
`ciphertext`2.1.0	加密文本	LivVerify
`button`	按钮	ElButton
`switch`	开关	ElSwitch
`tag`	标签	ElTag
`image`	图片	ElImage
`qrcode`	二维码	LivQrCode
`slot`	插槽	—

DataTableButton

属性名	说明	类型	默认值
name	按钮名称	`string`	—
authority	按钮权限	`string` / `string[]`	—
order	按钮顺序	`number`	—
show	是否显示按钮	`boolean` / `Function`	true
onClick	按钮点击事件	`Function`	—

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

事件

事件名	说明	类型
detail	点击详情按钮时触发	`Function`
edit	点击编辑按钮时触发	`Function`
delete	点击删除按钮时触发	`Function`

类型声明

import type { MaybeRef } from 'vue';
import type { ComponentExposed } from 'vue-component-type-helpers';
import type {
  TableProps as ElTableProps,
  ButtonProps as ElButtonProps,
  ImageProps as ElImageProps,
  SwitchProps as ElSwitchProps,
  TableColumnCtx as ElTableColumnCtx,
  TagProps as ElTagProps,
} from 'element-plus';
import type { QrCodeProps } from '../../qr-code';
import DataTable from './data-table.vue';
import { Writable } from 'element-plus/es/utils';
import { VerifyProps, VerifyResult } from '../../verify';

/**
 * 表格组件属性
 * @template T 表格的数据类型
 */
export interface DataTableProps<T = Record<string | number | symbol, any>> {
  /**
   * 表格数据
   * @template T 表格的数据类型
   */
  data?: T[];
  /**
   * 表格字段配置项集合
   * @template T 表格的数据类型
   */
  fields: DataTableFields<T>;
  /**
   * 右侧操作列按钮
   * @template T 表格的数据类型
   * @defaultValue []
   */
  buttons?: DataTableButtons<T>;
  /**
   * 右侧操作列展示按钮的个数
   * @remarks 超过的按钮会隐藏并显示展开图标
   * @defaultValue 3
   */
  showButtonCount?: number;
  /**
   * 右侧操作栏详情按钮点击事件
   * @remarks 传入该属性后会自动渲染详情按钮
   * @template T 表格的数据类型
   * @param row 行数据
   * @param index 数据索引
   */
  onDetail?: (row: T, index: number) => void;
  /**
   * 右侧操作栏编辑按钮点击事件
   * @remarks 传入该属性后会自动渲染编辑按钮
   * @template T 表格的数据类型
   * @param row 行数据
   * @param index 数据索引
   */
  onEdit?: (row: T, index: number) => void;
  /**
   * 右侧操作栏删除按钮点击事件
   * @remarks 传入该属性后会自动渲染删除按钮
   * @template T 表格的数据类型
   * @param row 行数据
   * @param index 数据索引
   */
  onDelete?: (row: T, index: number) => void;
}

/**
 * 数据表格组件实例
 * @template T 表格的数据类型
 */
export type DataTableInstance<
  T extends Record<string | number | symbol, any> = Record<string | number | symbol, any>,
> = ComponentExposed<typeof DataTable<T>>;

/**
 * 表格列字段类型
 */
export type TableColumnFieldType =
  | 'text'
  | 'ciphertext'
  | 'button'
  | 'switch'
  | 'tag'
  | 'image'
  | 'qrcode'
  | 'slot';

/**
 * 表格字段配置项
 * @template T 表格的数据类型
 */
export type DataTableField<T = Record<string | number | symbol, any>> =
  | TextTableColumnField<T>
  | CiphertextTableColumnField<T>
  | ButtonTableColumnField<T>
  | SwitchTableColumnField<T>
  | TagTableColumnField<T>
  | ImageTableColumnField<T>
  | QRCodeTableColumnField<T>
  | SlotTableColumnField<T>;

/**
 * 表格字段配置项集合
 * @template T 表格的数据类型
 */
export type DataTableFields<T = Record<string | number | symbol, any>> = MaybeRef<
  DataTableField<T>
>[];

/**
 * 表格右侧列操作按钮
 * @template T 表格的数据类型
 */
export interface DataTableButton<T = Record<string | number | symbol, any>>
  extends Partial<ElButtonProps> {
  /**
   * 按钮名称
   */
  name?: string;
  /**
   * 是否显示按钮
   * @template T 表格的数据类型
   * @param row 行数据
   * @param index 数据索引
   */
  show?: boolean | ((row: T, index: number) => boolean);
  /**
   * 按钮权限
   */
  authority?: string | string[];
  /**
   * 展示顺序
   * @remarks 组件内置的详情、编辑、删除按钮order分别为10、20、30，如果想要让自定义按钮显示在详情和编辑按钮之间，order可以设置为10~20之间，如果不设置order则默认展示在内置按钮后面。
   */
  order?: number;
  /**
   * 按钮点击事件
   * @template T 表格的数据类型
   * @param row 行数据
   * @param index 数据索引
   */
  onClick?: (row: T, index: number) => void;
}

/**
 * 表格右侧列操作按钮集合
 * @template T 表格的数据类型
 */
export type DataTableButtons<T = Record<string | number | symbol, any>> = DataTableButton<T>[];

/**
 * 表格插槽作用域数据
 * @template T 表格的数据类型
 */
export type DataTableScope<T = Record<string | number | symbol, any>> = {
  /**
   * 当前行的索引
   */
  $index: number;
  /**
   * 当前行数据
   */
  row: T;
  /**
   * 当前列的上下文
   * @template T 表格的数据类型
   */
  column: ElTableColumnCtx<T>;
};

/**
 * 表格列基类
 * @template T 表格的数据类型
 */
interface TableColumnField<T> extends Partial<Omit<ElTableColumnCtx<T>, 'prop'>> {
  /**
   * 字段名称，对应列内容的字段名
   */
  prop: string;
  /**
   * 表格列类型
   */
  type?: 'default' | 'selection' | 'index' | 'expand';
  /**
   * 表格列字段类型
   */
  fieldType?: TableColumnFieldType;
  /**
   * 权限标识
   */
  authority?: string | string[];
}

/**
 * 文本表格列
 * @template T 表格的数据类型
 */
export type TextTableColumnField<T> = Omit<Omit<TableColumnField<T>, 'fieldType'>, 'prop'> & {
  /**
   * 表格列类型为selection、index、expand时，允许不设置prop属性
   */
  prop?: string;
  /**
   * 文本字段
   */
  fieldType?: 'text';
};

/**
 * 加密文本表格列
 * @template T 表格的数据类型
 */
export type CiphertextTableColumnField<T> = Omit<Omit<TableColumnField<T>, 'fieldType'>, 'type'> &
  VerifyProps & {
    /**
     * @remarks 加密文本类型
     */
    fieldType?: 'ciphertext';
    /**
     * 解密方法
     * @param params 验证成功后返回的参数
     * @param row 行数据
     * @returns 解密后的文本
     */
    decrypt: (params: VerifyResult, row: T) => string | Promise<string>;
  };

/**
 * 按钮类型
 */
type ButtonType = 'success' | 'warning' | 'info' | 'primary' | 'danger';

/**
 * 按钮表格列
 * @template T 表格的数据类型
 */
export type ButtonTableColumnField<T> = Omit<
  Omit<TableColumnField<T>, 'fieldType'> & Partial<Writable<ElButtonProps>>,
  'type'
> & {
  /**
   * @remarks 按钮类型，内部实现为[el-button](https://element-plus.org/zh-CN/component/button.html)组件，可以透传[el-button的所有属性](https://element-plus.org/zh-CN/component/button.html#button-%E5%B1%9E%E6%80%A7)。
   */
  fieldType: 'button';
  /**
   * 按钮名称
   */
  name?: string;
  /**
   * 按钮的类型
   * @template T 表格的数据类型
   * @param row 行数据
   * @param index 数据索引
   * @param cellValue 列数据
   * @returns { ButtonType } 按钮的类型
   */
  type?: ButtonType | ((row: T, index: number, cellValue: T[keyof T]) => ButtonType);
  /**
   * 按钮点击的回调函数
   * @template T 表格的数据类型
   * @param row 行数据
   * @param index 数据索引
   * @param cellValue 列数据
   * @returns { void | Promise<any> } 如果返回`Promise`则会自动给按钮加上`loading`状态，并在执行完成后移除loading状态
   */
  onClick?: (row: T, index: number, cellValue: T[keyof T]) => void | Promise<any>;
};

/**
 * 开关表格列
 * @template T 表格的数据类型
 */
export type SwitchTableColumnField<T> = Omit<TableColumnField<T>, 'fieldType'> &
  Partial<Writable<Omit<ElSwitchProps, 'onChange' | 'beforeChange'>>> & {
    /**
     * @remarks 开关类型
     */
    fieldType: 'switch';
    /**
     * 开关状态切换后的回调函数
     * @template T 表格的数据类型
     * @param value 开关绑定值
     * @param row 行数据
     * @param index 数据索引
     * @param cellValue 列数据
     */
    onChange?: (
      value: string | number | boolean,
      row: T,
      index: number,
      cellValue: T[keyof T],
    ) => void;
    /**
     * 开关状态切换前的回调函数
     * @template T 表格的数据类型
     * @param row 行数据
     * @param index 数据索引
     * @param cellValue 列数据
     * @returns { boolean | Promise<any> } 返回`false`或者返回`Promise`且被`reject`则停止切换
     */
    beforeChange?: (row: T, index: number, cellValue: T[keyof T]) => boolean | Promise<any>;
  };

/**
 * 标签类型
 */
type TagType = 'success' | 'warning' | 'info' | 'primary' | 'danger';

/**
 * 标签表格列
 * @template T 表格的数据类型
 */
export type TagTableColumnField<T> = Omit<
  Omit<TableColumnField<T>, 'fieldType'> & Partial<Writable<ElTagProps>>,
  'type'
> & {
  /**
   * @remarks 标签类型
   */
  fieldType: 'tag';
  /**
   * 标签的类型
   * @template T 表格的数据类型
   * @param row 行数据
   * @param index 数据索引
   * @param cellValue 列数据
   * @returns { TagType } 标签的类型
   */
  type?: TagType | ((row: T, index: number, cellValue: T[keyof T]) => TagType);
};

/**
 * 图片表格列
 * @template T 表格的数据类型
 */
export type ImageTableColumnField<T> = Omit<TableColumnField<T>, 'fieldType'> &
  Partial<Writable<ElImageProps>> & {
    /**
     * @remarks 图片类型
     */
    fieldType: 'image';
  };

/**
 * 二维码表格列
 * @template T 表格的数据类型
 */
export type QRCodeTableColumnField<T> = Omit<TableColumnField<T>, 'fieldType'> &
  Partial<QrCodeProps> & {
    /**
     * @remarks 二维码类型
     */
    fieldType: 'qrcode';
  };

/**
 * 插槽表格列
 * @template T 表格的数据类型
 */
export type SlotTableColumnField<T> = Omit<TableColumnField<T>, 'fieldType'> & {
  /**
   * @remarks 插槽类型
   */
  fieldType: 'slot';
};

/**
 * 数据表格组件包含透传属性在内的全部属性
 * @template T 表格的数据类型
 */
export type DataTableFullProps<T> = Partial<ElTableProps<T> & DataTableProps<T>>;

Data Table 数据表格 ​

全局配置 ​

业务注入 ​

基础用法 ​

操作按钮 ​

自定义按钮 ​

权限校验 ​

格式化内容 ​

加密表格列2.1.0 ​

特殊表格列 ​

标签列 ​

按钮列 ​

开关列 ​

自定义表格列 ​

属性&事件&插槽透传 ​

属性 ​

DataTableField ​

fieldType值对应渲染组件 ​

DataTableButton ​

事件 ​