组件/DataTable 数据表格

DataTable 数据表格

语义单元格、列筛选、排序、选择与展开的数据表格

Verified自 0.3.4

用法

基础

语义 type 提供数值排序、标签展示与本地日历日期;列级 filter: true 增加对应的表头筛选器。

Loading demo...

排序

数字与日期列自动可排序,其他列用 sortable 开启;defaultSort 设初始排序,sortCycle 决定第三次点击是否取消。

Loading demo...

筛选

filter: true 按列类型给出文本搜索、标签多选、数值区间或日期预设;filter-<key> 插槽换成自定义面板,v-model:filter 让父级持有筛选状态。

Loading demo...

行选择

selectable 增加选择列,v-model:selected-keys 同步选中行。

Loading demo...

行展开

expandable 增加前置展开列,#expanded 插槽渲染行下方的详情。

Loading demo...

列宽自适应

未声明宽度的不换行列贴合内容,其余列分走剩余宽度;操作列默认固定在右侧,放不下时横向滚动。

Loading demo...

加载状态

loadingVariant 选择遮罩、骨架或光带;骨架与光带只在没有行时画占位行,刷新时保留已有的行。

Loading demo...

空状态

#empty 插槽替换无行时的空状态,可以放说明和操作;只改文案时传 emptyText。

Loading demo...

记录表

宽表版式:吸顶表头、吸底汇总、固定首列、选中高亮,单元格组合 TxTag、TxDotIndicator、TxCellLink。

Loading demo...

数据运维面板

TxPagination 负责翻页,TxSkeleton / TxLayoutSkeleton 承接加载预览。

Loading demo...

最佳实践

  • 业务列表传稳定的 rowKey,跨页保留选择时用业务 id 驱动 selectedKeys;数据量大时由宿主分页后再传入,表格不虚拟化。
  • 服务端加载的列表用 loadingVariant="skeleton" 或 "shimmer",并把 skeletonRows 设为每页条数;本地短暂等待用默认的 overlay。
  • 列宽交给内容:不换行的列不声明宽度,长文本列给 minWidth 作下限;同一侧固定多列时给数值 width,横向滚动只保留一层(scrollX 或外包 overflow-x: auto)。
  • 吸顶、吸底需要 maxHeight 或滚动祖先,且不要放进默认模式的 TxScroll;排序用时间戳等可比较字段,date 列按本地日历日解析 YYYY-MM-DD。
  • 远程筛选设置 filterOnClient=false 并处理 filterChange;筛选与选择框的文案默认是英文,用 labels、selectAllLabel 与 selectRowLabelFormatter 本地化。

API 参考

属性

属性名类型默认值说明
columnsDataTableColumn[][]列配置。
dataany[][]数据源。
rowKeykeyof T | (row: T, index: number) => string | numberindex行唯一标识。
loadingbooleanfalse加载状态。
loadingVariant'overlay' | 'skeleton' | 'shimmer''overlay'overlay 盖遮罩与转圈;skeleton 画骨架行,已有行时只显示进度条;shimmer 让光带逐行扫过占位行或已有的行。
skeletonRowsnumber5skeleton 与 shimmer 在首批数据到达前的占位行数;设为每页条数,到达时不跳动。高度由宿主决定时,占位行补到表格底部。
emptyTextstring'No data'空数据提示。
stripedbooleanfalse斑马纹。
borderedbooleanfalse表格边框。
hoverbooleantrue悬浮高亮。
interactiveRowsbooleanfalse整行可聚焦,Enter / Space 触发 rowClick;监听 rowClick 时自动开启。
selectablebooleanfalse增加选择列。
selectedKeysArray<string | number>[]选中行的 key。
selectAllLabelstring'Select all'表头全选框的可访问名称。
selectRowLabelstring'Select row'所有行选择框共用的可访问名称。
selectRowLabelFormatter(row, index) => string-为每行的选择框单独命名,读屏时能分清是哪一行;优先于 selectRowLabel。
expandablebooleanfalse增加前置展开列,展开行下方渲染详情行。
defaultExpandedKeysArray<string | number>[]非受控的初始展开行;与 expandedKeys 同传时后者优先。
expandedKeysArray<string | number>-受控展开行,配合 v-model:expanded-keys。
rowExpandable(row, index) => boolean-按行决定能否展开;不可展开的行保留空的前置单元格。
expandLabelstring'Expand row'收起时展开按钮的可访问名称。
collapseLabelstring'Collapse row'展开时展开按钮的可访问名称。
defaultSort{ key: string; order: 'asc' | 'desc' | null }null非受控的初始排序;与 sort 二选一。
sort{ key: string; order: 'asc' | 'desc' | null } | null-受控排序,null 表示未排序。
sortOnClientbooleantrue本地排序;远程排序时设为 false,只派发事件。
sortCycle'tri' | 'bi''tri'tri:升序→降序→取消;bi:升序与降序交替,不取消。
tableLayout'auto' | 'fixed''auto'原生 table-layout;列宽需稳定时用 fixed。
nowrapbooleanfalse表头与单元格都不换行。
maxHeightstring | number-限制高度,表格自身纵向滚动;吸顶、吸底的参照。
scrollXbooleanfalse在组件内横向滚动;宽表配固定列时使用。
stickyHeaderbooleanfalse表头吸顶。
stickyFooterbooleanfalse汇总行吸底。
rowClass(row, index) => string | string[] | Record<string, boolean>-按行追加 class,如按状态给整行上色。
highlightSelectedbooleanfalse给选中行加底色。
defaultFilterDataTableFilterState{}非受控模式的初始列筛选值。
filterDataTableFilterState-按列 key 的受控筛选值,可绑定 v-model:filter。
filterOnClientbooleantrue默认本地筛选;false 时由调用方获取匹配行。
autoStickyActionsbooleantrue默认将操作列固定到右侧;列上显式 fixed 优先。
labelsPartial<DataTableLabels>-筛选控件的文案;只传要替换的键,其余保持英文默认值。

事件

事件名参数说明
update:selectedKeys(keys)选中变化。
selectionChange(keys)选中变化。
update:expandedKeys(keys)展开变化;受控与非受控都触发。
expand({ row, index, expanded })某行展开或收起。
sortChange(sort)排序变化。
update:sort(sort)排序变化;受控与非受控都触发。
update:filter(filter)筛选值变化,受控与非受控模式均触发。
filterChange(filter)本地或远程筛选变化。
rowClick({ row, index })行点击。

插槽

名称说明
header-<columnKey>自定义表头;接收 { column, sorted, order, toggle },toggle 按排序循环推进该列。
cell-<columnKey>自定义单元格;接收 { row, column, value, index }。
filter-<columnKey>自定义筛选面板,接收 { column, filterValue, setFilter, clearFilter, close };close 关闭面板。
expanded展开详情,横跨全部列;接收 { row, index }。
footer整行汇总,自行提供可跨列的 <td>;有任一 footer 插槽才渲染 <tfoot>。
footer-<columnKey>按列填充汇总单元格;接收 { column, data },与 footer 同在时以 footer 为准。
empty无行且 loading=false 时的空状态。

DataTableColumn

字段类型说明
keystring列 key。
titlestring表头文本。
type'text' | 'number' | 'datetime' | 'date' | 'tag' | 'source' | 'actions'语义展示、排序与筛选;单元格插槽和 format 优先。
dataIndexstring数据字段名。
widthstring | number列宽;不声明时,不换行的列贴合内容,其余列分走剩余宽度。
minWidthstring | number列最小宽度。
maxWidthstring | number列最大宽度。
autoboolean强制列宽为 auto。
fixedboolean | 'left' | 'right'固定方向,true 即 'left';偏移按实际列宽测量,左侧已计入展开列与选择列。
nowrapboolean当前列不换行。
align'left' | 'center' | 'right'对齐方式。
sortableboolean可排序。
sorter(a, b) => number自定义排序器。
filterboolean增加匹配类型的表头筛选器,默认关闭。
filterOptionsDataTableFilterOption[]自定义标签筛选选项,含 label、value,可选 tone 与 count(选项旁显示的行数)。
format(value, row, index) => string默认文本格式化。
headerClassstring表头 class。
cellClassstring单元格 class。

DataTableLabels

键默认值说明
filter'Filter {column}'筛选按钮的可访问名称,{column} 替换为列标题。
filterAll'All'清除标签筛选的选项。
filterAnyTime'Any time'清除日期筛选的选项。
filterToday'Today'日期预设:今天。
filterLast3Days'Last 3 days'日期预设:近 3 天。
filterLast7Days'Last 7 days'日期预设:近 7 天。
filterLast30Days'Last 30 days'日期预设:近 30 天。
filterSearch'Search'文本筛选与长标签列表搜索框的占位文本。
filterMin'Min'数值区间下限。
filterMax'Max'数值区间上限。
filterReset'Reset'清空数值区间。
filterApply'Done'关闭数值区间面板。

概述

  • sort、expandedKeys 一经传入(含 null、[])即受控:组件只派发更新事件,渲染父级回传的值。
  • filter 一经传入也为受控。标签可传单值或多值数组,数值使用 { min, max },日期使用 today、3d、7d、30d 或时间戳 { start, end };文本列按不区分大小写的包含关系匹配。
  • 标签筛选的选项来自数据时,本地筛选会给每项标出行数;选项达到 8 个时面板顶部出现搜索框。
  • 可排序表头带 scope="col" 与 aria-sort,点击、Enter、Space 按 sortCycle 循环。
  • 全选框以 selectAllLabel 命名,行选择框以 selectRowLabelFormatter 命名,未传时用 selectRowLabel。部分选中时全选框为 indeterminate(aria-checked="mixed");选择与展开单元格的点击不触发 rowClick。
  • loading 在 <table> 上设置 aria-busy,加载期间不显示空状态;overlay 只盖住表格的可见区域,没有行时表格保持空状态的高度。
  • 占位行 aria-hidden,与单行文本行等高;减少动态效果时,刷新进度条静止,光带改为静止的浅色底。
  • 开启 stickyHeader、stickyFooter 或 maxHeight 时改用 border-collapse: separate;末行不画下边框,tfoot 上方的分隔线保留。

技术实现

  • 骨架变体渲染 TxSkeleton:按需样式插件会一并加载;手动引入样式时另引 @talex-touch/tuffex/skeleton/style.css。
  • 语义默认值、筛选和排序共用内部 useDataTableData;列宽、固定列偏移、遮罩高度与光带位置由内部 useDataTableLayout 测量。
  • 标签与日期筛选使用 TxDropdownMenu / TxDropdownItem,数值与文本筛选使用 TxPopover;面板 Teleport 后仍由组件的 BEM 样式控制。
  • 源码:packages/tuffex/packages/components/src/data-table/。
查看源码
packages/tuffex/packages/components/src/data-table/index.ts

自定义

CSS 变量用途
--tx-data-table-row-hover-bg行悬停底色。
--tx-data-table-row-selected-bghighlightSelected 的选中行底色。
.records-shell {
  --tx-data-table-row-hover-bg: var(--tx-bui-hover);
  --tx-data-table-row-selected-bg: color-mix(in srgb, var(--tx-bui-accent) 7%, var(--tx-bui-surface));
}