数据表格 · Table

展示结构化数据，示例涵盖排序、筛选、选择、分组和分页。

安装与前置条件

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

• 数据表格 · 综合展示 1：首先体验这个示例，再查看代码理解组件的组合方式。
• 数据表格 · 交互示例 2：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 数据表格 · 粘性布局 3：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 数据表格 · 交互示例 4：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 数据表格 · 交互示例 5：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 数据表格 · 筛选 6：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 数据表格 · 浮动 7：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 数据表格 · 交互示例 8：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 数据表格 · 分组 9：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 数据表格 · 交互示例 10：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 数据表格 · 筛选 11：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 数据表格 · 交互示例 12：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 数据表格 · 交互示例 13：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 数据表格 · 交互示例 14：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 数据表格 · 交互示例 15：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 数据表格 · 交互示例 16：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 数据表格 · 状态 17：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 数据表格 · 交互示例 18：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 数据表格 · 交互示例 19：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 数据表格 · 交互示例 20：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 数据表格 · 交互示例 21：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

Table

Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.

使用建议

• Use density and divider variants to match the information density and scanning needs of your data.
• Compose rich cell content with Astryx components like Badge, StatusDot, and Avatar via renderCell.
• 避免：Use a table for data without consistent columns. Use a list or card layout for heterogeneous content.
• 避免：Enable every plugin at once. Add only the features your use case requires to keep the interface focused.

主题 API

{
  "targets": [
    {
      "className": "astryx-table"
    },
    {
      "className": "astryx-table-scroll-wrapper"
    },
    {
      "className": "astryx-table-header"
    },
    {
      "className": "astryx-table-body"
    },
    {
      "className": "astryx-table-footer"
    },
    {
      "className": "astryx-table-row"
    },
    {
      "className": "astryx-table-cell",
      "visualProps": [
        "density"
      ]
    },
    {
      "className": "astryx-table-header-cell",
      "visualProps": [
        "density"
      ]
    }
  ]
}

TableHeader

TableBody

TableFooter

TableRow

TableCell

TableHeaderCell

useTableSelection

useTableSelectionState

TableSelectionToolbar

useTableSortable

useTableTreeData

useTableTreeState

useTablePagination

useTableColumnSettings

useTableFiltering

useTableFilterState

组件结构

• Table: Semantic table element that groups the table sections, rows, and cells.
• Scroll region: Outer region that scrolls horizontally, enters the keyboard order, and contains overscroll only while the columns overflow.
• Header section: Column-heading section generated when data-driven columns are present or supplied with TableHeader in children mode.
• Column header cell: Cell that identifies one column and may contain sorting or bulk-selection controls.
• Sort control: Button that wraps a sortable column label and changes that column's sort direction.
• Sort indicator glyph: Directional symbol rendered by Icon inside a Sort control.
• Sort priority: Number shown for a sorted column when multi-column sorting is active.
• Selection control: CheckboxInput rendered in the header and selectable body rows by the selection plugin.
• Body section: Section containing data rows or the current empty state; data-driven mode renders it automatically.
• Row: Repeated TableRow that groups cells in a standard header, body, or footer row.
• Cell: TableCell containing one value or caller-provided content in a standard body or footer row.
• Default empty state: Compact EmptyState shown for an empty data array unless it is replaced or disabled.
• Expansion control: Button in a leading cell that expands or collapses one expandable row.
• Expansion glyph: Directional symbol rendered by Icon inside an Expansion control.
• Expanded detail panel: Detail row and spanning cell rendered below an expanded row around caller-provided content.
• Footer section: Optional summary or totals section supplied with TableFooter in children mode.

Table Body

主题 API

{
  "targets": [
    {
      "className": "astryx-table-body"
    }
  ]
}

Table Cell

Table Footer

主题 API

{
  "targets": [
    {
      "className": "astryx-table-footer"
    }
  ]
}

Table Header

主题 API

{
  "targets": [
    {
      "className": "astryx-table-header"
    }
  ]
}

Table Header Cell

Table Row

Table Selection Toolbar

Pass both outputs of useTableSelectionState to their matching consumers: selectionConfig to useTableSelection and selectionState to TableSelectionToolbar. Render product actions through startContent. Keep fixed or floating placement in the surrounding layout.

使用建议

• Pass selectionState directly from useTableSelectionState so the count and clear action stay synchronized with row selection.
• Provide product actions as startContent instead of encoding them as configuration objects.
• 避免：Inject the toolbar through the Table plugin or its horizontal scroll wrapper.

useTableColumnResize

返回 TablePlugin 的 Hook，为列表头边框添加可拖动的调整手柄。支持指针 + 键盘（WAI-ARIA 窗口分隔符）调整、RTL、每列最小/最大宽度，以及比例列保留（调整相邻列以保持表格全宽）。在释放时提交宽度。

useTableColumnSettings

无头列可见性和排序管理。提供筛选后的列、切换帮助方法和 MultiSelector 选项。

useTableFilterState

表格筛选的受管状态 hook。返回当前筛选映射和 onChange 处理程序。将结果直接传递给 useTableFiltering。

useTableFiltering

表格筛选插件，添加内联列过滤器（弹出式或内联控件）。与 useTableFilterState 配合使用管理状态。

useTableGroupedRows

Hook that groups a flat data array into collapsible section rows. Each distinct groupBy value becomes a full-width section-header row with a chevron toggle, the group label, and a member count; collapsing hides that group's data rows while keeping the header visible. The disclosure state lives on the chevron button, not the native table row. Mirrors useTableTreeState: the consumer owns the collapsedGroups set and the hook returns {data, plugin, idKey}: pass them to Table as data, plugins, and idKey respectively. Grouping runs on the rows you hand it, so with pagination the order is filter, sort, slice, then group: sort by the group key first and the user's keys second, so a section's rows stay contiguous and each page appends to the bottom of the table instead of splicing rows in above the reader. A page that ends on a row count still cuts mid-section, and the heading then counts what has loaded rather than what exists: "6" quietly becoming "10". Where the full result set is in hand, carry the cut forward to the end of the section it lands in: every rendered section is then whole and its count is a total.

useTablePagination

Call useTablePagination with a config object containing page state and callback. Pass the returned plugin to Table via the plugins prop.

useTableRowExpansion

Hook that returns a TablePlugin which expands a full-width detail panel below a row, rendered by the consumer via renderExpanded(item). Adds a leading chevron column and a right-click "Expand/Collapse row" action; the consumer owns the expandedKeys set. The panel spans the row but starts its content at the first column, past the chevron, so detail lines up with the labels above it; the inset follows the table density. Use it for master-detail rows (order details, forms, charts, nested tables). For hierarchical data where child rows reuse the parent columns, use useTableTreeData + useTableTreeState instead.

Master-detail order rows

const [expandedKeys, setExpandedKeys] = useState(new Set());
const expansion = useTableRowExpansion({
  expandedKeys,
  onToggle: key =>
    setExpandedKeys(prev => {
      const next = new Set(prev);
      next.has(key) ? next.delete(key) : next.add(key);
      return next;
    }),
  getRowKey: item => item.id,
  renderExpanded: item => <OrderDetails order={item} />,
});

<Table data={orders} columns={columns} idKey="id" plugins={{expansion}} />;

Migrating from tree rows to the tree plugin

// useTableRowExpansion is now for DETAIL PANELS, not tree rows. If you used
// it to render nested child rows that reuse the parent columns, move to
// useTableTreeData + useTableTreeState.

// BEFORE (tree rows via useTableRowExpansion + useTableRowExpansionState):
const {data, expansionConfig} = useTableRowExpansionState({
  baseData: tree,
  getChildren: item => item.children ?? [],
  getRowKey: item => item.id,
  expandedKeys,
  setExpandedKeys,
});
const expansion = useTableRowExpansion(expansionConfig);
<Table data={data} columns={columns} idKey="id" plugins={{expansion}} />;

// AFTER (tree rows via the tree plugin):
const {visibleData, treeConfig} = useTableTreeState({
  data: tree,                   // nested data
  idKey: 'id',                  // or a function: idKey={item => item.id}
  childrenKey: 'children',      // replaces getChildren
  defaultExpandedIds: ['root'], // or controlled: expandedIds + onExpandedIdsChange
});
const tree = useTableTreeData({
  ...treeConfig,
  hasExpandAllControl: true,    // was isAllExpanded + onToggleExpandAll
  hasRowClickExpansion: true,   // same prop name
});
<Table data={visibleData} columns={columns} idKey="id" plugins={{tree}} />;

useTableRowIndex

Hook that returns a TablePlugin which prepends a right-aligned, monospaced row-number column. Numbering follows the rendered data order (reflecting the current sort / filter / pagination view) and starts at 1 by default. Astryx renderCell receives only the row item, so the plugin takes the rendered data array to derive each ordinal.

useTableRowStatus

Hook that returns a TablePlugin which prepends a narrow column signaling per-row status. Return {status, label} for a semantic success, warning, or error: Table resolves the matching glyph and tone through the active theme. Return {color, icon?, label} for a custom marker: every color is paint-only, an omitted icon renders the stable 8px dot, and an explicit icon renders that caller-selected glyph. Named custom icons keep their released Icon color mapping; raw CSS custom icons inherit the caller's exact paint instead of the previous primary fallback. Existing callers require no source migration. label is required and becomes the accessible image name plus supplemental hover tooltip; return null for no indicator. The column header is visually blank but carries a screen-reader-only localized name ("Row status", i18n key @astryx.table.rowStatus.columnHeader). Memoize getStatus with useCallback for a stable plugin identity.

useTableSelection

返回 TablePlugin 的 Hook，实现带复选框、全选和 aria-selected 的行选择功能。使用 React Context 实现独立的复选框重新渲染。

Accessible per-row checkbox names

const selectionPlugin = useTableSelection({
  getIsItemSelected: item => selectedIds.has(item.id),
  onSelectItem: ({item, isSelected}) => toggle(item.id, isSelected),
  onSelectAll: ({isAllSelected}) => selectAll(isAllSelected),
  getIsAllSelected: () => selectedIds.size === users.length,
  // Screen readers announce "Select Alice", "Select Bob", ...
  // instead of an undifferentiated "Select row" for every checkbox.
  getRowLabel: item => item.name,
});

<Table
  data={users}
  columns={columns}
  idKey="id"
  plugins={{selection: selectionPlugin}}
/>;

Opt out of the checked-row wash

// This table already uses row background to mean "open in the detail
// panel". Turning the selection wash off keeps that meaning unambiguous;
// the checkbox and aria-selected still carry the selection.
const selectionPlugin = useTableSelection({
  getIsItemSelected: item => selectedIds.has(item.id),
  onSelectItem: ({item, isSelected}) => toggle(item.id, isSelected),
  onSelectAll: ({isAllSelected}) => selectAll(isAllSelected),
  getIsAllSelected: () => selectedIds.size === users.length,
  hasRowHighlight: false,
});

useTableSelectionState

State management companion for useTableSelection. Returns selectionConfig for the behaviour plugin plus selectionState for selection-aware UI such as TableSelectionToolbar. Handles disabled/selectable row filtering for select-all automatically: disabled rows are frozen (preserved across select-all/deselect-all), non-selectable rows are excluded.

useTableSortable

Call useTableSortable with a config object containing sort state and callback. Pass the returned plugin to Table via the plugins prop.

useTableStickyColumns

返回 TablePlugin 的 Hook，将一组连续的列固定到表格的起始和/或结束边缘。固定的列具有累积偏移量，并在滚动内容上方显示柔和的、随滚动感知的阴影。空配置 ({}) 是有效的空操作，不固定任何列。

useTableTreeData

Headless tree plugin for Table: renders nested rows with per-level indentation and expand/collapse chevrons in the tree column (the first column by default), and reflects hierarchy on body rows via aria-level and aria-expanded. Composable with the other Table plugins: the canonical plugin order places tree before selection, so the checkbox column lands left of the indented tree column. Feed it the treeConfig from useTableTreeState, or construct the config directly for server-driven or pre-flattened trees. When no row is expandable (flat data), every transform is a pass-through and the table renders identically to one without the plugin. Known limitation: the tree column wraps its cell content, so textOverflow="truncate" tooltips do not apply within the tree column.

File tree with expandable folders

const {visibleData, treeConfig} = useTableTreeState({
  data: files,          // rows may nest under 'children'
  idKey: 'id',
  defaultExpandedIds: ['src'],
});
const tree = useTableTreeData(treeConfig);

<Table data={visibleData} columns={columns} idKey="id" plugins={{tree}} />;

useTableTreeState

State management companion for useTableTreeData. Owns the expanded set (controlled or uncontrolled) and flattens nested data into the visible row array; collapsed subtrees are unmounted, not hidden, so the table body contains exactly the visible rows. Returns expandAll/collapseAll helpers, the aggregate isAllExpanded state (true/false/indeterminate) for a header expand-all control, and a ready-to-use config for the tree plugin. Note: because collapsed rows unmount, cell-local React state inside collapsed subtrees is lost on collapse; lift state that must survive.

示例的 StyleX 编译要求

TableFloatingBulkActionsTable 包含 stylex.create，需要配置 StyleX 源码编译流程。仅引入 Core 预编译 CSS 不足以运行这些示例样式，复制前请阅读样式与 Tailwind。