可排序資料表

後台最常用的那張表：點欄頭在遞增、遞減、不排序之間循環，每一列以 FLIP 動畫從舊位置滑到新位置，看得出誰換到了哪裡；內容超過 maxHeight 時在表內捲動、表頭 sticky 置頂。勾選任一列後，頂部以 spring 滑入批次操作列（「已選 N 筆」＋動作按鈕＋清除）；提供 expandable 時列首多一個展開箭頭，明細列以高度動畫展開。欄位可自訂渲染與比較函式，預設比較自動判別數字、純數字字串與日期字串。

Playground

即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。

import * as React from "react";

export default function Example() {
  return (
    <div className="flex min-h-[320px] w-full items-center justify-center p-6">

<SortableDataTable/>

    </div>
  );
}

安裝

使用

import {
  SortableDataTable,
  type SortableColumn,
} from "@/components/ui/sortable-data-table";

type Order = {
  id: string;
  customer: string;
  amount: number;
  status: string;
  date: string;
};

const columns: SortableColumn<Order>[] = [
  { key: "id", label: "訂單編號", sortable: true },
  { key: "customer", label: "客戶", sortable: true },
  {
    key: "amount",
    label: "金額",
    sortable: true,
    align: "right",
    render: (row) => `NT$ ${row.amount.toLocaleString("zh-TW")}`,
  },
  { key: "status", label: "狀態" },
  { key: "date", label: "日期", sortable: true },
];

<SortableDataTable
  columns={columns}
  rows={orders}
  defaultSort={{ key: "date", dir: "desc" }}
  selectable
  bulkActions={[{ id: "ship", label: "標記出貨" }]}
  onBulkAction={(actionId, ids) => markShipped(ids)}
  expandable={(row) => <OrderDetail order={row} />}
/>;

Props

SortableColumn

SortState

BulkAction

另外具名匯出 SortableRowBase、SortableColumn、SortState、BulkAction 型別，以及預設比較函式 compareCellValues(a, b)，可在自訂 sortFn 裡沿用。

細節

• 排序循環：點同一欄的欄頭依序切換遞增 → 遞減 → 不排序；換點另一欄則從遞增開始。不排序時回到 rows 的原始順序
• 預設比較：兩邊都是數字或純數字字串時比數值（避免 "12" 排在 "3" 前面），都是 YYYY-MM-DD／YYYY/M/D 開頭的日期字串時比時間，其餘以 localeCompare 比較；空值無論方向都排在最後，同值列以原始順序保持穩定
• FLIP 重排：每一列以 motion 的 layout 搭配穩定的 id key 做重排滑動。刻意不用 layoutId——它是全域命名空間，同一頁有兩張表出現相同的 row id 時會誤觸共享元素動畫
• 受控與非受控：sort 與 selected 各自可受控或非受控；展開狀態由元件內部管理
• 表頭全選 checkbox 在部分勾選時呈現半選（indeterminate）狀態；全選只作用於目前 rows 內的列

可及性

• 使用語意化的 table／thead／th scope="col"；可排序欄頭是 type="button" 的按鈕，th 帶 aria-sort（ascending／descending／none）
• 全選與每列 checkbox 都有 aria-label；展開按鈕帶 aria-expanded 與「展開／收合 明細」標籤
• 批次操作列為 role="toolbar"，清除按鈕附 aria-label；所有按鈕都有 focus-visible 焦點環
• 使用者系統開啟「減少動態效果」時，列直接重排不做 FLIP 滑動，批次操作列與明細列直接出現、欄頭箭頭直接翻轉