@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/data-table/meta.md

@@ -0,0 +1,107 @@
+# DataTable
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+数据表格 DataTable
+高阶数据表 — 基于 [@tanstack/react-table](https://tanstack.com/table) 的配置式表格，组合
+Table primitives + Pagination 实现 排序 / 过滤 / 分页 / 行选择 / 行展开 / 自定义渲染 等核心交互。
+主题与视觉对齐本仓 tokens；API 命名采用业界主流（columns / data / accessorKey / header / cell / enableSorting…），
+同时保留对 antd / cloud-design 旧字段的向后兼容（dataSource / dataIndex / title / sortable / render / fixed / width）。
+
+## 使用场景
+
+- 需要排序、筛选等交互的数据列表
+- 批量操作场景（多选行 + 操作按钮）
+- 大量数据的分页展示
+- 表格行需要可展开补充信息时
+- 组合结构：DataTable（columns + data）— 内部组合 Table + TableHeader/Body/Row/Cell + Pagination + Popover Filter
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `columns` | `DataTableColumn<T>[]` | – | ✓ | 列定义。 |
+| `data` | `T[]` | – | – | 数据源（主名）。 |
+| `dataSource` | `T[]` | – | – | 数据源（cd / antd 兼容名，等价 `data`）。 |
+| `rowKey` | `keyof T \| ((record: T) => string)` | `'id'` | – | 行唯一键字段或函数。 |
+| `size` | `'sm' \| 'md'` | `'sm'` | – | 表格尺寸。 |
+| `bordered` | `boolean` | `true` | – | 是否显示外边框与单元格分隔线。 |
+| `striped` | `boolean` | `false` | – | 是否启用斑马纹。 |
+| `hoverable` | `boolean` | `true` | – | 是否启用行 hover 高亮。 |
+| `crossline` | `boolean` | `false` | – | 是否启用十字辅助轴。 |
+| `stickyHeader` | `boolean` | `false` | – | 是否吸顶表头。 |
+| `maxBodyHeight` | `number \| string` | – | – | 表格容器最大高度（配合 stickyHeader 使用）。 |
+| `enableColumnResizing` | `boolean` | `false` | – | 是否启用列宽拖拽（开关，列级用 column.resizable 覆盖）。 |
+| `columnSizing` | `Record<string, number>` | – | – | 受控列宽状态。 |
+| `onColumnSizingChange` | `(sizing: Record<string, number>) => void` | – | – | 列宽变更回调（拖拽完成时触发）。 |
+| `isTree` | `boolean` | `false` | – | 是否启用树形结构（按 `childrenColumnName` 字段递归渲染子行）。 |
+| `childrenColumnName` | `string` | `'children'` | – | 子节点字段名（树形模式下）。 |
+| `indentSize` | `number` | `16` | – | 每层缩进像素（树形模式下）。 |
+| `virtual` | `boolean` | `false` | – | 是否启用虚拟滚动（大数据量场景）。需同时设置 `maxBodyHeight`。 |
+| `estimateRowHeight` | `number` | `40` | – | 虚拟滚动预估行高（像素）。 |
+| `virtualOverscan` | `number` | `8` | – | 虚拟滚动 overscan 个数。 |
+| `cellProps` | `( rowIndex: number, colIndex: number, record: T, ) => { rowSpan?: number; colSpan?: number } \| undefined` | – | – | 合并单元格：返回 `{ rowSpan, colSpan }`；返回 0 则跳过该 td。 |
+| `draggable` | `boolean` | `false` | – | 是否启用行拖拽排序。 |
+| `onDragEnd` | `(info: { from: number; to: number; data: T[] }) => void` | – | – | 行拖拽结束回调（仅拖拽启用时）。 |
+| `loading` | `boolean` | `false` | – | 是否加载中。 |
+| `loadingNode` | `React.ReactNode` | – | – | 自定义加载节点。 |
+| `empty` | `React.ReactNode` | `居中 Inbox 图标 + “暂无数据”` | – | 空数据节点。 |
+| `sorting` | `SortingState` | – | – | 受控排序状态（TanStack SortingState）。 |
+| `onSortingChange` | `(sorting: SortingState) => void` | – | – | 排序变化回调。 |
+| `columnFilters` | `ColumnFiltersState` | – | – | 受控列过滤状态（TanStack ColumnFiltersState）。 |
+| `onColumnFiltersChange` | `(filters: ColumnFiltersState) => void` | – | – | 列过滤变化回调。 |
+| `columnVisibility` | `VisibilityState` | – | – | 受控列显隐状态（key 为列 id，value 为 boolean）。 |
+| `onColumnVisibilityChange` | `(visibility: VisibilityState) => void` | – | – | 列显隐变化回调。 |
+| `rowSelection` | `DataTableRowSelection<T>` | – | – | 行选择配置；传入开启选择列。 |
+| `pagination` | `DataTablePagination` | – | – | 分页配置；传 false 关闭分页。 |
+| `expandable` | `DataTableExpandable<T>` | – | – | 行展开配置；传入开启展开列。 |
+| `onRow` | `( record: T, index: number, ) => React.HTMLAttributes<HTMLTableRowElement>` | – | – | 行级 props（cd 兼容）。 |
+| `onRowClick` | `(record: T, index: number, e: React.MouseEvent) => void` | – | – | 整行点击。 |
+| `className` | `string` | – | – | 类容器 className（透传给最外层 div）。 |
+| `tableClassName` | `string` | – | – | Table 的 className（内层 table 元素）。 |
+| `value` | `string \| number` | – | ✓ | 当前值。 |
+| `onCommit` | `(next: string \| number) => void` | – | ✓ | blur / Enter 时若值变化则提交。 |
+| `type` | `'text' \| 'number'` | `'text'` | – | 输入类型。 |
+| `placeholder` | `string` | – | – | placeholder。 |
+| `className` | `string` | – | – | 自定义 className。 |
+
+## 示例
+
+### ExpandedRow
+
+行展开：`expandable.expandedRowRender` 渲染额外区域。
+
+```tsx
+<DataTable
+  columns={baseColumns}
+  data={users.slice(0, 4)}
+  expandable={{
+    expandedRowRender: (record) => (
+      <div className="flex flex-col gap-1 text-xs">
+        <p>姓名：{record.name}</p>
+        <p>城市：{record.city}</p>
+        <p>状态：{record.status}</p>
+      </div>
+    ),
+  }}
+/>
+```
+
+### LoadingAndEmpty
+
+Loading 与 Empty 状态。
+
+```tsx
+<div className="flex flex-col gap-6">
+  <div>
+    <p className="mb-2 text-xs text-muted-foreground">loading</p>
+    <DataTable columns={baseColumns} data={users.slice(0, 3)} loading />
+  </div>
+  <div>
+    <p className="mb-2 text-xs text-muted-foreground">empty</p>
+    <DataTable columns={baseColumns} data={[]} />
+  </div>
+</div>
+```