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名活跃

排序、过滤与展开

Select all rows		角色
Select row	Alice Chen	管理员
alice@example.com · 活跃
Select row	Bob Smith	编辑者
bob@example.com · 活跃
Select row	Carol Lee	查看者
carol@example.com · 已邀请
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名成员

React

CSS

Tailwind

@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"`	—	由所选样式表提供的外观变体。
`render`	`ReactElement \| ((props, state) => ReactElement)`	—	替换渲染元素，同时保留行为和无障碍连接关系。

`Table.Footer`

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

`Table.RowHeader / Table.Cell / Table.ColumnHeader`

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

`TableClient.ExpandTrigger / TableClient.ExpandedRow`

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

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

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

`Table.Header`

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

`Table.Body`

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

`Table.Row`

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

`Table.ColumnHeader`

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

`Table.Cell`

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

`Table.Caption`

属性	类型	默认值	说明
`children`	`ReactNode`	—	描述表格的说明文字。
`render`	`ReactElement \| ((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

框架

样式

主题

语言

Table

交互示例

Table

原生表格示例

排序、过滤与展开

固定表头、表尾和列

API

`Table.Root (native)`

`Table.Footer`

`Table.RowHeader / Table.Cell / Table.ColumnHeader`

`TableClient.ExpandTrigger / TableClient.ExpandedRow`

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

`Table.Header`

`Table.Body`

`Table.Row`

`Table.ColumnHeader`

`Table.Cell`

`Table.Caption`

`Table.RowSelect`

键盘

无障碍

样式钩子