表格组件示例

演示 src/common/components/table 下的完整表格体系：DataTable、表头、单元格、分页与空状态。

功能完整的 DataTable

搜索、批量操作、行选择、排序、过滤、列显隐、可编辑单元格与分页，全部集成在一张表里。

ID	姓名	邮箱	状态	金额	币种	年龄	创建时间
1	Alice	alice@example.com	可用	$1,280.50	USD	28	2023-11-15 06:13:20
2	Bob	bob@example.com	可用	€640.00	EUR	35	2023-11-15 06:13:22
3	Carol	carol@example.com	不可用	$3,200.00	USD	42	2023-11-15 06:13:24
4	David	david@example.com	可用	CN¥900.00	CNY	31	2023-11-15 06:13:26
5	Eve	eve@example.com	不可用	¥1,560	JPY	26	2023-11-15 06:13:28

树形表格

使用 TreeCell 展示可展开/收起的分层数据。

		姓名	邮箱	金额	状态
Engineering		Engineering	eng@example.com	$5,000.00	可用
Marketing		Marketing	mkt@example.com	€1,500.00	可用

分页基础组件

独立使用的 Pagination / PaginationContent / PaginationItem / PaginationLink 等构建块。

空数据状态

没有数据时 EmptyRow 展示占位提示。

姓名	邮箱	状态
No results.

表格组件（components/table）使用说明

概述

src/common/components/table/ 基于 @tanstack/react-table + shadcn/ui 封装了一套通用表格体系，核心是 DataTable，配合表头（header/）、单元格（cell/）、分页（pagination/pager）等子组件。

DataTable 通过 useReactTable 开启：排序、过滤、列显隐、行选择、展开（树形）、手动分页（manualPagination: true，数据需由外部按页切好，recordTotal 表示总数）。

DataTable —— 核心表格

import {DataTable} from "@/common/components/table/data-table";

<DataTable<T>
  columns={columns}
  result={result}
  setData={setResult}
  tableName="UserExample"
  primary="id"
  i18n={true}
  initHandler={init}
  deleteHandler={deleteHandler}
  EditComponent={EditPage}
  RowOperationComponents={[]}
  SearchComponent={Search}
  OperationComponent={Operation}
  defaultPager={{pageIndex: 0, pageSize: 10}}
/>

Prop	类型	必填	说明
columns	`ColumnDef<T,string>[]`	是	列定义
result	`Result`	是	数据源；`result.data = { list, recordTotal, dictionary }`
setData	`Dispatch<SetStateAction<Result>>`	是	更新 `result` 的 setState
initHandler	`() => void`	是	重新加载（重置到第一页），行编辑/删除后回调
primary	string	否	主键字段名（`deleteHandler` 取 `original[primary]`）
tableName	string	否	i18n 命名空间，表头用 `useTranslations(tableName)` 翻译
i18n	boolean	否	是否翻译表头（`t.has(column.id)`）与单元格字典（`KVS.<field>.<value>`）
hiddenColumns	`VisibilityState`	否	初始隐藏列
SearchComponent	`ComponentType<TableOperationProps>`	否	搜索栏，需设置 `meta.searchHandler`
OperationComponent	`ComponentType<TableOperationProps>`	否	工具栏（批量操作）
EditComponent	`ComponentType<CellContextProps>`	否	行编辑弹窗内容（由 `PopItem` 包裹在 Dialog 中）
deleteHandler	`(id) => void`	否	行删除回调
RowOperationComponents	`ComponentType<CellContextProps>[]`	否	操作菜单中追加的自定义行操作
parent	`{}`	否	透传自定义上下文（示例用 `parent` 传递控制器）
defaultPager	`PaginationState`	否	默认分页

注意：因为 manualPagination 为 true，result.data.list 必须是当前页的数据；排序/过滤仍为客户端行为，只作用于当前页。

单元格（cell/）

单元格工厂均返回一个「渲染函数组件」，直接赋给列的 cell。

NormalCell(field, width?, handler?) —— 普通文本；若 result.data.dictionary[field] 存在则按字典映射，i18n 时用 KVS.<field>.<value> 翻译。
CheckBoxCell —— 行选择框，配合 CheckboxHeader；通过 TableUtils.getSelectedIds(table) 取已选主键。
CurrencyCell(field, currencyField) —— 用 Intl.NumberFormat 按币种字段格式化金额。
InputCell(field, type, width?) —— 行内编辑；type="checkbox" 渲染勾选框，其余渲染 <Input type=...>，改动直接写回 row.original[field]。
SelectCell(field, i18n?, readOnly?) —— 行内下拉框，字典取自 result.data.dictionary[field]；readOnly 时仅显示文本。
SortableCell(field) —— 数字输入框，onBlur 时按 sort 对当前页重新排序并 setData。
UnixTimestampCell(field, category?) —— 用 dayjs 格式化为 YYYY-MM-DD HH:mm:ss。
TreeCell(field) —— 树形展开按钮 + 缩进，展示 field 值；数据需提供 subRows。
OperationCell（内部）—— 当列的 cell 为字符串 "Actions" 时由 CellRenderer 触发：编辑（EditComponent 弹窗）、删除（deleteHandler）、自定义行操作（RowOperationComponents）。

表头（header/）

PlainTextHeader({columnTitle}) —— 纯文本表头；i18n 时用 t(column.id) 覆盖。
NormalHeader({showFilter, showSort, columnTitle}) —— 内含 ColumnOperation，可加排序按钮与过滤输入框。
CheckboxHeader —— 全选/半选（indeterminate）。
ColumnFilter() —— 列显隐下拉框，列出 getCanHide() 为 true 的列。
EmptyHeader —— 空白表头（常用于树形展开列）。

其它

ColumnOperation({columnTitle, showFilter, showSort, column}) —— 表头内的排序/过滤操作组合。
Pager({table}) —— 分页条，配合 DataTable 使用，翻页时调用 meta.searchHandler。
Pagination 系列 —— 可独立使用的分页原子组件（Pagination/PaginationContent/PaginationItem/PaginationLink/PaginationPrevious/PaginationNext/PaginationFirst/PaginationLast/PaginationEllipsis）。
EmptyRow({columnSize}) —— 无数据占位行，由 DataTable 在无行时自动渲染。
CellRenderer —— 单元格分发器（内部），判断 cell === "Actions" 走操作单元格，否则 flexRender。