Table 表格

用于展示结构化二维数据,可以快速实对数据进行排序、搜索、分组、编辑、分页、汇总等操作。

代码示例#

API#

预设类型#

Table 组件的类型定义非常之多,如果你想充分了解它们之间的关系,建议从 源码 入手。

ts
type Key = string | number | symbol
type Data = any
type TableIconName = 'filter' | 'asc' | 'desc' | 'dragger' | 'expand' | 'plus' | 'minus'
type TableRowPropFn<P = any> = (data: Data, index: number) => P
type TableRowDropType = 'before' | 'after' | 'none'
type TableTextAlign = 'left' | 'center' | 'right'
type TableColumnType = 'order' | 'selection' | 'expand' | 'drag'
type TableColResizeType = 'lazy' | 'responsive'

type TableIcons = Partial<Record<TableIconName, Record<string, any> | (() => any)>>

interface CellSpanResult {
  colSpan?: number,
  rowSpan?: number
}

interface TableKeyConfig {
  id?: string,
  children?: string,
  checked?: string,
  height?: string,
  expanded?: string,
  treeExpanded?: string
}

type Accessor<D = Data, Val extends string | number = string | number> = (
  data: D,
  index: number
) => Val
type ExpandRenderFn<D = Data> = (data: {
  /** @deprecated */
  leftFixed: number,
  /** @deprecated */
  rightFixed: number,
  row: D,
  rowIndex: number
}) => any
type ColumnCellSpanFn<D = Data> = (data: {
  row: D,
  index: number,
  fixed?: 'left' | 'right'
}) => CellSpanResult | undefined
type SummaryCellSpanFn<D = Data, Val extends string | number = string | number> = (data: {
  column: TableColumnOptions<D, Val>,
  index: number,
  fixed?: 'left' | 'right'
}) => CellSpanResult | undefined

type TableFilterOptions<D = Data, Val extends string | number = string | number> =
  | {
    able?: boolean,
    custom?: false,
    options?: (string | { value: Val, label?: string, active?: boolean })[],
    multiple?: false,
    active?: null | Val,
    method?: null | ((active: Val, data: D) => boolean),
    meta?: any
  }
  | {
    able?: boolean,
    custom?: false,
    options?: (string | { value: Val, label?: string, active?: boolean })[],
    multiple: true,
    active?: null | Val[],
    method?: null | ((active: Val[], data: D) => boolean),
    meta?: any
  }
  | {
    able?: boolean,
    custom: true,
    options?: never,
    multiple?: false,
    active?: null | Val | Val[],
    method?: null | ((active: any, data: D) => boolean),
    meta?: any
  }

interface TableSorterOptions<D = Data> {
  able?: boolean,
  type?: null | 'asc' | 'desc',
  order?: number,
  method?: null | ((prev: D, next: D) => number)
}

interface TableSummaryData {
  sum: number,
  min: number,
  max: number
}

type SummaryRenderFn<D = Data, Val extends string | number = string | number> = (data: {
  column: TableColumnOptions<D, Val>,
  index: number,
  rows: D[],
  meta: TableSummaryData
}) => any

type ColumnSummaryRenderFn<
  D = Data,
  Val extends string | number = string | number
> = (data: {
  column: TableColumnOptions<D, Val>,
  index: number,
  rows: D[],
  meta: TableSummaryData,
  summary: TableSummaryOptions<D, Val>
}) => any

interface TableBaseColumn<D = Data, Val extends string | number = string | number> {
  name: string,
  key: keyof D,
  type?: never,
  meta?: any,
  fixed?: boolean | 'left' | 'right',
  class?: ClassType,
  style?: StyleType,
  attrs?: Record<string, any>,
  width?: number,
  filter?: TableFilterOptions<D, Val>,
  sorter?: boolean | TableSorterOptions<D>,
  order?: number,
  /** @deprecated */
  noEllipsis?: boolean,
  ellipsis?: boolean,
  textAlign?: TableTextAlign,
  headSpan?: number,
  noSummary?: boolean,
  accessor?: Accessor<D, Val>,
  formatter?: (value: Val) => unknown,
  cellSpan?: ColumnCellSpanFn<D>,
  renderer?: ColumnRenderFn<D, Val>,
  headRenderer?: HeadRenderFn,
  filterRenderer?: FilterRenderFn,
  summaryRenderer?: ColumnSummaryRenderFn<D, Val>
}

interface TableOrderColumn<D = Data, Val extends string | number = string | number>
  extends Omit<TableBaseColumn<D, Val>, 'type' | 'renderer'> {
  type: 'order',
  truthIndex?: boolean,
  orderLabel?: (index: number) => string | number
}

interface TableSelectionColumn<D = Data, Val extends string | number = string | number>
  extends Omit<TableBaseColumn<D, Val>, 'type' | 'renderer' | 'headRenderer'> {
  type: 'selection',
  checkboxSize?: ComponentSize,
  disableRow?: (data: Data) => boolean
}

interface TableExpandColumn<D = Data, Val extends string | number = string | number>
  extends Omit<TableBaseColumn<D, Val>, 'type' | 'renderer'> {
  type: 'expand',
  disableRow?: (data: Data) => boolean,
  renderer?: ExpandRenderFn<D>
}

interface TableDragColumn<D = Data, Val extends string | number = string | number>
  extends Omit<TableBaseColumn<D, Val>, 'type' | 'renderer'> {
  type: 'drag',
  disableRow?: (data: Data) => boolean
}

type TableTypeColumn<D = Data, Val extends string | number = string | number> =
  | TableOrderColumn<D, Val>
  | TableSelectionColumn<D, Val>
  | TableExpandColumn<D, Val>
  | TableDragColumn<D, Val>
type TableColumnOptions<D = Data, Val extends string | number = string | number> =
  | TableBaseColumn<D, Val>
  | TableTypeColumn<D, Val>

type ColumnWithKey<
  D = Data,
  Val extends string | number = string | number
> = TableColumnOptions<D, Val> & { key: Key, rowSpan: number }

interface TableColumnGroupOptions {
  name?: string,
  fixed?: boolean | 'left' | 'right',
  order?: number,
  ellipsis?: boolean,
  textAlign?: TableTextAlign,
  renderer?: () => any,
  children: TableColumnOptions<any, any>[]
}

type TableColumnRawOptions = TableColumnOptions<any, any> | TableColumnGroupOptions

type ColumnRenderFn<D = Data, Val extends string | number = string | number> = (data: {
  row: D,
  rowIndex: number,
  column: TableBaseColumn<D, Val>,
  columnIndex: number
}) => any
type HeadRenderFn<D = Data, Val extends string | number = string | number> = (data: {
  column: TableColumnOptions<D, Val>,
  index: number
}) => any
type FilterRenderFn<D = Data, Val extends string | number = string | number> = (data: {
  column: TableColumnOptions<D, Val>,
  index: number,
  filter: Required<TableFilterOptions<D, Val>>,
  handleFilter: (active: any) => void
}) => any

type TableCellSpanFn<D = Data, Val extends string | number = string | number> = (data: {
  row: D,
  rowIndex: number,
  column: TableColumnOptions<D, Val>,
  columnIndex: number,
  fixed?: 'left' | 'right'
}) => CellSpanResult | undefined

type TableCellPropFn<D = Data, P = any> = (data: {
  row: D,
  rowIndex: number,
  column: ColumnWithKey,
  columnIndex: number
}) => P
type TableHeadPropFn<P = any> = (data: { column: ColumnWithKey, index: number }) => P
type TableFootPropFn<P = any> = (data: {
  column: ColumnWithKey,
  columnIndex: number,
  summary: SummaryWithKey,
  summaryIndex: number
}) => P

type ColumnProfile<D = Data, Val extends string | number = string | number> = Pick<
  ColumnWithKey<D, Val>,
  'name' | 'key' | 'meta'
>
type TableFilterProfile<
  D = Data,
  Val extends string | number = string | number
> = ColumnProfile<D, Val> & {
  active: Val | Val[]
}
type TableSorterProfile<
  D = Data,
  Val extends string | number = string | number
> = ColumnProfile<D, Val> & {
  type: 'asc' | 'desc',
  order: number
}

interface TableSummaryOptions<D = Data, Val extends string | number = string | number> {
  name: string,
  key: keyof D,
  class?: ClassType,
  style?: StyleType,
  attrs?: Record<string, any>,
  order?: number,
  above?: boolean,
  cellSpan?: SummaryCellSpanFn<D, Val>,
  renderer?: SummaryRenderFn<D, Val>
}

type SummaryWithKey<
  D = Data,
  Val extends string | number = string | number
> = TableSummaryOptions<D, Val> & { key: Key }

interface TableRowPayload {
  row: Data,
  key: Key,
  index: number,
  event: Event,
  checked?: boolean,
  expanded?: boolean
}

interface TableCellPayload {
  row: Data,
  key: Key,
  rowIndex: number,
  column: TableColumnOptions,
  columnIndex: number,
  event: Event
}

interface TableHeadPayload {
  column: TableColumnOptions,
  index: number,
  event: Event
}

interface TableColResizePayload extends TableHeadPayload {
  width: number
}

interface TableFootPayload {
  column: TableColumnOptions,
  columnIndex: number,
  summary: TableSummaryOptions,
  summaryIndex: number,
  event: Event
}

Table 属性#

名称类型说明默认值始于
bar-fadenumber设置滚动条的渐隐时间,若小于 300 则关闭渐隐效果1500-
borderboolean设置表格是否具有外边框和纵向边框false-
border-widthnumber设置表格的边框宽度12.2.12
cell-attrsRecord<string, any> | TableCellPropFn<Record<string, any>>单元格的自定义属性null2.0.1
cell-classClassType | TableCellPropFn<ClassType>单元格的自定义类名null2.0.1
cell-spanTableCellSpanFn设置单元格跨度的回调函数null2.1.24
cell-styleStyleType | TableCellPropFn<StyleType>单元格的自定义样式null2.0.1
col-resizableboolean | TableColResizeType设置表格列的宽度是否可以调整,设置为 true 时等同于 'lazy'false2.1.23
columnsTableColumnRawOptions[]表格列的配置,参考下方的 TableColumn 属性[]-
current-pagenumber设置表格当前显示的数据页1-
custom-filterboolean设置是否为自定义过滤,开启后仅派发事件而不会进行内部过滤false2.1.4
custom-sorterboolean设置是否为自定义排序,开启后仅派发事件而不会进行内部排序false2.1.4
dataData[]表格的数据源[]-
data-filter(data: Data) => boolean设置额外的数据过滤方法null2.2.14
disabled-treeboolean设置是否禁用自动解析树形数据false2.1.6
ellipsisboolean是否为单元格内容使用省略组件false2.2.16
empty-textstring设置表格空数据时的提示语locale.empty-
expand-rendererExpandRenderFn设置行拓展内容的渲染方法null-
foot-attrsRecord<string, any> | TableFootPropFn<Record<string, any>>表尾单元格的自定义属性null2.1.24
foot-classClassType | TableFootPropFn<ClassType>表尾单元格的自定义类名null2.1.24
foot-styleStyleType | TableFootPropFn<StyleType>表尾单元格的自定义样式null2.1.24
head-attrsRecord<string, any> | TableHeadPropFn<Record<string, any>>表头单元格的自定义属性null2.0.1
head-classClassType | TableHeadPropFn<ClassType>表头单元格的自定义类名null2.0.1
head-styleStyleType | TableHeadPropFn<StyleType>表头单元格的自定义样式null2.0.1
heightnumber表格的高度,超出这个高度时会变成可滚动状态null-
highlightboolean设置表格行是否在鼠标移入时高亮false-
iconsTableIcons用于设置表格的各种图标{}2.1.28
key-configTableKeyConfig设置数据解析 data 时的各项键名{}2.1.6
localeLocaleConfig['table']设置多语言配置null2.1.0
min-heightnumber表格的最小高度,不应大于 heightnull2.3.7
no-cascadedboolean在树形表格中使父子节点能被独立勾选false2.1.6
no-transitionboolean是否禁用表格的过渡效果false2.2.14
page-sizenumber设置表格每页的数据量,当为 0 时则禁用分页0-
render-countnumber设置表格的最大渲染行数,通常用于大量数据渲染,需设置固定行高null-
row-attrsRecord<string, any> | TableRowPropFn<Record<string, any>>行的自定义属性null2.0.1
row-classClassType | TableRowPropFn<ClassType>行的自定义类名null-
row-draggableboolean设置表格行是否可以拖拽排序false-
row-heightnumber设置表格的行高,未设置时表格行高将会动态计算null-
row-indentstring | number设置树形表格每一级的缩进距离'16px'2.1.6
row-styleStyleType | TableRowPropFn<StyleType>行的自定义样式null2.0.1
scroll-classScrollClass设置表格各滚动组件的自定义类型{}-
scroll-delta-ynumber设置表格纵向每次滚动的距离20-
side-paddingnumber | number[]设置表格两侧的内边距02.1.28
single-filterboolean设置后将限制表格只能有一列开启过滤false-
single-sorterboolean设置后将限制表格只能有一列开启排序false-
stripeboolean设置表格是否应用斑马纹false-
summariesTableSummaryOptions<any, any>[]表格总结行的配置,参考下方 TableSummary 属性[]2.1.24
transparentboolean设置是否为透明表格,该属性优先级低于其他内置样式属性false-
use-x-barboolean设置表格是否使用横向滚动条false2.1.25
use-y-barboolean设置表格是否使用纵向滚动条false-
virtualboolean是否开启虚拟滚动false-
widthnumber表格的宽度,在有固定列时使用null-

Table 事件#

名称说明参数始于
cell-click当点击了单元格时触发(payload: TableCellPayload)2.0.1
cell-contextmenu当右击了单元格时触发(payload: TableCellPayload)2.0.1
cell-dblclick当双击了单元格时触发(payload: TableCellPayload)2.0.1
cell-enter当鼠标移入了单元格时触发(payload: TableCellPayload)2.0.1
cell-leave当鼠标移出了单元格时触发(payload: TableCellPayload)2.0.1
col-resize-end当列结束调整宽度时触发(payload: TableColResizePayload)2.1.23
col-resize-move当列正在调整宽度时触发(payload: TableColResizePayload)2.1.23
col-resize-start当列要开始调整宽度时触发(payload: TableColResizePayload)2.1.23
foot-click当点击了尾部单元格时触发(payload: TableFootPayload)2.1.24
foot-contextmenu当右击了尾部单元格时触发(payload: TableFootPayload)2.1.24
foot-dblclick当双击了尾部单元格时触发(payload: TableFootPayload)2.1.24
foot-enter当鼠标移入了尾部单元格时触发(payload: TableFootPayload)2.1.24
foot-leave当鼠标移出了尾部单元格时触发(payload: TableFootPayload)2.1.24
head-click当点击了头部单元格时触发(payload: TableHeadPayload)2.0.1
head-contextmenu当右击了头部单元格时触发(payload: TableHeadPayload)2.0.1
head-dblclick当双击了头部单元格时触发(payload: TableHeadPayload)2.0.1
head-enter当鼠标移入了头部单元格时触发(payload: TableHeadPayload)2.0.1
head-leave当鼠标移出了头部单元格时触发(payload: TableHeadPayload)2.0.1
row-check当勾选了行复选框时触发(payload: TableRowPayload)-
row-check-all当进行了全选时触发(checked: boolean, partial: boolean)-
row-click当点击了行时触发(payload: TableRowPayload)-
row-contextmenu当右击了行时触发(payload: TableRowPayload)2.0.1
row-dblclick当双击了行时触发(payload: TableRowPayload)2.0.1
row-drag-end当行结束拖拽时触发(data: Record<string, unknown>, allData: Record<string, unknown>[], event: DragEvent)-
row-drag-over当行正在拖拽时触发(data: Record<string, unknown>, event: DragEvent)-
row-drag-start当行将要开始拖拽时触发(data: Record<string, unknown>, event: DragEvent)-
row-drop当行被其他的拖拽行放入时触发(data: Record<string, unknown>, dropType?: 'before' | 'after', event: DragEvent)-
row-enter当鼠标移入了行时触发(payload: TableRowPayload)-
row-expand当行拓展内容的展开状态改变时触发(payload: TableRowPayload)-
row-filter当发生表格数据过滤时触发(profiles: TableFilterProfile[], filteredRow: Data[])-
row-leave当鼠标移出了行时触发(payload: TableRowPayload)-
row-sort当发生表格数据排序时触发(profiles: SortProfile[], sortedRow: Data[])-
row-tree-expand当行的树展开状态改变时触发(payload: TableRowPayload)2.3.1
scroll当表格滚动时触发(scroll: { type: 'horizontal' | 'vertical', client: number, percent: number })2.1.25
update:data当行结束拖拽并且数据结构发生变化时触发(data: Data[])2.2.18

Table 插槽#

名称说明参数始于
default用于定义 TableColumn 和 TableSummary 组件--
empty空数据提示内容的插槽{ isFixed: boolean }-
icon-[name]表格图标的插槽,其中 [name] 的可选值请参考 TableIconName-2.1.28

Table 方法#

名称说明签名始于
clearFilter清除当前表格激活的所有过滤() => void-
clearSelected清除所有被勾选的行数据() => void-
clearSort清除表格当前激活的所有排序() => void-
getData获取表格的数据,通常用于获取拖拽后的数据() => Data[]2.2.6
getSelected获取所有被勾选的行数据() => Data[]-
refresh刷新表格,将会触发表格的重新布局及数据渲染() => Promise<void>-
refreshData刷新表格数据,会触发表格重新解析数据(data?: any[]) => Promise<void>2.2.14
selectRow手动勾选或取消勾选行数据(keyOrData: Key | Record<any, any>, checked?: boolean): void2.3.1
treeExpandRow手动展开或收起行数据(keyOrData: Key | Record<any, any>, checked?: boolean): void2.3.1

TableColumn 属性#

名称类型说明默认值始于
accessor(data: any, rowIndex: number) => any该列的数据读取方法null-
attrsRecord<string, any>该列单元格的自定义属性null2.0.1
cell-spanColumnCellSpanFn<any>设置单元格跨度的回调函数null2.1.24
checkbox-size'small' | 'default' | 'large'type'selection' 时设置复选框大小'default'-
classClassType该列单元格的自定义类名null2.1.19
disable-row(data: Data) => boolean设置禁用行的回调函数null-
ellipsisboolean是否为单元格内容使用省略组件false2.2.12
filterTableFilterOptions<any, any>列的过滤配置器null-
filter-rendererFilterRenderFn自定义过滤器渲染函数null2.1.18
fixedboolean | 'left' | 'right'是否为固定列,可选值为 leftright,设置为 true 时固定在左侧false-
formatter(value: any) => unknown设置单元格内容的格式化方法null2.2.13
head-rendererHeadRenderFn自定义头部渲染函数null-
head-spannumber设置头部跨度12.1.24
indentedboolean指定为树形表格的缩进列false2.2.6
key | id-keystring | number列的唯一索引,使用模版列时请使用 id-key 代替null-
metaany设置列的元数据null2.1.24
namestring列的名称''-
no-summaryboolean是否禁用自动计算列值的总结数据false2.1.24
ordernumber列的渲染顺序0-
order-label(index: number) => string | numbertype'order' 时设置索引显示内容的回调函数null-
rendererColumnRenderFn自定义渲染函数,若 type'expand' 时则为 ExpandRenderFnnull-
sorterboolean | TableSorterOptions<any>列的排序排序器null-
styleStyleType该列单元格的自定义样式null2.0.1
summary-rendererColumnSummaryRenderFn自定义尾部渲染函数null2.1.24
text-alignTableTextAlign设置列的横向对其方式'left'2.1.19
truth-indexbooleantype'order' 时设置是否使用行真实(全局)索引false-
typeTableColumnType设置内置特定类型列null-
widthnumber设置列宽null-

TableColumn 插槽#

名称说明参数始于
default列内容的插槽Parameters<ColumnRenderFn>-
filter列过滤器的插槽Parameters<FilterRenderFn>2.1.18
head列头内容的插槽Parameters<HeadRenderFn>-
summary列尾内容的插槽Parameters<ColumnSummaryRenderFn>2.1.24

TableColumnGroup 属性#

名称类型说明默认值始于
ellipsisboolean是否为表头单元格内容使用省略组件false-
fixedboolean | 'left' | 'right'是否为固定列分组,可选值为 leftright,设置为 true 时固定在左侧false-
namestring列分组的名称''-
ordernumber列分组的渲染顺序,与列的 order 属性共同作用,每一层级、每个分组之间的排序均是独立的0-
renderer() => any自定义头部渲染函数null-
text-alignTableTextAlign设置表头单元格的横向对其方式'center'-

TableColumnGroup 插槽#

名称说明参数始于
default用于定义 TableColumn 组件--
head列头内容的插槽--

TableSummary 属性#

名称类型说明默认值始于
aboveboolean设置总结行是否在表格上部false-
attrsRecord<string, any>该行单元格的自定义属性null-
cell-spanSummaryCellSpanFn设置单元格跨度的回调函数null-
classClassType该行单元格的自定义类名null-
key | id-keystring | number总结行的唯一索引,使用模版列时请使用 id-key 代替null-
metaany设置总结行的元数据null-
namestring总结行的名称''-
ordernumber总结行的渲染顺序0-
rendererSummaryRenderFn自定义渲染函数null-
styleStyleType该行单元格的自定义样式null-

TableSummary 插槽#

名称说明参数始于
default总结行内容的插槽Parameters<SummaryRenderFn>-

TableSorter 属性#

名称类型说明默认值始于
ableboolean设置是否可以排序false-
method(prev: any, next: any) => number自定义排序的方法,分别接收前后行数据null-
ordernumber在多列排序时用于规定各列的先后顺序0-
type'asc' | 'desc'排序的类型null-

TableFilter 属性#

名称类型说明默认值始于
ableboolean设置是否可以过滤false-
activeany当前过滤的依赖值,会传入过滤方法null-
customboolean是否为自定义过滤,配合 TableColumn 的 filter 插槽使用false2.1.18
metaany自定义元数据undefined2.1.18
method(active: any | any[], data: any) => boolean过滤的方法,接收过滤的依赖值和行数据null-
multipleboolean是否开启多条件过滤false-
options(string | { value: any, label?: string, active?: boolean })[]过滤的选项,元素为 { label, value } 的对象[]-