Skip to content

GridTable ( Grid 表格 )

使用 CSS Grid 实现的表格组件

演示

基础用法

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

固定表头

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

固定列

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

堆叠固定列

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

合并单元格

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

虚拟列表

通过 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
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-
renderMode渲染模式
 - 具体可查看 GridTableProps
'auto' | 'modern' | 'legacy''auto'

Expose

方法名描述类型
expandAllRows展开所有行() => void
collapseAllRows折叠所有行() => void
expandRows展开指定行(rowKeys: string[]) => void
collapseRows折叠指定行(rowKeys: string[]) => void

Slots

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

类型定义

GridTableProps

ts

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}`;

  /**
   * 树形数据子节点字段名
   * @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;

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

GridTableColumn

ts

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'>) => number | `${number}` | undefined;
  /**
   * 单元格行合并
   *  - 返回需要合并的行数, 2 代表将当前单元格与下方的一个单元格合并, 以此类推
   *  - 返回 <= 1 或 undefined 则不进行合并
   */
  rowSpan?: (props: Omit<RenderProps<Item>, 'value'>) => 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>;
  index: number;
}

Released under the MIT License.