GridTable ( Grid 表格 )

使用 CSS Grid 实现的表格组件

演示

基础用法

简单的表格, 最后一列是各种操作

固定表头

方便一页内展示大量数据, 只要给表格设置一个高度即可

固定列

对于列数很多的数据, 可以固定前后的列, 横向滚动查看其它数据

堆叠固定列

混合固定列，滚动到一定距离进行堆叠

合并单元格

通过 rowSpan 和 colSpan 实现单元格的行列合并, 需要在列配置中进行配置

警告

启用虚拟列表时暂不支持此功能

虚拟列表

通过 virtual 开启虚拟滚动

树形数据

表格支持树形数据的展示, 当数据中有 children 字段时会自动展示为树形表格, 如果不需要或配置为其他字段可以用 expandColumnKey 进行配置。

API

Props

参数名	描述	类型	默认值
rowKey	表格行主键	string | (() => string)	'id'
data	数据源	Record<string, any>[]	-
columns	列配置	GridTableColumn[]	-
loading	是否加载中	boolean	-
virtual	是否启用虚拟列表  - 需要为表格设置一个高度	boolean	-
overscan	启用虚拟列表时预渲染的行数  - 可减少快速滚动时的白屏	number | `${number}`	5
estimatedRowHeight	启用虚拟列表时的预估行高度	number | `${number}`	50
fixedRowHeight v3.6.0	启用虚拟列表时的固定行高度  - 设置后, 将不再动态计算行高, 提升渲染性能, 和 estimatedRowHeight 互斥  - 设置后, 将移除单元格上下内边距	number | `${number}`	-
childrenKey	树形数据子节点字段名	string	'children'
expandColumnKey	显示展开按钮的列主键  - 如果不设置, 则使用第一列作为展开列	string	-
expandedRowKeys	树形数据展开的行主键列表  - 支持通过 v-model:expandedRowKeys="xxx" 进行双向绑定	string[]	-
expandedIndent	展示树形数据时, 每层缩进的宽度, 以 px 为单位	number | `${number}`	15
cellClass	单元格样式类 ( th/td )	string	-
headerCellClass	表头单元格样式类 ( th )	string	-
contentCellClass	表体单元格样式类 ( td )	string	-
bordered	是否展示外边框和列边框	boolean	-
headerDivider	是否展示未启用 bordered 时的表头分割线	boolean	true
hover	鼠标悬浮时的高亮模式	'row' | false	'row'
renderMode	渲染模式  - 具体可查看 GridTableProps	'auto' | 'modern' | 'legacy'	'auto'

Expose

方法名/属性名	描述	类型
tableWrapSize	表格包裹层宽高	{ width: number; height: number }
tableSize	表格主体宽高	{ width: number; height: number }
expandAllRows	展开所有行	() => void
collapseAllRows	折叠所有行	() => void
expandRows	展开指定行	(rowKeys: string[]) => void
collapseRows	折叠指定行	(rowKeys: string[]) => void

Slots

名称	描述
header	通用表头单元格插槽
header-${field}	指定字段表头单元格插槽
cell	通用字段单元格插槽
cell-${field}	指定字段单元格插槽

类型定义

GridTableProps

export interface GridTableProps<Fields extends Record<string, any>> {
  /**
   * 表格行主键
   * @default 'id'
   */
  rowKey?: MaybeRefOrGetter<string>;

  /** 数据源 */
  data?: any[];
  /** 表格列配置 */
  columns?: GridTableColumn<Fields>[];

  /** 是否加载中 */
  loading?: boolean;

  /**
   * 是否启用虚拟列表
   *  - 需要为表格设置一个高度
   */
  virtual?: boolean;
  /**
   * 启用虚拟列表时预渲染的行数
   *  - 可减少快速滚动时的白屏
   * @default 5
   */
  overscan?: number | `${number}`;
  /**
   * 启用虚拟列表时的预估行高度
   * @default 50
   */
  estimatedRowHeight?: number | `${number}`;
  /**
   * 启用虚拟列表时的固定行高度
   *  - 设置后, 将不再动态计算行高, 提升渲染性能, 和 `estimatedRowHeight` 互斥
   *  - 设置后, 将移除单元格上下内边距
   * @version 3.5.2
   */
  fixedRowHeight?: number | `${number}`;

  /**
   * 树形数据子节点字段名
   * @default 'children'
   */
  childrenKey?: keyof Fields | 'children' | (string & {});
  /**
   * 显示展开按钮的列主键
   *  - 如果不设置, 则使用第一列作为展开列
   */
  expandColumnKey?: keyof Fields | (string & {});
  /**
   * 树形数据展开的行主键列表
   *  - 支持通过 v-model:expandedRowKeys="xxx" 进行双向绑定
   */
  expandedRowKeys?: string[];
  /**
   * 展示树形数据时, 每层缩进的宽度, 以 px 为单位
   * @default 15
   */
  expandedIndent?: number | `${number}`;

  /** 单元格样式类 ( th/td ) */
  cellClass?: string;
  /** 表头单元格样式类 ( th ) */
  headerCellClass?: string;
  /** 表体单元格样式类 ( td ) */
  contentCellClass?: string;

  /** 是否展示外边框和列边框 */
  bordered?: boolean;
  /**
   * 是否展示未启用 `bordered` 时的表头分割线
   * @default true
   */
  headerDivider?: boolean;

  /**
   * 鼠标悬浮时的高亮模式
   *  - 'row': 高亮当前行
   *  - false: 禁用高亮
   * @default 'row'
   */
  hover?: 'row' | false;

  /**
   * 渲染模式
   *  - `auto`: 自动检测浏览器, 自动切换为 `modern` 或 `legacy` 模式
   *  - `modern`: 强制使用现代渲染模式 ( 如 CSS Subgrid ), 在不支持的浏览器可能出现布局异常
   *  - `legacy`: 强制使用传统渲染模式 ( 不依赖 `modern` 模式的现代特性 )
   * @default 'auto'
   */
  renderMode?: 'auto' | 'modern' | 'legacy';
}

GridTableColumn

export interface GridTableColumn<
  Fields extends Record<string, any>,
  Item extends Record<string, any> = Fields & Record<string, any>,
> {
  /** 字段名 */
  field: keyof Fields | (string & {});
  /** 表头名称 */
  title?: string | ((props: ColumnProps<Item>) => string);

  /** 表头自定义渲染方法 */
  headerRender?: (props: RenderHeaderProps<Item>) => any;

  /** 单元格自定义渲染方法 */
  render?: (props: RenderProps<Item>) => any;

  /** 列宽度 */
  width?: string | number | `${number}` | ((props: ColumnProps<Item>) => string | number | `${number}`);

  /**
   * 列的对齐方式
   * @default 'left'
   */
  align?: 'left' | 'center' | 'right';

  /** 列固定 */
  fixed?: boolean | 'left' | 'right';

  /** 单元格样式类 ( th/td ) */
  cellClass?: string;
  /** 表头单元格样式类 ( th ) */
  headerCellClass?: string;
  /** 表体单元格样式类 ( td ) */
  contentCellClass?: string;

  /** 显示列 */
  visible?: boolean | ((props: ColumnProps<Item>) => boolean);
  /** 隐藏列 */
  hidden?: boolean | ((props: ColumnProps<Item>) => boolean);

  /**
   * 单元格列合并
   *  - 返回需要合并的列数, 2 代表将当前单元格与右侧的一个单元格合并, 以此类推
   *  - 返回 <= 1 或 undefined 则不进行合并
   *  - 启用虚拟列表时暂不支持此功能
   */
  colSpan?: (props: Omit<RenderProps<Item>, 'value' | 'columnIndex'>) => number | `${number}` | undefined;
  /**
   * 单元格行合并
   *  - 返回需要合并的行数, 2 代表将当前单元格与下方的一个单元格合并, 以此类推
   *  - 返回 <= 1 或 undefined 则不进行合并
   *  - 启用虚拟列表时暂不支持此功能
   */
  rowSpan?: (props: Omit<RenderProps<Item>, 'value' | 'columnIndex'>) => number | `${number}` | undefined;
}

export interface ColumnProps<Fields extends Record<string, any>> {
  column: GridTableColumn<Fields>;
}

export interface RenderHeaderProps<Fields extends Record<string, any>> {
  column: GridTableColumn<Fields>;
  /** 表头名称 */
  title?: string;
}

export interface RenderProps<Fields extends Record<string, any>> {
  value: any;
  record: Fields;
  column: GridTableColumn<Fields>;
  columnIndex: number;
  index: number;
}