表格 Table

基本用法

表格的基本用法，需要传递 columns 和 data。

追加内容

通过 append 插槽可以在表格最后一行之后追加自定义内容，适合承载“继续加载”“汇总提示”等辅助区域。

自定义表格元素

可以通过特定插槽自定义表格元素的渲染。仅需要传入表格元素，内部属性会自动附加上去

自定义渲染

通过 #columns 插槽和 <sd-table-column> 组件可以使用模板的方法自定义列渲染。 注意：在使用 #columns 插槽后，将会屏蔽 columns 属性

拖拽锚点

（实验性）开启锚点拖拽功能

可拖拽表格

（实验性）开启表格行可拖拽功能

可编辑表格

可以在使用插槽获得的数据，修改 data 中的数据，达到可编辑表格的功能。 2.25.0 版本后可以直接修改插槽传出的 record 变量。这个 record 变量是传入的 data 中对应数据的引用，请保证 data 为 Reactive 类型。

文本省略和提示

开启 ellipsis 属性可以显示省略号，如果同时开启 tooltip 会在显示省略号时使用文本提示。注意：开启 tooltip 后会修改 table-cell 中的 DOM 结构。

展开行

通过设置 expandable 开启展开行功能。可以在 data 中添加 expand 属性，设置展开行显示内容。

自定义筛选菜单

通过插槽可以自定义筛选菜单内容。

分组表头与固定列

分组表头使用固定列时，需要优先指定数据列为固定列。如果一个分组下的所有数据列都是固定列，此时可以设置分组列为固定列，宽度为子列宽度之和。

固定列

在 columns 中指定 fixed: 'left' 或 fixed: 'right'，可将列固定到左侧或右侧。设置了 fixed 的列必须设置 width 指定列的宽度。 注意：要配合 :scroll="{ x: number }" 使用。此外 columns 中至少需要有一列不设置宽度，自适应，不然会有样式问题。

分组表头

columns 内可以设置 children，用于表头分组。

子树懒加载

通过 load-more 属性可以开启子树懒加载功能。开启子树懒加载功能后，需要在无子树节点标注 isLeaf: true，没有标注且没有 children 属性的节点会认为需要子树懒加载处理。 load-more 属性有提供 done 函数进行回调，可以在回调中传入懒加载的子树。如果 done 函数没有传入数据会认为懒加载失败，此节点可以再次触发懒加载。

表格属性

这里罗列了一些表格的属性，你可以方便的打开或关闭一些属性，查看它的效果。

行选择器（单选框）

通过设置 rowSelection.type='radio' 开启单选模式。

函数型行 Key

row-key 除了传字段名，也可以传函数。在数据主键不叫 key，或者需要基于现有字段计算唯一标识时更直接。下面示例同时演示了它与选择、展开能力的组合使用。

调整列宽

使用 column-resizable 属性开启列宽调整。建议初始设置除最后一列外其他列的默认列宽。

行选择器

通过设置 row-selection 开启行选择器。

表格滚动

设置 scroll 属性可以开启表格滚动。x 指表格的实际宽度，一般设置的值会大于表格容器宽度；y 指表格的显示高度，表格实际高度超出后会显示滚动条。2.18.0 版本后 x, y 均可设置百分比。y 设置为 100% 可以让表格容器高度跟随外层容器，超出后自动显示滚动条。

排序和筛选

通过设置 columns 中的 sortable 和 filterable 属性，可以配置排序和筛选功能。 通过 filter-icon-align-left 属性可以让筛选按钮左对齐。可以通过设置 sortable.sorter=true 来关闭内部排序，并通过 change 或者 sorterChange 事件来实现服务器端排序。

单元格合并

通过 span-method 属性进行单元格合并。可以设置 span-all 让列索引包含操作列，注意：目前如果合并多项选择器会导致全选状态判断错误。

表头吸顶

通过 sticky-header 设置表头吸顶。表头吸顶的计算容器为最近滚动容器，设置数字时可指定距离滚动容器顶部的高度。

树形数据展示

树形数据展示的例子，data 里有 children 字段时会展示为树形表格。

总结行

设置 summary 可以开启表尾总结行，并可以通过 summary-text 指定首列文字。如果想要自定义总结行展示，可以传入函数。函数的返回值为需要展示的数据，结构同 data 一样即可，支持多行数据。注意：控制列暂不可以自定义内容

虚拟列表

设置 virtual-list-props 开启虚拟列表功能。当前 Table 已经接入组件库共享的 VirtualList，推荐优先按下面的思路选择参数：

• 常规表格优先使用 height + estimatedSize
• 所有行高都一致时使用 itemSize
• 行高可能增长、或需要结合展开内容时使用 minItemSize

下面的示例同时演示了 estimatedSize / itemSize / minItemSize、可视区高度、sticky-header、滚动定位和展开行的组合方式。表格虚拟滚动固定使用组件库共享的 Scrollbar。

API

<table> Props

参数名	描述	类型	默认值	版本
columns	表格的列描述信息	TableColumnData[]	[]
data	表格的数据	TableData[]	[]
bordered	是否显示边框	boolean | TableBorder	true
hoverable	是否显示选中效果	boolean	true
stripe	是否开启斑马纹效果	boolean	false
size	表格的大小	'mini' | 'small' | 'medium' | 'large'	'large'
table-layout-fixed	表格的 table-layout 属性设置为 fixed，设置为 fixed 后，表格的宽度不会被内容撑开超出 100%。	boolean	false
loading	是否为加载中状态	boolean|object	false
spin-props	传递给加载中 Spin 的属性，优先于 ConfigProvider 的 table-spin-props	SpinProps	-
row-selection	表格的行选择器配置	TableRowSelection	-
expandable	表格的展开行配置	TableExpandable	-
scroll	表格的滚动属性配置。2.13.0 版本增加字符型值的支持。2.20.0 版本增加 minWidth,maxHeight 的支持。	{ x?: number | string; y?: number | string; minWidth?: number | string; maxHeight?: number | string;}	-
pagination	分页的属性配置	boolean | PaginationProps	true
page-position	分页选择器的位置	'tl' | 'top' | tr' | 'bl' | 'bottom' | 'br'	'br'
indent-size	树形表格的缩进距离	number	16
row-key	表格行 key 的取值字段	string | ((record: TableData) => string | number)	'key'
show-header	是否显示表头	boolean	true
virtual-list-props	传递虚拟列表属性，传入此参数以开启虚拟滚动 VirtualListProps	VirtualListProps	-
span-method	单元格合并方法（索引从数据项开始计数）	(data: { record: TableData; column: TableColumnData | TableOperationColumn; rowIndex: number; columnIndex: number;}) => { rowspan?: number; colspan?: number } | void	-	2.10.0
span-all	是否让合并方法的索引包含所有	boolean	false	2.18.0
load-more	数据懒加载函数，传入时开启懒加载功能	(record: TableData, done: (children?: TableData[]) => void) => void	-	2.13.0
filter-icon-align-left	筛选图标是否左对齐	boolean	false	2.13.0
hide-expand-button-on-empty	是否在子树为空时隐藏展开按钮	boolean	false	2.14.0
row-class	表格行元素的类名。2.34.0 版本增加函数值支持	string| any[]| Record<string, any>| ((record: TableData, rowIndex: number) => any)	-	2.16.0
draggable	表格拖拽排序的配置	TableDraggable	-	2.16.0
column-resizable	是否允许调整列宽	boolean	false	2.16.0
summary	显示表尾总结行	boolean| ((params: { columns: TableColumnData[]; data: TableData[]; }) => TableData[])	-	2.21.0
summary-text	总结行的首列文字	string	'Summary'	2.21.0
summary-span-method	总结行的单元格合并方法	(data: { record: TableData; column: TableColumnData | TableOperationColumn; rowIndex: number; columnIndex: number;}) => { rowspan?: number; colspan?: number } | void	-	2.21.0
selected-keys	已选择的行（受控模式）优先于 rowSelection	(string | number)[]	-	2.25.0
default-selected-keys	默认已选择的行（非受控模式）优先于 rowSelection	(string | number)[]	-	2.25.0
expanded-keys	显示的展开行、子树（受控模式）优先于 expandable	(string | number)[]	-	2.25.0
default-expanded-keys	默认显示的展开行、子树（非受控模式）优先于 expandable	(string | number)[]	-	2.25.0
default-expand-all-rows	是否默认展开所有的行	boolean	false	2.25.0
sticky-header	是否开启表头吸顶	boolean|number	false	2.30.0
scrollbar	是否开启虚拟滚动条	boolean | ScrollbarProps	true	2.38.0
show-empty-tree	是否展示空子树	boolean	false	2.51.0

<table> Events

事件名	描述	参数	版本
expand	点击展开行时触发	rowKey: string | number record: TableData
expanded-change	已展开的数据行发生改变时触发	rowKeys: (string | number)[]
select	点击行选择器时触发	rowKeys: string | number[] rowKey: string | number record: TableData
select-all	点击全选选择器时触发	checked: boolean
selection-change	已选择的数据行发生改变时触发	rowKeys: (string | number)[]
sorter-change	排序规则发生改变时触发	dataIndex: string direction: string
filter-change	过滤选项发生改变时触发	dataIndex: string filteredValues: string[]
page-change	表格分页发生改变时触发	page: number
page-size-change	表格每页数据数量发生改变时触发	pageSize: number
change	表格数据发生变化时触发	data: TableData[] extra: TableChangeExtra currentData: TableData[]	2.40.0 增加 currentData
cell-mouse-enter	单元格 hover 进入时触发	record: TableData column: TableColumnData ev: Event
cell-mouse-leave	单元格 hover 退出时触发	record: TableData column: TableColumnData ev: Event
cell-click	点击单元格时触发	record: TableData column: TableColumnData ev: Event
row-click	点击行数据时触发	record: TableData ev: Event
header-click	点击表头数据时触发	column: TableColumnData ev: Event
column-resize	调整列宽时触发	dataIndex: string width: number	2.28.0
row-dblclick	双击行数据时触发	record: TableData ev: Event
cell-dblclick	双击单元格时触发	record: TableData column: TableColumnData ev: Event
row-contextmenu	右击行数据时触发	record: TableData ev: Event
cell-contextmenu	右击单元格时触发	record: TableData column: TableColumnData ev: Event

<table> Methods

方法名	描述	参数	返回值	版本
selectAll	设置全选状态	checked: boolean	-	2.22.0
select	设置行选择器状态	rowKey: string | number | (string | number)[] checked: boolean	-	2.31.0
expandAll	设置全部展开状态	checked: boolean	-	2.31.0
expand	设置展开状态	rowKey: string | number | (string | number)[] checked: boolean	-	2.31.0
resetFilters	重置列的筛选器	dataIndex: string | string[]	-	2.31.0
clearFilters	清空列的筛选器	dataIndex: string | string[]	-	2.31.0
resetSorters	重置列的排序	-	-	2.31.0
clearSorters	清空列的排序	-	-	2.31.0
scrollIntoView	虚拟滚动到指定行	options: { index?: number; key?: string | number; align?: ScrollIntoViewOptions['align']; }	-

<table> Slots

插槽名	描述	参数	版本
th	自定义 th 元素	column: TableColumnData	2.26.0
thead	自定义 thead 元素	-	2.26.0
empty	空白展示	-
append	插入至表格最后一行之后的内容	-
summary-cell	总结行	column: TableColumnData record: TableData rowIndex: number	2.23.0
pagination-right	分页器右侧内容	-	2.18.0
pagination-left	分页器左侧内容	-	2.18.0
td	自定义 td 元素	column: TableColumnData record: TableData rowIndex: number	2.16.0
tr	自定义 tr 元素	record: TableData rowIndex: number	2.16.0
tbody	自定义 tbody 元素	-	2.16.0
drag-handle-icon	拖拽锚点图标	-	2.16.0
footer	表格底部	-
expand-row	展开行内容	record: TableData
expand-icon	展开行图标	expanded: boolean record: TableData
columns	表格列定义。启用时会屏蔽 columns 属性	-

<table-column> Props

参数名	描述	类型	默认值	版本
data-index	列信息的标识，对应TableData中的数据	string	-
title	列标题	string	-
width	列宽度	number	-
min-width	最小列宽	number	-
align	对齐方向	TableColumnData['align']	-
fixed	固定位置	TableColumnData['fixed']	-
ellipsis	是否显示为省略	boolean	false
sortable	排序相关选项	TableSortable	-
filterable	过滤相关选项	TableFilterable	-
cell-class	自定义单元格类名	ClassName	-	2.36.0
header-cell-class	自定义表头单元格类名	ClassName	-	2.36.0
body-cell-class	自定义内容单元格类名	ClassName | ((record: TableData) => ClassName)	-	2.36.0
summary-cell-class	自定义总结栏单元格类名	ClassName | ((record: TableData) => ClassName)	-	2.36.0
cell-style	自定义单元格样式	CSSProperties	-	2.11.0
header-cell-style	自定义表头单元格样式	CSSProperties	-	2.29.0
body-cell-style	自定义内容单元格样式	CSSProperties | ((record: TableData) => CSSProperties)	-	2.29.0
summary-cell-style	自定义总结栏单元格样式	CSSProperties | ((record: TableData) => CSSProperties)	-	2.30.0
index	用于手动指定选项的 index。2.26.0 版本后不再需要手动指定	number	-	2.20.2
tooltip	在省略时是否显示文字提示	boolean|object	false	2.26.0

<table-column> Slots

插槽名	描述	参数	版本
filter-icon	筛选按钮图标	-	2.23.0
filter-content	自定义筛选弹出框内容	filterValue: string[] setFilterValue: (filterValue: string[]) => void handleFilterConfirm: (event: Event) => void handleFilterReset: (event: Event) => void	2.23.0
title	标题	-
cell	单元格	record: TableData column: TableColumnData rowIndex: number

Type

type Filters = Record<string, string[]>;

type Sorter = { filed: string; direction: 'ascend' | 'descend' } | Record<string, never>;

TableData

参数名	描述	类型	默认值	版本
key	数据行的key	string	-
expand	扩展行内容	string | RenderFunction	-
children	子数据	TableData[]	-
disabled	是否禁用行选择器	boolean	false
isLeaf	是否是叶子节点	boolean	false	2.13.0

TableSortable

参数名	描述	类型	默认值
sortDirections	支持的排序方向	('ascend' | 'descend')[]	-
sorter	排序函数。设置为 true 可关闭内部排序。2.19.0 版本修改传出数据。	(( a: TableData, b: TableData, extra: { dataIndex: string; direction: 'ascend' | 'descend' } ) => number) | boolean	-
sortOrder	排序方向	'ascend' | 'descend' | ''	-
defaultSortOrder	默认排序方向（非受控模式）	'ascend' | 'descend' | ''	-

TableFilterData

参数名	描述	类型	默认值
text	筛选数据选项的内容	string | RenderFunction	-
value	筛选数据选项的值	string	-

TableFilterable

参数名	描述	类型	默认值	版本
filters	筛选数据	TableFilterData[]	-
filter	筛选函数	(filteredValue: string[], record: TableData) => boolean	-
multiple	是否支持多选	boolean	false
filteredValue	筛选项	string[]	-
defaultFilteredValue	默认筛选项	string[]	-
renderContent	筛选框的内容	(data: { filterValue: string[]; setFilterValue: (filterValue: string[]) => void; handleFilterConfirm: (event: Event) => void; handleFilterReset: (event: Event) => void; }) => VNodeChild	-
icon	筛选按钮的图标	RenderFunction	-
triggerProps	筛选框的弹出框配置	TriggerProps	-
alignLeft	筛选图标是否左对齐	boolean	false	2.13.0

TableColumnData

参数名	描述	类型	默认值	版本
dataIndex	列信息的标识，对应 TableData 中的数据	string	-
title	列标题	string | RenderFunction	-
width	列宽度	number	-
minWidth	最小列宽	number	-
align	对齐方向	'left' | 'center' | 'right'	-
fixed	固定位置	'left' | 'right'	-
ellipsis	是否显示省略号	boolean	false
tooltip	是否在显示省略号时显示文本提示。可填入 tooltip 组件属性	boolean | Record<string, any>	-	2.26.0
sortable	排序相关选项	TableSortable	-
filterable	过滤相关选项	TableFilterable	-
children	表头子数据，用于表头分组	TableColumnData[]	-
cellClass	自定义单元格类名	ClassName	-	2.36.0
headerCellClass	自定义表头单元格类名	ClassName	-	2.36.0
bodyCellClass	自定义内容单元格类名	ClassName | ((record: TableData) => ClassName)	-	2.36.0
summaryCellClass	自定义总结栏单元格类名	ClassName | ((record: TableData) => ClassName)	-	2.36.0
cellStyle	自定义单元格样式	CSSProperties	-	2.11.0
headerCellStyle	自定义表头单元格样式	CSSProperties	-	2.29.0
bodyCellStyle	自定义内容单元格样式	CSSProperties | ((record: TableData) => CSSProperties)	-	2.29.0
summaryCellStyle	自定义总结栏单元格样式	CSSProperties | ((record: TableData) => CSSProperties)	-	2.30.0
render	自定义列单元格的渲染	(data: { record: TableData; column: TableColumnData; rowIndex: number; }) => VNodeChild	-
slotName	设置当前列的渲染插槽的名字。插槽参数同 #cell	string	-	2.18.0
titleSlotName	设置当前列的标题的渲染插槽的名字	string	-	2.23.0

TableBorder

参数名	描述	类型	默认值
wrapper	是否展示外边框	boolean	false
cell	是否展示单元格边框（表头+主体）	boolean	false
headerCell	是否展示表头单元格边框	boolean	false
bodyCell	是否展示主体单元格边框	boolean	false

TableRowSelection

参数名	描述	类型	默认值	版本
type	行选择器的类型	'checkbox' | 'radio'	-
selectedRowKeys	已选择的行（受控模式）	BaseType[]	-
defaultSelectedRowKeys	默认已选择的行（非受控模式）	BaseType[]	-
showCheckedAll	是否显示全选选择器	boolean	false
title	列标题	string	-
width	列宽度	number	-
fixed	是否固定	boolean	false
checkStrictly	是否开启严格选择模式	boolean	true	2.29.0
onlyCurrent	是否仅展示当前页的 keys（切换分页时清空 keys）	boolean	false	2.32.0

TableExpandable

参数名	描述	类型	默认值
expandedRowKeys	显示的展开行（受控模式）	BaseType[]	-
defaultExpandedRowKeys	默认显示的展开行（非受控模式）	BaseType[]	-
defaultExpandAllRows	是否默认展开所有的行	boolean	false
expandedRowRender	自定义展开行内容	(record: TableData) => VNodeChild	-
icon	展开图标	(expanded: boolean, record: TableData) => VNodeChild	-
title	列标题	string	-
width	列宽度	number	-
fixed	是否固定	boolean	false

TableDraggable

参数名	描述	类型	默认值
type	拖拽类型	'row' | 'handle'	-
title	列标题	string	-
width	列宽度	number	-
fixed	是否固定	boolean	false

TableChangeExtra

参数名	描述	类型	默认值
type	触发类型	'pagination' | 'sorter' | 'filter' | 'drag'	-
page	页码	number	-
pageSize	每页数据数	number	-
sorter	排序信息	Sorter	-
filters	筛选信息	Filters	-
dragTarget	拖拽信息	TableData	-

VirtualListProps

参数名	描述	类型	默认值	版本
height	可视区域高度	number | string	-
itemSize	固定高度模式的行高。所有行高度一致时优先使用它。	number	-
minItemSize	动态高度模式的最小行高。存在展开内容或更长文本时优先使用它。	number	-
estimatedSize	估算行高。未显式传 itemSize 时，通常和 minItemSize 一起使用，帮助初始定位更平滑。	number	-
buffer	额外渲染缓冲区，语义与底层 scroller 一致。	number	200
keyField	用于提取每行唯一键，默认跟随表格行 key。	string | ((item, index) => string | number)	'key'

FAQ

1. 关于元素插槽的使用

table 组件提供了内部元素的自定义插槽，这些插槽不同于普通插槽，对用户传入的内容有一定限制。因为 vue 的插槽没有提供传出 children 并在 slot 中渲染的方式，我们针对 table 中的元素插槽，做了一些特殊处理，会在用户传入的内容中，附加上原有的 children，保证子元素的正常渲染。此时需要用户注意，在元素插槽中自定义渲染时，需要传入单一空元素使用，不能在传入的元素中添加内容（参考例 1）。如果用户需要传入复合元素，可以自定义组件，并指定 default 插槽，然后传入 table 的元素插槽中（参考例 2）。

例 1：

<template>
  <sd-table>
    <template #td>
      <td @click="onClick"></td>
    </template>
  </sd-table>
</template>

例 2：

<template>
  <sd-table>
    <template #td>
      <MyTd></MyTd>
    </template>
  </sd-table>
</template>

<template>
  <td>
    <div>my td content</div>
    <div>
      <slot />
    </div>
  </td>
</template>

2. 关于数据中的 row-key 设置

表格默认会通过数据中设置的 key 字段来唯一定位行数据，在提供数据时请确保行数据中都设置了 key 字段。这个字段在开启选择器等功能时为必要字段，如果想要更换默认的字段名，可以修改 row-key 进行设置。