Ordo UI
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*number0—
onClearSelection*() => void——
emptyState*ReactNode——
errorState*ReactNode——
loadingState*ReactNode——
labels*Partial<DataTablePageLabels>——
className*string——

源码

packages/patterns/src/components/data-table-page.tsx
/**
 * 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 /translator props,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。
  • 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。

用法说明

列表页整页装配:工具栏 + 筛选 + 表格壳 + 分页 + loading/error/empty/ready 四态 + 批量操作条;不取数。