PatternsApp Patterns
DataTablePage
@mox-hub/patterns 模式 · App Patterns · canonical
data-table-page@mox-hub/patternsApp Patternscanonicalsrc/components/data-table-page.tsx变体演示data-table-page
| 登录页改版 | 进行中 |
| 支付回调修复 | 已完成 |
显示 1–2 条,共 2 条1 / 1
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| columns* | ColumnDef<T, unknown>[] | — | — |
| data* | T[] | — | — |
| state* | "empty" | "loading" | "error" | "ready" | 'ready' | — |
| onRetry* | () => void | — | — |
| toolbar* | ReactNode | — | — |
| filters* | ReactNode | — | — |
| pagination* | { page: number; pageSize: number; total: number; onPageChange: (page: number) => void; } | — | — |
| bulkActions* | ReactNode | — | — |
| selectedCount* | number | 0 | — |
| onClearSelection* | () => void | — | — |
| emptyState* | ReactNode | — | — |
| errorState* | ReactNode | — | — |
| loadingState* | ReactNode | — | — |
| labels* | Partial<DataTablePageLabels> | — | — |
| className* | string | — | — |
源码
/**
* DataTablePage - L3 列表页整页装配件(W4 B5:列表页整页装配)
*
* 收编「工具栏(ToolbarRow)+ 筛选条(FilterChipsRow/任意筛选节点)+ 表格
* (ui/DataTable)+ 分页(ui/Pagination)」的重复拼装,并把四态占位
* (loading / error / empty / ready)一次封死:
* - loading / error / empty:渲染占位(优先消费方传入节点,否则内置
* Spinner+文案 / EmptyState+重试 / EmptyState);
* - ready:工具栏、筛选、批量操作条、表格、数字分页依次装配。
*
* 分层:patterns 装配件,只组合 ui 原子与本层既有件;不取数、不发请求、
* 不持有筛选/排序/分页状态(全部经 props 受控),不依赖 router/query/i18n 框架。
*
* 与 ui/DataTable 的适配:
* - columns / data 原样透传,DataTable 的 `manualPagination` 恰与本件 `pagination`
* 形状一致(page 1-based + pageSize + total + onPageChange),因此直接复用它的
* 受控分页模型,不在 patterns 里另造排序/分页实现;翻页动作统一经本件下发。
* - DataTable 自带的卡片壳(rounded-xl + border + shadow-xs)就是「表格壳」,
* 故不再套 data-table-shell,避免审计 P2-07 记录的 8px+12px 双层边框。
* - DataTable 卡片 footer 是紧凑区间/上下页;本件在其下按需补一条
* ui/pagination 数字跳页条(仅 pageCount > 1 时出现),两者共用同一
* onPageChange,便于直接跳到指定页。
* - `ColumnDef` 经 `@mox-hub/ui/components/data-table` 再导出取类型,patterns
* 不新增 @tanstack/react-table 直接依赖。
*
* 越界修正:pagination.page 超出 [1, pageCount] 时按显示层夹取(不触发回调),
* 真实页码仍以消费方状态为准。
*/
import type { ReactNode } from 'react';
import { cn } from '@mox-hub/ui';
import { Button } from '@mox-hub/ui/components/button';
import {
DataTable,
type ColumnDef,
} from '@mox-hub/ui/components/data-table';
import { EmptyState } from '@mox-hub/ui/components/empty-state';
import {
Pagination,
PaginationContent,
PaginationEllipsis,
PaginationItem,
PaginationLink,
} from '@mox-hub/ui/components/pagination';
import { Spinner } from '@mox-hub/ui/components/spinner';
import { usePatternLabels } from '../lib/i18n';
/** 组件内文案缺省(中文常量;消费方经 labels 覆写接入 i18n)。 */
export interface DataTablePageLabels {
/** 加载态文案 */
loading: string;
/** 错误态标题 */
loadFailed: string;
/** 错误态说明(仅在未传 errorState 时出现) */
loadFailedDescription: string;
/** 错误态重试按钮 */
retry: string;
/** 空态标题 */
empty: string;
/** 批量操作条选中计数 */
selectedCount: (count: number) => string;
/** 清除选择按钮 */
clearSelection: string;
/** 批量操作条无障碍名 */
bulkActionsLabel: string;
/** 分页导航无障碍名 */
paginationLabel: string;
/** 数字跳页链接无障碍名 */
pageLink: (page: number) => string;
}
export const DATA_TABLE_PAGE_DEFAULT_LABELS: DataTablePageLabels = {
loading: '加载中…',
loadFailed: '加载失败',
loadFailedDescription: '请稍后重试。',
retry: '重试',
empty: '暂无数据',
selectedCount: (count) => `已选 ${count} 项`,
clearSelection: '清除选择',
bulkActionsLabel: '批量操作',
paginationLabel: '分页',
pageLink: (page) => `第 ${page} 页`,
};
export interface DataTablePageProps<T> {
/** 列定义(与 ui/DataTable 同源类型) */
columns: ColumnDef<T, unknown>[];
/** 行数据(受控分页时是「当前页」数据,由消费方按服务端结果传入) */
data: T[];
/** 页面数据态;缺省 ready(由消费方显式声明 loading/error/empty) */
state?: 'loading' | 'error' | 'empty' | 'ready';
/** 错误态重试回调(内置错误占位的重试按钮使用) */
onRetry?: () => void;
/** 工具栏槽(通常传 ToolbarRow) */
toolbar?: ReactNode;
/** 筛选槽(通常传 FilterChipsRow / FilterCascadeMenu 组合) */
filters?: ReactNode;
/** 受控分页(page 1-based;total 为服务端总数) */
pagination?: {
page: number;
pageSize: number;
total: number;
onPageChange: (page: number) => void;
};
/** 批量操作节点(与 selectedCount 联动,仅在选中数 > 0 时显示操作条) */
bulkActions?: ReactNode;
/** 当前选中行数 */
selectedCount?: number;
/** 清除选择回调(操作条右侧按钮;不传则隐藏按钮) */
onClearSelection?: () => void;
/** 自定义空态(优先于内置 EmptyState) */
emptyState?: ReactNode;
/** 自定义错误态(优先于内置 EmptyState + 重试) */
errorState?: ReactNode;
/** 自定义加载态(优先于内置 Spinner + 文案) */
loadingState?: ReactNode;
/** 文案覆写(默认 zh-CN;主仓 i18n 适配层集中传入 t() 结果)。 */
labels?: Partial<DataTablePageLabels>;
/** 页面外层附加类名 */
className?: string;
}
type PageItem = number | 'ellipsis-start' | 'ellipsis-end';
/** 数字跳页窗口:首尾常驻,当前页左右各 1 页,其余折叠为省略号 */
function buildPageItems(current: number, pageCount: number): PageItem[] {
if (pageCount <= 7) {
return Array.from({ length: pageCount }, (_, index) => index + 1);
}
const items: PageItem[] = [1];
const start = Math.max(2, current - 1);
const end = Math.min(pageCount - 1, current + 1);
if (start > 2) items.push('ellipsis-start');
for (let page = start; page <= end; page += 1) items.push(page);
if (end < pageCount - 1) items.push('ellipsis-end');
items.push(pageCount);
return items;
}
export function DataTablePage<T>({
columns,
data,
state = 'ready',
onRetry,
toolbar,
filters,
pagination,
bulkActions,
selectedCount = 0,
onClearSelection,
emptyState,
errorState,
loadingState,
labels,
className,
}: DataTablePageProps<T>) {
const D = usePatternLabels('dataTablePage', DATA_TABLE_PAGE_DEFAULT_LABELS);
const L: DataTablePageLabels = {
loading: labels?.loading ?? D.loading,
loadFailed: labels?.loadFailed ?? D.loadFailed,
loadFailedDescription: labels?.loadFailedDescription ?? D.loadFailedDescription,
retry: labels?.retry ?? D.retry,
empty: labels?.empty ?? D.empty,
selectedCount: labels?.selectedCount ?? D.selectedCount,
clearSelection: labels?.clearSelection ?? D.clearSelection,
bulkActionsLabel: labels?.bulkActionsLabel ?? D.bulkActionsLabel,
paginationLabel: labels?.paginationLabel ?? D.paginationLabel,
pageLink: labels?.pageLink ?? D.pageLink,
};
const showBulkBar = bulkActions != null && selectedCount > 0;
// 受控分页越界修正(显示层夹取,不触发回调):pageSize/total 非法时兜底 1。
const safePageSize = pagination ? Math.max(1, pagination.pageSize) : 1;
const pageCount = pagination
? Math.max(1, Math.ceil(pagination.total / safePageSize))
: 1;
const currentPage = pagination
? Math.min(Math.max(1, pagination.page), pageCount)
: 1;
let body: ReactNode;
if (state === 'loading') {
body = (
<div
data-slot="data-table-page-state"
data-state="loading"
role="status"
aria-live="polite"
>
{loadingState ?? (
<div className="flex min-h-45 items-center justify-center gap-2 text-sm text-muted-foreground">
<Spinner size="sm" aria-hidden="true" />
{L.loading}
</div>
)}
</div>
);
} else if (state === 'error') {
body = (
<div
data-slot="data-table-page-state"
data-state="error"
role="alert"
aria-live="assertive"
>
{errorState ?? (
<EmptyState
title={L.loadFailed}
description={L.loadFailedDescription}
action={
onRetry ? (
<Button type="button" onClick={onRetry}>
{L.retry}
</Button>
) : undefined
}
/>
)}
</div>
);
} else if (state === 'empty') {
body = (
<div
data-slot="data-table-page-state"
data-state="empty"
role="status"
aria-live="polite"
>
{emptyState ?? <EmptyState title={L.empty} />}
</div>
);
} else {
body = (
<>
{toolbar}
{filters}
{showBulkBar ? (
<div
data-slot="data-table-page-bulk-actions"
role="region"
aria-label={L.bulkActionsLabel}
className="flex flex-wrap items-center gap-2 rounded-lg border border-border bg-muted/40 px-3 py-2"
>
<span className="text-xs font-medium text-foreground">
{L.selectedCount(selectedCount)}
</span>
<div className="flex flex-wrap items-center gap-1">{bulkActions}</div>
{onClearSelection ? (
<Button
type="button"
variant="ghost"
size="xs"
className="ms-auto"
onClick={onClearSelection}
>
{L.clearSelection}
</Button>
) : null}
</div>
) : null}
{/* ui/DataTable 自带卡片壳;manualPagination 与上方受控分页同构 */}
<DataTable<T>
columns={columns}
data={data}
manualPagination={
pagination
? {
page: currentPage,
pageSize: safePageSize,
total: pagination.total,
onPageChange: pagination.onPageChange,
}
: undefined
}
/>
{/* 数字跳页条:与 DataTable footer 的紧凑上下页共用同一 onPageChange */}
{pagination &&
pagination.total > 0 &&
pageCount > 1 ? (
<Pagination aria-label={L.paginationLabel} className="justify-center">
<PaginationContent>
{buildPageItems(currentPage, pageCount).map((item, index) => {
if (typeof item !== 'number') {
return (
<PaginationItem key={`${item}-${index}`}>
<PaginationEllipsis />
</PaginationItem>
);
}
return (
<PaginationItem key={item}>
<PaginationLink
isActive={item === currentPage}
// 不传 href:PaginationLink 走 Button 的 nativeButton=false 路径,
// 由 base-ui 补齐 role=button + tabIndex 与 Enter/Space 激活;
// 翻页状态仍由消费方 onPageChange 受控(无 router 依赖)。
aria-label={L.pageLink(item)}
onClick={(event) => {
event.preventDefault();
if (item !== currentPage) pagination.onPageChange(item);
}}
>
{item}
</PaginationLink>
</PaginationItem>
);
})}
</PaginationContent>
</Pagination>
) : null}
</>
);
}
return (
<div
data-slot="data-table-page"
data-state={state}
aria-busy={state === 'loading' || undefined}
className={cn('flex min-w-0 flex-col gap-3', className)}
>
{body}
</div>
);
}
可访问性与 RTL
- 键盘:交互件保留
:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。 - RTL:间距、对齐与方向性图标使用逻辑属性 (
ms-*/text-start/rtl:-scale-x-100);通过ThemeProvider或I18nProvider的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。 - 文案:优先用组件
labels/translate/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
列表页整页装配:工具栏 + 筛选 + 表格壳 + 分页 + loading/error/empty/ready 四态 + 批量操作条;不取数。