astryx-vue

表格

@astryxdesign/core v0.7.1 · Table

Name
Email
Role
Age
Alice Johnsonalice@example.comEngineer30
Bob Smithbob@example.comDesigner25
Charlie Browncharlie@example.comPM35

使用方法 ​

Table（数据表格）用来以行和列的方式整整齐齐地展示结构化数据。只要传入行数据 data 和列配置 columns 就能快速渲染出表格。每一列都要有唯一标识 key、表头文字 header，也可以用 proportional() 或 pixel() 来分配宽度。单元格默认直接显示数据字段的值，需要自定义内容时可以通过 renderCell 渲染徽标、链接或按钮。idKey 用来区分每一行的唯一身份，默认取数据里的 id。

什么时候用：

  • 需要对比多条结构相似的数据（例如订单列表、用户清单、财务账目），或者需要对数据进行排序、筛选、分页和多选时。

什么时候不要用：

  • 数据结构不规则，或者更适合用卡片呈现视觉封面时，请改用网格或卡片列表。
  • 在屏幕极窄的手机端，普通大表格容易被挤压，可以考虑使用精简列表或折叠详情面板。

常用的高级功能可以通过配套的函数插件（plugins）按需开启：

  • useTableSortable：让用户点击表头在升序、降序和恢复默认之间切换。开启 isMultiSortEnabled 后，按住 Shift 键再点表头可以同时按多个列排序。搭配 useTableSortableState 保存排序规则并返回排好序的数据。
  • useTableSelection：在每行最左侧添加复选框，点击可以选中或高亮当前行。搭配 useTableSelectionState 保存选中的行 ID。选中之后把返回的 selectionState 交给 TableSelectionToolbar，就可以对选中项做批量操作；一个都没选中时这条不出现。周围已经用行底色表示别的含义时，把 hasRowHighlight 设为 false，选中行不再铺底色，读屏仍能读到已选中。
  • useTablePagination：在表格底部添加分页器。在传给表格前，用 paginateData 把总数据切出当前页的内容。
  • useTableColumnSettings：让用户自己勾选显示或隐藏哪些列，带有 isAlwaysVisible 的列会固定保留。
  • useTableColumnResize：允许用户拖动表头边缘自由调整列宽，最小宽度为 60px。
  • useTableFiltering：为指定列开启文字模糊搜索或选项精确匹配。搭配 applyTableFilters 过滤出符合条件的行。
  • useTableGroupedRows：把已经排好序的数据按某个分类整理成分组折叠行。
  • useTableTreeState 与 useTableTreeData：支持像文件夹树一样展开或折叠带有层级关系的子行。
  • useTableRowExpansion：允许点击行首箭头在某一行下方展开一整块详情面板。打开 hasRowClickExpansion 后点整行也能展开；点到按钮、链接、可编辑文字或已经选中的文字时不会切换。详情和第一列对齐，不把面板算进斑马纹。
  • useTableStickyColumns：当表格很宽需要横向滚动时，把左侧或右侧的指定列钉住固定不动。
  • useTableRowStatus：在行首显示成功、警告或错误等状态标记圆点，鼠标悬停时还可以看到文字解释。
  • useTableRowIndex：自动为真正的数据行生成连续的序号。

没写宽度的列至少留 60px。写在表格上的 style.minWidth 如果比各列下限的总和还小，表格会抬到这个下限，避免列被压到读不清；写得更大时保留你给的值。表格放得下时，滚轮继续交给外面的页面；横向溢出之后才拦住回弹。

表格的显示风格也很灵活：density 可以调节行高间距（紧凑 compact、适中 balanced 或宽松 spacious）；dividers 控制网格线的样式（仅行线 rows、仅列线 columns、全网格 grid 或无边框 none）；isStriped 开启隔行换色的斑马纹，hasHover 开启鼠标悬停高亮。当 data 为空时，表格会自动显示贴心的缺省提示，也可以通过 empty 插槽换成自己的图文。

如果不需要配置式的驱动，也可以直接使用 TableHeader、TableBody、TableFooter、TableRow、TableHeaderCell 和 TableCell 这些原子组件像写普通 HTML 表格一样自由拼接。

vue
<script setup lang="ts">
import { proportional, Table } from '@astryx-vue/core/Table'

const rows = [
  { id: '1', name: 'Alice Johnson', email: 'alice@example.com' },
]
const columns = [
  { key: 'name', header: 'Name', width: proportional(1) },
  { key: 'email', header: 'Email', width: proportional(2) },
]
</script>

<template>
  <Table :data="rows" :columns="columns" has-hover />
</template>

如果开启了列过滤，状态要用函数（getter）的形式传进去，表格才能敏锐察觉到过滤词的变化：

ts
const { filters, onFilterChange } = useTableFilterState()
const filterPlugin = useTableFiltering(() => ({
  filters: filters.value,
  onFilterChange,
  fields,
}))

rowCount 和 rowIndexStart 用来告诉读屏软件当前这一页数据在全表里的位置。两者只要填了一个，读屏就能准确播报当前行号。分组的表头和展开的详情面板不会占用行号。

建议 ​

建议做法
推荐每一行给一个稳定的 idKey。选择和行身份都靠它。
推荐短的数字列用 pixel()，需要分剩余宽度的文字列用 proportional()。
推荐排序、选择和过滤的状态放在表格外面，把算好的行放进 data。
避免在 renderCell 里排序或分页。单元格只画交给它的那一行。
避免一张表把每个插件都打开。又密又要过滤、拖宽度、还要多选，通常太挤。

解剖

部分说明
表格把表格分区、行和单元格组在一起的语义 table 元素。
滚动区横向滚动的外层。只有列溢出时才进入键盘顺序，并且只在那时限制过度滚动。
表头区有数据驱动的列时生成的列标题区。用插槽组合表格时，由 TableHeader 提供。
列标题单元格标识一列的单元格，可以装着排序或批量选择控件。
排序控件包住可排序列的标签，并改变该列排序方向的按钮。
排序指示符号排序控件里由 Icon 画出的方向符号。
排序优先级多列排序打开时，已排序列上显示的数字。
选择控件选择插件在表头和可选正文行里渲染的 CheckboxInput。
正文区装着数据行或当前空状态的分区。数据驱动模式会自动渲染它。
行重复的 TableRow，把标准表头、正文或表尾行里的单元格组在一起。
单元格TableCell。在标准正文行或表脚行里，装着一个值或使用方提供的内容。
默认空状态数据数组为空时显示的紧凑 EmptyState，除非被替换或关掉。
展开控件前导单元格里的按钮，用来展开或收起一行可展开的行。
展开符号展开控件里由 Icon 画出的方向符号。
展开详情面板展开行下方的详情行和跨列单元格，包着使用方提供的内容。
表脚区用插槽组合表格时，由 TableFooter 提供的可选汇总或合计分区。

示例 ​

Table — 列设置

Name
Email
Role
Department
Status
Alice Johnsonalice@example.comEngineerPlatformActive
Bob Smithbob@example.comDesignerProductActive
Charlie Browncharlie@example.comManagerPlatformAway
Diana Princediana@example.comEngineerInfraActive
Eve Daviseve@example.comAdminOperationsInactive

工具栏里选择要显示的列。可以开关，也可以调整顺序由当前选中项决定。

Table — 弹出过滤

Name
Email
Role
Department
Alicealice@example.comEngineerPlatform
Bobbob@example.comDesignerProduct
Charliecharlie@example.comManagerPlatform
Dianadiana@example.comEngineerInfrastructure
Eveeve@example.comAdminOperations

点表头上的图标，在弹出层里过滤。

Table — 网格分隔

Metric
Q1
Q2
Q3
Q4
Revenue$1.2M$1.4M$1.3M$1.8M
Users12,40014,20015,80018,100
Retention82%85%84%88%
NPS42454851
CSAT4.24.34.54.6

紧凑密度，行和列都有分隔线，适合密集的数字。

Table — 放在卡片里

Team Members

Name
Role
Email
Alice JohnsonEngineeralice@example.com
Bob SmithDesignerbob@example.com
Charlie BrownPMcharlie@example.com
Diana PrinceEngineerdiana@example.com

表格放在卡片里，标题和表格对齐，用来看容器出血。

Table — 行内过滤

Name
Email
Role
Department
Alice Johnsonalice@example.comEngineerPlatform
Bob Smithbob@example.comDesignerProduct
Charlie Browncharlie@example.comManagerPlatform
Diana Princediana@example.comEngineerInfra
Eve Daviseve@example.comAdminOperations

过滤控件直接放在每一列表头下面，输入后立刻生效。

Table — 分页

Name
Email
Role
Alice Johnsonalice@example.comEngineer
Bob Smithbob@example.comDesigner
Charlie Browncharlie@example.comManager
Diana Princediana@example.comAdmin
Eve Daviseve@example.comAnalyst

数据比较多时按页查看。

Table — 可调整列宽

Name
Email
Role
Alice Johnsonalice@example.comEngineer
Bob Smithbob@example.comDesigner
Charlie Browncharlie@example.comPM
Diana Princediana@example.comEngineer
Eve Daviseve@example.comAnalyst

拖表头右缘可以改列宽，松开后记住宽度。

Table — 丰富的单元格

Name
Email
Role
Age
Alice Johnsonalice@example.comEngineer30
Bob Smithbob@example.comDesigner25
Charlie Browncharlie@example.comPM35
Diana Princediana@example.comEngineer28
Eve Daviseve@example.comDesigner32

邮箱是链接，角色是徽标。

Table — 行选择

Name
Email
Role
Alicealice@example.comEngineer
Bobbob@example.comDesigner
Charliecharlie@example.comManager
Dianadiana@example.comEngineer
Eveeve@example.comAdmin

每一行有复选框，表头可以全选。

Table — 可排序列

Alicealice@example.comEngineer32
Bobbob@example.comDesigner28
Charliecharlie@example.comManager45
Dianadiana@example.comEngineer37
Eveeve@example.comAdmin29

点表头在升序和降序之间切换。

Table — 斑马纹

Name
Email
Role
Age
Alice Johnsonalice@example.comEngineer30
Bob Smithbob@example.comDesigner25
Charlie Browncharlie@example.comPM35
Diana Princediana@example.comEngineer28
Eve Daviseve@example.comDesigner32

隔行变色，悬停时再高亮，方便扫读。

Table — 分组和行号

#
Name
Role
Designer (2)
1BobDesigner
2DiegoDesigner
Engineer (2)
3AliceEngineer
4CarolEngineer

按角色分成两段。折叠后表头还在，行号只数真正的数据行。

Table — 树形数据

Name
Owner
Platform
Ada
API
Grace
Design
Noah

子行沿用同样的列。表头可以一次展开，点行也能展开有子节点的那一行。

Table — 展开行

行展开
Order
Customer
Total
1042Northwind$240

Two seats, ships Friday.

1043Contoso$80
1044Fabrikam$560

点行或行首的箭头，在下面展开备注。右键也有同样的操作。

Table — 固定列

Name
Monday
Tuesday
Wednesday
Thursday
Friday
AliceDeskDeskRemoteDeskOff
BobRemoteDeskDeskRemoteDesk
CarolOffRemoteDeskDeskRemote

姓名钉在左边，周五钉在右边。把表格滚到边上时，中间的日期会从固定列下面滑过去。

Table — 行状态

行状态
Service
Detail
PaymentsSettled
InventoryLow stock
MailBounced
NotesNo signal

行首的标记说明这一行是成功、警告、错误，或者只是一个没有信号的圆点。