跳至正文

Table

原生表格,可选配交互适配器。

浏览器
Chrome 123+Firefox 121+Safari 17.5+
层级
0
压缩后大小
617 B
强制布局预算
0 ms
axe 预算
0
支持 SSR
是
公开契约
测试环境

交互示例

Table

原生表格示例

团队成员
姓名角色状态
Alice Chen管理员活跃
Bob Smith编辑者活跃
Carol Lee查看者已邀请
3名成员 · 2名活跃

排序、过滤与展开

角色详细信息
Alice Chen管理员
Bob Smith编辑者
Carol Lee查看者
3名成员 · 已选0名

固定表头、表尾和列

成员1编辑者member1@example.com活跃
成员2编辑者member2@example.com活跃
成员3编辑者member3@example.com活跃
成员4编辑者member4@example.com活跃
成员5编辑者member5@example.com活跃
成员6编辑者member6@example.com活跃
成员7编辑者member7@example.com活跃
成员8编辑者member8@example.com活跃
成员9编辑者member9@example.com活跃
成员10编辑者member10@example.com活跃
成员11编辑者member11@example.com活跃
成员12编辑者member12@example.com活跃
成员13编辑者member13@example.com活跃
成员14编辑者member14@example.com活跃
成员15编辑者member15@example.com活跃
成员16编辑者member16@example.com活跃
成员17编辑者member17@example.com活跃
成员18编辑者member18@example.com活跃
成员19编辑者member19@example.com活跃
成员20编辑者member20@example.com活跃
成员21编辑者member21@example.com活跃
成员22编辑者member22@example.com活跃
成员23编辑者member23@example.com活跃
成员24编辑者member24@example.com活跃
24名成员
import { Table } from "@gunkin/uiify";
const rows = [
  { id: "alice", name: "Alice Chen", role: "Admin", status: "Active" },
  { id: "bob", name: "Bob Smith", role: "Editor", status: "Active" },
  { id: "carol", name: "Carol Lee", role: "Viewer", status: "Invited" },
];
export default function Example() {
  return (
    <Table.Root className="" variant="outline" size="sm">
      <Table.Caption>Team members</Table.Caption>
      <Table.Header>
        <Table.Row id="team-head">
          <Table.ColumnHeader id="team-name">Name</Table.ColumnHeader>
          <Table.ColumnHeader id="team-role">Role</Table.ColumnHeader>
          <Table.ColumnHeader id="team-status">Status</Table.ColumnHeader>
        </Table.Row>
      </Table.Header>
      <Table.Body>
        {rows.map((row) => (
          <Table.Row id={row.id} key={row.id}>
            <Table.RowHeader>{row.name}</Table.RowHeader>
            <Table.Cell>{row.role}</Table.Cell>
            <Table.Cell>{row.status}</Table.Cell>
          </Table.Row>
        ))}
      </Table.Body>
      <Table.Footer>
        <Table.Row id="team-total">
          <Table.Cell colSpan={3}>3 members · 2 active</Table.Cell>
        </Table.Row>
      </Table.Footer>
    </Table.Root>
  );
}
@layer components {
  [data-uiify-table] {
    inline-size: 100%;
    border-collapse: separate;
    border-spacing: 0;
    background: var(--card);
    color: var(--card-foreground);
    font-size: var(--text-sm);
  }
  [data-uiify-table][data-layout="fixed"] {
    table-layout: fixed;
  }
  [data-uiify-table] :is(th, td) {
    padding-block: 0.75rem;
    padding-inline: 1rem;
    text-align: start;
    vertical-align: middle;
    border-block-end: 1px solid var(--border);
    background: inherit;
  }
  [data-uiify-table] :is(th, td)[data-align="center"] {
    text-align: center;
  }
  [data-uiify-table] :is(th, td)[data-align="end"] {
    text-align: end;
  }
  [data-uiify-table] :is(thead, tfoot) {
    background: var(--secondary);
    font-weight: 600;
  }
  [data-uiify-table] tbody tr {
    background: var(--card);
  }
  [data-uiify-table] tbody tr:hover {
    background: var(--secondary);
  }
  [data-uiify-table] tbody tr[data-selected] {
    background: var(--accent);
  }
  [data-uiify-table] caption {
    padding-block: 0.75rem;
    text-align: start;
    color: var(--muted-foreground);
  }
  [data-uiify-table][data-size="sm"] :is(th, td) {
    padding-block: 0.5rem;
    padding-inline: 0.75rem;
  }
  [data-uiify-table][data-size="lg"] :is(th, td) {
    padding-block: 1rem;
    padding-inline: 1.25rem;
  }
  [data-uiify-table][data-variant="outline"] {
    border: 1px solid var(--border);
    border-radius: var(--radius-lg);
  }
  [data-uiify-table][data-variant="ghost"] {
    background: transparent;
  }
  [data-uiify-table] :is(thead, tfoot, tr)[data-sticky] {
    position: sticky;
    inset-block-start: var(--uiify-table-sticky-offset, 0);
    z-index: 2;
  }
  [data-uiify-table] tfoot[data-sticky] {
    inset-block: auto var(--uiify-table-sticky-offset, 0);
  }
  [data-uiify-table] :is(th, td)[data-sticky] {
    position: sticky;
    z-index: 1;
  }
  [data-uiify-table] :is(th, td)[data-sticky="start"] {
    inset-inline-start: var(--uiify-table-sticky-offset, 0);
  }
  [data-uiify-table] :is(th, td)[data-sticky="end"] {
    inset-inline-end: var(--uiify-table-sticky-offset, 0);
  }
  [data-uiify-table] :is(thead, tfoot)[data-sticky] :is(th, td)[data-sticky] {
    z-index: 3;
  }
  [data-uiify-table] th > button {
    display: inline-flex;
    align-items: center;
    gap: 0.5rem;
    padding: 0;
    border: 0;
    background: transparent;
    color: inherit;
    font: inherit;
    cursor: pointer;
  }
  [data-uiify-table] th[aria-sort="ascending"] > button::after {
    content: "↑" / "";
  }
  [data-uiify-table] th[aria-sort="descending"] > button::after {
    content: "↓" / "";
  }
  [data-uiify-table] [data-part="expanded-row"] {
    background: var(--secondary);
  }
  [data-uiify-table] :is(button, tr):focus-visible {
    outline: 2px solid var(--ring);
    outline-offset: -2px;
  }
}
import { Table } from "@gunkin/uiify";
const rows = [
  { id: "alice", name: "Alice Chen", role: "Admin", status: "Active" },
  { id: "bob", name: "Bob Smith", role: "Editor", status: "Active" },
  { id: "carol", name: "Carol Lee", role: "Viewer", status: "Invited" },
];
export default function Example() {
  return (
    <Table.Root
      className={
        "[inline-size:100%] [border-collapse:separate] [border-spacing:0] bg-card text-card-foreground text-sm data-" +
        "[layout=fixed]:table-fixed [&_:is(th,td)]:[padding-block:0.75rem] [&_:is(th,td)]:[padding-inline:1rem] [&_:" +
        "is(th,td)]:text-start [&_:is(th,td)]:[vertical-align:middle] [&_:is(th,td)]:[border-block-end-width:1px] [&" +
        "_:is(th,td)]:[border-block-end-style:solid] [&_:is(th,td)]:[border-block-end-color:var(--border)] [&_:is(th" +
        ",td)]:[background:inherit] [&_:is(th,td)[data-align=center]]:text-center [&_:is(th,td)[data-align=end]]:tex" +
        "t-end [&_:is(thead,tfoot)]:bg-secondary [&_:is(thead,tfoot)]:[font-weight:600] [&_tbody_tr]:bg-card [&_tbod" +
        "y_tr:hover]:bg-secondary [&_tbody_tr[data-selected]]:bg-accent [&_caption]:[padding-block:0.75rem] [&_capti" +
        "on]:text-start [&_caption]:text-muted-foreground [&[data-size=sm]_:is(th,td)]:[padding-block:0.5rem] [&[dat" +
        "a-size=sm]_:is(th,td)]:[padding-inline:0.75rem] [&[data-size=lg]_:is(th,td)]:[padding-block:1rem] [&[data-s" +
        "ize=lg]_:is(th,td)]:[padding-inline:1.25rem] data-[variant=outline]:[border-width:1px] data-[variant=outlin" +
        "e]:border-solid data-[variant=outline]:border-border data-[variant=outline]:rounded-lg data-[variant=ghost]" +
        ":bg-transparent [&_:is(thead,tfoot,tr)[data-sticky]]:sticky [&_:is(thead,tfoot,tr)[data-sticky]]:[inset-blo" +
        "ck-start:var(--uiify-table-sticky-offset,_0)] [&_:is(thead,tfoot,tr)[data-sticky]]:z-[2] [&_tfoot[data-stic" +
        "ky]]:[inset-block:auto_var(--uiify-table-sticky-offset,_0)] [&_:is(th,td)[data-sticky]]:sticky [&_:is(th,td" +
        ")[data-sticky]]:z-[1] [&_:is(th,td)[data-sticky=start]]:[inset-inline-start:var(--uiify-table-sticky-offset" +
        ",_0)] [&_:is(th,td)[data-sticky=end]]:[inset-inline-end:var(--uiify-table-sticky-offset,_0)] [&_:is(thead,t" +
        "foot)[data-sticky]_:is(th,td)[data-sticky]]:z-[3] [&_th>button]:inline-flex [&_th>button]:items-center [&_t" +
        "h>button]:[gap:0.5rem] [&_th>button]:p-0 [&_th>button]:border-0 [&_th>button]:border-current [&_th>button]:" +
        "border-none [&_th>button]:bg-transparent [&_th>button]:text-inherit [&_th>button]:[font-style:inherit] [&_t" +
        "h>button]:[font-variant:inherit] [&_th>button]:[font-weight:inherit] [&_th>button]:[font-stretch:inherit] [" +
        "&_th>button]:text-[length:inherit] [&_th>button]:leading-[inherit] [&_th>button]:font-[family-name:inherit]" +
        " [&_th>button]:cursor-pointer [&_th[aria-sort=ascending]>button::after]:content-[\"↑\"_/_\"\"] [&_th[aria-sort=" +
        "descending]>button::after]:content-[\"↓\"_/_\"\"] [&_[data-part=expanded-row]]:bg-secondary [&_:is(button,tr):f" +
        "ocus-visible]:[outline:2px_solid_var(--ring)] [&_:is(button,tr):focus-visible]:[outline-offset:-2px]"
      }
      variant="outline"
      size="sm"
    >
      <Table.Caption>Team members</Table.Caption>
      <Table.Header>
        <Table.Row id="team-head">
          <Table.ColumnHeader id="team-name">Name</Table.ColumnHeader>
          <Table.ColumnHeader id="team-role">Role</Table.ColumnHeader>
          <Table.ColumnHeader id="team-status">Status</Table.ColumnHeader>
        </Table.Row>
      </Table.Header>
      <Table.Body>
        {rows.map((row) => (
          <Table.Row id={row.id} key={row.id}>
            <Table.RowHeader>{row.name}</Table.RowHeader>
            <Table.Cell>{row.role}</Table.Cell>
            <Table.Cell>{row.status}</Table.Cell>
          </Table.Row>
        ))}
      </Table.Body>
      <Table.Footer>
        <Table.Row id="team-total">
          <Table.Cell colSpan={3}>3 members · 2 active</Table.Cell>
        </Table.Row>
      </Table.Footer>
    </Table.Root>
  );
}
/* app.css */

@layer reset, ui, app, tokens, base, demo, components, utilities, theme;

@import "@gunkin/uiify/styles/reset";

@import "@gunkin/uiify/components/behavior.css";

@import "@gunkin/uiify/styles/tokens";

@import "@gunkin/uiify/styles/tailwind";

@import "tailwindcss/utilities.css";

@theme { --spacing: 0.25rem; --font-weight-normal: 400; --font-weight-medium: 500; --font-weight-semibold: 600; --font-weight-bold: 700; }

@source inline('[inline-size:100%] [border-collapse:separate] [border-spacing:0] bg-card text-card-foreground text-sm data-[layout=fixed]:table-fixed [&_:is(th,td)]:[padding-block:0.75rem] [&_:is(th,td)]:[padding-inline:1rem] [&_:is(th,td)]:text-start [&_:is(th,td)]:[vertical-align:middle] [&_:is(th,td)]:[border-block-end-width:1px] [&_:is(th,td)]:[border-block-end-style:solid] [&_:is(th,td)]:[border-block-end-color:var(--border)] [&_:is(th,td)]:[background:inherit] [&_:is(th,td)[data-align=center]]:text-center [&_:is(th,td)[data-align=end]]:text-end [&_:is(thead,tfoot)]:bg-secondary [&_:is(thead,tfoot)]:[font-weight:600] [&_tbody_tr]:bg-card [&_tbody_tr:hover]:bg-secondary [&_tbody_tr[data-selected]]:bg-accent [&_caption]:[padding-block:0.75rem] [&_caption]:text-start [&_caption]:text-muted-foreground [&[data-size=sm]_:is(th,td)]:[padding-block:0.5rem] [&[data-size=sm]_:is(th,td)]:[padding-inline:0.75rem] [&[data-size=lg]_:is(th,td)]:[padding-block:1rem] [&[data-size=lg]_:is(th,td)]:[padding-inline:1.25rem] data-[variant=outline]:[border-width:1px] data-[variant=outline]:border-solid data-[variant=outline]:border-border data-[variant=outline]:rounded-lg data-[variant=ghost]:bg-transparent [&_:is(thead,tfoot,tr)[data-sticky]]:sticky [&_:is(thead,tfoot,tr)[data-sticky]]:[inset-block-start:var(--uiify-table-sticky-offset,_0)] [&_:is(thead,tfoot,tr)[data-sticky]]:z-[2] [&_tfoot[data-sticky]]:[inset-block:auto_var(--uiify-table-sticky-offset,_0)] [&_:is(th,td)[data-sticky]]:sticky [&_:is(th,td)[data-sticky]]:z-[1] [&_:is(th,td)[data-sticky=start]]:[inset-inline-start:var(--uiify-table-sticky-offset,_0)] [&_:is(th,td)[data-sticky=end]]:[inset-inline-end:var(--uiify-table-sticky-offset,_0)] [&_:is(thead,tfoot)[data-sticky]_:is(th,td)[data-sticky]]:z-[3] [&_th>button]:inline-flex [&_th>button]:items-center [&_th>button]:[gap:0.5rem] [&_th>button]:p-0 [&_th>button]:border-0 [&_th>button]:border-current [&_th>button]:border-none [&_th>button]:bg-transparent [&_th>button]:text-inherit [&_th>button]:[font-style:inherit] [&_th>button]:[font-variant:inherit] [&_th>button]:[font-weight:inherit] [&_th>button]:[font-stretch:inherit] [&_th>button]:text-[length:inherit] [&_th>button]:leading-[inherit] [&_th>button]:font-[family-name:inherit] [&_th>button]:cursor-pointer [&_th[aria-sort=ascending]>button::after]:content-["↑"_/_""] [&_th[aria-sort=descending]>button::after]:content-["↓"_/_""] [&_[data-part=expanded-row]]:bg-secondary [&_:is(button,tr):focus-visible]:[outline:2px_solid_var(--ring)] [&_:is(button,tr):focus-visible]:[outline-offset:-2px]');

@layer base { :root { --uiify-control-text: var(--text-sm); } @media (pointer: coarse) { :root { --uiify-control-text: var(--text-base); } } }

/* Authored animation and registered properties used by the Tailwind skin.
 * Visual rules belong in utility recipes; only at-rule definitions live here. */
@layer components {
  @keyframes uiify-presence-in {
    from {
      opacity: 0;
      scale: var(--presence-scale);
    }
  }
}

@layer components {
  @keyframes uiify-presence-out {
    to {
      opacity: 0;
      scale: var(--presence-scale);
    }
  }
}

@property --uiify-spinner-tail {
  syntax: "<angle>";
  inherits: false;
  initial-value: 0deg;
}

@property --uiify-spinner-length {
  syntax: "<angle>";
  inherits: false;
  initial-value: 36deg;
}

@layer components {
  @keyframes uiify-spinner-rotate {
    to {
      transform: rotate(360deg);
    }
  }
}

@layer components {
  @keyframes uiify-spinner-orbit {
    0% {
      --uiify-spinner-tail: 0deg;
      --uiify-spinner-length: 36deg;
    }

    50% {
      --uiify-spinner-tail: 90deg;
      --uiify-spinner-length: 324deg;
    }

    100% {
      --uiify-spinner-tail: 360deg;
      --uiify-spinner-length: 36deg;
    }
  }
}

@layer components {
  @keyframes uiify-skeleton-pulse {
    50% {
      opacity: 0.45;
    }
  }
}

@layer components {
  @keyframes uiify-skeleton-shimmer {
    to {
      background-position: -200% 0;
    }
  }
}

@layer components {
  @keyframes uiify-skeleton-reveal {
    from {
      opacity: 0;
    }
    to {
      opacity: 1;
    }
  }
}

@property --candle-body-height {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 0%;
}

@property --candle-body-top {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 50%;
}

@property --candle-slot {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 100%;
}

@property --candle-wick-height {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 0%;
}

@property --candle-wick-top {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 50%;
}

@property --candle-x {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 0%;
}

@property --candle-scale {
  syntax: "<number>";
  inherits: true;
  initial-value: 1;
}

@property --line-y {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 50%;
}

@property --line-prev-y {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 50%;
}

@property --line-count {
  syntax: "<integer>";
  inherits: false;
  initial-value: 1;
}

@property --line-scale {
  syntax: "<number>";
  inherits: true;
  initial-value: 1;
}

@layer components {
  @keyframes uiify-otp-input-caret-blink {
    50% {
      opacity: 0;
    }
  }
}

API

Table.Root (native)

属性类型默认值说明
layout"auto" | "fixed""auto"原生表格布局。选择、排序和展开使用显式的TableClient入口。
size"sm" | "md" | "lg"—由所选样式表提供的单元格间距。
variant"solid" | "outline" | "ghost"—由所选样式表提供的外观变体。
renderReactElement | ((props, state) => ReactElement)—替换渲染元素,同时保留行为和无障碍连接关系。

Table.Footer

属性类型默认值说明
stickyboolean—将表尾固定在滚动容器的块轴末端。
renderReactElement | ((props, state) => ReactElement)—替换渲染元素,同时保留行为和无障碍连接关系。

Table.RowHeader / Table.Cell / Table.ColumnHeader

属性类型默认值说明
align"start" | "center" | "end""start"该单元格的逻辑文本对齐方式。
sticky"start" | "end"—将单元格固定在逻辑行内边缘。相邻固定单元格应分别设置--uiify-table-sticky-offset。
renderReactElement | ((props, state) => ReactElement)—替换渲染元素,同时保留行为和无障碍连接关系。

TableClient.ExpandTrigger / TableClient.ExpandedRow

属性类型默认值说明
rowId*string—连接展开按钮与其原生<tr>的共享行key。在展开行内放置<td colSpan={columnCount}>。

TableClient.Root — @gunkin/uiify/components/table/client

属性类型默认值说明
aria-labelstring—没有可见标题或表格说明时使用的表格无障碍名称。
aria-labelledbystring—为表格提供标签的元素id。
selectionMode"none" | "single" | "multiple""none"是否允许选择行,以及每次可选多少行;"none"渲染不带grid角色的普通静态表格。
selectionBehavior"toggle" | "replace"—点击行时,将其加入选择还是替换当前选择。
defaultSelectedKeysIterable<string>—初始选中的行id,选择状态由组件内部非受控管理。
selectedKeysIterable<string>—当前选中的行id,选择状态由调用方受控管理。
onSelectionChange(selectedKeys: Set<string>) => void—选择变化时,使用新的已选行id集合调用。
defaultSortDescriptorSortDescriptor | null—初始排序列和方向,排序状态由组件内部非受控管理。
sortDescriptorSortDescriptor | null—当前排序列和方向,使排序状态受控。
onSortChange(descriptor: SortDescriptor | null) => void—激活可排序列标题时,使用新的排序描述或null调用。
expandedKeys / defaultExpandedKeysIterable<string>—受控或初始展开行key。
onExpandedChange(keys: Set<string>) => void—报告展开请求。受控行等待更新后的key。
renderReactElement | ((props, state) => ReactElement)—替换渲染元素,同时保留行为和无障碍连接关系。

Table.Header

属性类型默认值说明
stickybooleanfalse将此区块固定在滚动容器中;Header使用块轴起点,Footer使用块轴末端。
renderReactElement | ((props, state) => ReactElement)—替换渲染元素,同时保留行为和无障碍连接关系。

Table.Body

属性类型默认值说明
childrenReactNode—表格主体的行。
renderReactElement | ((props, state) => ReactElement)—替换渲染元素,同时保留行为和无障碍连接关系。

Table.Row

属性类型默认值说明
id*string—稳定的行id,用作选择key和元素id。
disabledbooleanfalse阻止该行被选择或通过键盘聚焦。
selectedboolean—在选择存储接管前,将服务端渲染标记中的行标为选中。
renderReactElement | ((props, state) => ReactElement)—替换渲染元素,同时保留行为和无障碍连接关系。

Table.ColumnHeader

属性类型默认值说明
id*string—排序描述引用的列id。
allowsSortingbooleanfalse使标题可切换所在列的排序,并发布aria-sort。
sortDirection"ascending" | "descending" | null—该列渲染的排序方向;允许排序时,用于初始服务端标记。
onClickReact.MouseEventHandler<HTMLTableCellElement>—排序前运行;preventDefault()可阻止排序变更。
childrenReactNode—表头标签。
renderReactElement | ((props, state) => ReactElement)—替换渲染元素,同时保留行为和无障碍连接关系。

Table.Cell

属性类型默认值说明
childrenReactNode—单元格内容。
renderReactElement | ((props, state) => ReactElement)—替换渲染元素,同时保留行为和无障碍连接关系。

Table.Caption

属性类型默认值说明
childrenReactNode—描述表格的说明文字。
renderReactElement | ((props, state) => ReactElement)—替换渲染元素,同时保留行为和无障碍连接关系。

Table.RowSelect

属性类型默认值说明
rowId*string—该复选框用于选择或取消选择的行id。

键盘

按键操作
Tab聚焦TableClient中的排序、选择和展开控件
Enter / Space激活已聚焦的排序或展开按钮;切换复选框
Arrow keys在TableClient中可选择的表格主体行之间移动

无障碍

默认Table渲染原生<table>、<caption>、<thead>、<tbody>和<tfoot>,无须客户端JavaScript;使用ColumnHeader和RowHeader提供表头语义。/client入口添加排序、选择、键盘行导航和受控展开,并通过aria-sort、aria-expanded和aria-controls暴露状态。ExpandedRow是原生<tr>;应在其内部放置带colSpan的Cell。过滤和排序顺序由使用方处理。

样式钩子

data-uiify-tabledata-partdata-layoutdata-sizedata-variantdata-stickydata-selecteddata-disabled--uiify-table-sticky-offset