表格 table

数据展示组件。三层同源：无头内核给出解剖与状态机，Vue 组件与自定义元素只是它的两层外壳，行为完全一致。

示例

基础用法

columns 是列号与列宽的唯一事实源，rows 是行序与行号的唯一事实源，标记只管长相

团队成员

姓名

部门

职级

赵一

平台研发

P6

钱二

前端体验

P7

孙三

基础架构

P6

李四

质量保障

P5

<script setup lang="ts">
import {
  XhTableBody,
  XhTableCaption,
  XhTableCell,
  XhTableColumnHeader,
  XhTableHeader,
  XhTableRoot,
  XhTableRow,
} from "@xihan-ui/vue";

const columns = [
  { id: "name", label: "姓名", width: "8rem" },
  { id: "dept", label: "部门" },
  { id: "level", label: "职级", width: "6rem" },
];

const members = [
  { id: "u1", name: "赵一", dept: "平台研发", level: "P6" },
  { id: "u2", name: "钱二", dept: "前端体验", level: "P7" },
  { id: "u3", name: "孙三", dept: "基础架构", level: "P6" },
  { id: "u4", name: "李四", dept: "质量保障", level: "P5" },
];

const rows = members.map((m) => ({ id: m.id }));
</script>

<template>
  <div style="width: 100%; max-width: 560px">
    <XhTableRoot :columns="columns" :rows="rows">
      <XhTableCaption>团队成员</XhTableCaption>
      <XhTableHeader>
        <!-- 表头行不给 value，它恒占行号空间的第 1 行 -->
        <XhTableRow>
          <XhTableColumnHeader v-for="col in columns" :key="col.id" :value="col.id">
            {{ col.label }}
          </XhTableColumnHeader>
        </XhTableRow>
      </XhTableHeader>
      <XhTableBody>
        <XhTableRow v-for="m in members" :key="m.id" :value="m.id">
          <XhTableCell value="name">{{ m.name }}</XhTableCell>
          <XhTableCell value="dept">{{ m.dept }}</XhTableCell>
          <XhTableCell value="level">{{ m.level }}</XhTableCell>
        </XhTableRow>
      </XhTableBody>
    </XhTableRoot>
  </div>
</template>

排序

列上标了 sortable 才认排序把手；按住 Shift 点是追加到排序链，裸点是整条链换成这一列

姓名

部门

职级

赵一

平台研发

P6

钱二

前端体验

P7

孙三

基础架构

P6

李四

前端体验

P5

排序链：（无）

<script setup lang="ts">
import { computed, ref } from "vue";
import {
  XhTableBody,
  XhTableCell,
  XhTableColumnHeader,
  XhTableHeader,
  XhTableRoot,
  XhTableRow,
  XhTableSortTrigger,
} from "@xihan-ui/vue";

interface Member {
  id: string;
  name: string;
  dept: string;
  level: string;
}

const columns = [
  { id: "name", label: "姓名", width: "8rem", sortable: true },
  { id: "dept", label: "部门", sortable: true },
  { id: "level", label: "职级", width: "6rem" },
];

const members: Member[] = [
  { id: "u1", name: "赵一", dept: "平台研发", level: "P6" },
  { id: "u2", name: "钱二", dept: "前端体验", level: "P7" },
  { id: "u3", name: "孙三", dept: "基础架构", level: "P6" },
  { id: "u4", name: "李四", dept: "前端体验", level: "P5" },
];

// 排序链是有序的：下标即优先级，第一个是主排序字段
const sort = ref<{ id: string; direction: "asc" | "desc" }[]>([]);

const sorted = computed(() => {
  if (!sort.value.length) return members;
  return [...members].sort((a, b) => {
    for (const s of sort.value) {
      const diff = String(a[s.id as keyof Member]).localeCompare(
        String(b[s.id as keyof Member]),
        "zh"
      );
      if (diff !== 0) return s.direction === "asc" ? diff : -diff;
    }
    return 0;
  });
});

// 行序的事实源跟着排序结果走
const rows = computed(() => sorted.value.map((m) => ({ id: m.id })));
</script>

<template>
  <div style="width: 100%; max-width: 560px; display: grid; gap: 12px">
    <XhTableRoot v-model:sort="sort" :columns="columns" :rows="rows">
      <XhTableHeader>
        <XhTableRow>
          <XhTableColumnHeader v-for="col in columns" :key="col.id" :value="col.id">
            <XhTableSortTrigger v-if="col.sortable">{{ col.label }}</XhTableSortTrigger>
            <template v-else>{{ col.label }}</template>
          </XhTableColumnHeader>
        </XhTableRow>
      </XhTableHeader>
      <XhTableBody>
        <XhTableRow v-for="m in sorted" :key="m.id" :value="m.id">
          <XhTableCell value="name">{{ m.name }}</XhTableCell>
          <XhTableCell value="dept">{{ m.dept }}</XhTableCell>
          <XhTableCell value="level">{{ m.level }}</XhTableCell>
        </XhTableRow>
      </XhTableBody>
    </XhTableRoot>
    <span>
      排序链：{{
        sort.length ? sort.map((s) => `${s.id} ${s.direction}`).join(" → ") : "（无）"
      }}
    </span>
  </div>
</template>

多选

selectionMode 默认 none，声明 multiple 才有选择机制；选择列也要在 columns 里占一条，否则右侧列号串位

✓

姓名

部门

✓

赵一

平台研发

✓

钱二

前端体验

✓

孙三

基础架构

✓

李四（禁用）

质量保障

选中：u2

<script setup lang="ts">
import { ref } from "vue";
import {
  XhTableBody,
  XhTableCell,
  XhTableColumnHeader,
  XhTableHeader,
  XhTableRoot,
  XhTableRow,
  XhTableRowSelectTrigger,
  XhTableSelectAllTrigger,
} from "@xihan-ui/vue";

const columns = [
  { id: "select", width: "3rem" },
  { id: "name", label: "姓名", width: "8rem" },
  { id: "dept", label: "部门" },
];

const members = [
  { id: "u1", name: "赵一", dept: "平台研发" },
  { id: "u2", name: "钱二", dept: "前端体验" },
  { id: "u3", name: "孙三", dept: "基础架构" },
  { id: "u4", name: "李四（禁用）", dept: "质量保障" },
];

// 禁用行选不动，也不算进全选的基数
const rows = [
  { id: "u1" },
  { id: "u2" },
  { id: "u3" },
  { id: "u4", disabled: true },
];

const selection = ref<string[] | "all">(["u2"]);
</script>

<template>
  <div style="width: 100%; max-width: 560px; display: grid; gap: 12px">
    <XhTableRoot
      v-model:selection="selection"
      :columns="columns"
      :rows="rows"
      selection-mode="multiple"
    >
      <XhTableHeader>
        <XhTableRow>
          <XhTableColumnHeader value="select">
            <!-- 全选把手是三态的唯一载体，自己占一个 Tab 位 -->
            <XhTableSelectAllTrigger>✓</XhTableSelectAllTrigger>
          </XhTableColumnHeader>
          <XhTableColumnHeader value="name">姓名</XhTableColumnHeader>
          <XhTableColumnHeader value="dept">部门</XhTableColumnHeader>
        </XhTableRow>
      </XhTableHeader>
      <XhTableBody>
        <XhTableRow v-for="m in members" :key="m.id" :value="m.id">
          <XhTableCell value="select">
            <XhTableRowSelectTrigger>✓</XhTableRowSelectTrigger>
          </XhTableCell>
          <XhTableCell value="name">{{ m.name }}</XhTableCell>
          <XhTableCell value="dept">{{ m.dept }}</XhTableCell>
        </XhTableRow>
      </XhTableBody>
    </XhTableRoot>
    <span>
      选中：{{
        selection === "all"
          ? "全部"
          : selection.length
            ? selection.join("、")
            : "（无）"
      }}
    </span>
  </div>
</template>

行展开

行上标了 expandable 才认展开把手与左右方向键；详情行占一个真实行号，收起只加 hidden 不卸载内部节点

订单号

金额

▸

XH-2026-0001

¥ 1,280

明细：键盘 ×1、鼠标 ×2

▸

XH-2026-0002

¥ 320

▸

XH-2026-0003

¥ 96

展开：o1

<script setup lang="ts">
import { ref } from "vue";
import {
  XhTableBody,
  XhTableCell,
  XhTableColumnHeader,
  XhTableExpandedRow,
  XhTableExpandTrigger,
  XhTableHeader,
  XhTableRoot,
  XhTableRow,
} from "@xihan-ui/vue";

const columns = [
  { id: "expand", width: "2.5rem" },
  { id: "order", label: "订单号", width: "9rem" },
  { id: "amount", label: "金额" },
];

const orders = [
  { id: "o1", no: "XH-2026-0001", amount: "¥ 1,280", detail: "键盘 ×1、鼠标 ×2" },
  { id: "o2", no: "XH-2026-0002", amount: "¥ 320", detail: "显示器支架 ×1" },
  { id: "o3", no: "XH-2026-0003", amount: "¥ 96", detail: "线材若干" },
];

const rows = orders.map((o) => ({ id: o.id, expandable: true }));

const expanded = ref<string[]>(["o1"]);
</script>

<template>
  <div style="width: 100%; max-width: 560px; display: grid; gap: 12px">
    <XhTableRoot v-model:expanded="expanded" :columns="columns" :rows="rows">
      <XhTableHeader>
        <XhTableRow>
          <XhTableColumnHeader value="expand" />
          <XhTableColumnHeader value="order">订单号</XhTableColumnHeader>
          <XhTableColumnHeader value="amount">金额</XhTableColumnHeader>
        </XhTableRow>
      </XhTableHeader>
      <XhTableBody>
        <template v-for="o in orders" :key="o.id">
          <XhTableRow :value="o.id">
            <XhTableCell value="expand">
              <XhTableExpandTrigger>▸</XhTableExpandTrigger>
            </XhTableCell>
            <XhTableCell value="order">{{ o.no }}</XhTableCell>
            <XhTableCell value="amount">{{ o.amount }}</XhTableCell>
          </XhTableRow>
          <!-- 详情行紧跟它所属的数据行，整行铺开靠 colspan -->
          <XhTableExpandedRow :value="o.id">
            <XhTableCell value="expand" :colspan="3">明细：{{ o.detail }}</XhTableCell>
          </XhTableExpandedRow>
        </template>
      </XhTableBody>
    </XhTableRoot>
    <span>展开：{{ expanded.length ? expanded.join("、") : "（无）" }}</span>
  </div>
</template>

密度

size 只落成 root 的 data-size，换的是单元格纵向内边距与字号；三档并排，差别在行高上

sm 紧凑

姓名

职级

赵一

P6

钱二

P7

孙三

P6

李四

P5

周五

P7

缺省

姓名

职级

赵一

P6

钱二

P7

孙三

P6

李四

P5

周五

P7

lg 宽松

姓名

职级

赵一

P6

钱二

P7

孙三

P6

李四

P5

周五

P7

<script setup lang="ts">
import {
  XhTableBody,
  XhTableCaption,
  XhTableCell,
  XhTableColumnHeader,
  XhTableHeader,
  XhTableRoot,
  XhTableRow,
} from "@xihan-ui/vue";

const columns = [
  { id: "name", label: "姓名" },
  { id: "level", label: "职级" },
];

const members = [
  { id: "u1", name: "赵一", level: "P6" },
  { id: "u2", name: "钱二", level: "P7" },
  { id: "u3", name: "孙三", level: "P6" },
  { id: "u4", name: "李四", level: "P5" },
  { id: "u5", name: "周五", level: "P7" },
];

const rows = members.map((m) => ({ id: m.id }));

// 中间档不传 size，缺省即中密度
const densities = [
  { key: "sm", size: "sm", label: "sm 紧凑" },
  { key: "md", size: undefined, label: "缺省" },
  { key: "lg", size: "lg", label: "lg 宽松" },
];
</script>

<template>
  <div
    style="display: flex; flex-wrap: wrap; gap: 16px; align-items: flex-start"
  >
    <div
      v-for="d in densities"
      :key="d.key"
      style="flex: 1 1 190px; min-width: 190px"
    >
      <XhTableRoot :columns="columns" :rows="rows" :size="d.size">
        <XhTableCaption>{{ d.label }}</XhTableCaption>
        <XhTableHeader>
          <XhTableRow>
            <XhTableColumnHeader
              v-for="col in columns"
              :key="col.id"
              :value="col.id"
            >
              {{ col.label }}
            </XhTableColumnHeader>
          </XhTableRow>
        </XhTableHeader>
        <XhTableBody>
          <XhTableRow v-for="m in members" :key="m.id" :value="m.id">
            <XhTableCell value="name">{{ m.name }}</XhTableCell>
            <XhTableCell value="level">{{ m.level }}</XhTableCell>
          </XhTableRow>
        </XhTableBody>
      </XhTableRoot>
    </div>
  </div>
</template>

空态与加载态

两个状态节点常挂着只靠 hidden 显隐：表体为空且在取数时露加载态，取数完了没有行才露空态

任务

负责人

还没有任务，点「取数」拉一份。

<script setup lang="ts">
import { computed, ref } from "vue";
import {
  XhTableBody,
  XhTableCell,
  XhTableColumnHeader,
  XhTableEmpty,
  XhTableHeader,
  XhTableLoadingState,
  XhTableRoot,
  XhTableRow,
} from "@xihan-ui/vue";

interface Task {
  id: string;
  name: string;
  owner: string;
}

const columns = [
  { id: "name", label: "任务", width: "10rem" },
  { id: "owner", label: "负责人" },
];

const source: Task[] = [
  { id: "t1", name: "构建流水线", owner: "赵一" },
  { id: "t2", name: "组件回归", owner: "钱二" },
  { id: "t3", name: "文档校订", owner: "孙三" },
];

const tasks = ref<Task[]>([]);
const loading = ref(false);
let timer = 0;

function load(): void {
  window.clearTimeout(timer);
  tasks.value = [];
  loading.value = true;
  timer = window.setTimeout(() => {
    tasks.value = source;
    loading.value = false;
  }, 1200);
}

function reset(): void {
  window.clearTimeout(timer);
  tasks.value = [];
  loading.value = false;
}

// 表体为空与否按 rows 推导，不必另写 empty
const rows = computed(() => tasks.value.map((t) => ({ id: t.id })));
</script>

<template>
  <div style="width: 100%; max-width: 480px; display: grid; gap: 12px">
    <div style="display: flex; gap: 8px">
      <button type="button" @click="load">取数</button>
      <button type="button" @click="reset">清空</button>
    </div>

    <XhTableRoot :columns="columns" :rows="rows" :loading="loading">
      <XhTableHeader>
        <XhTableRow>
          <XhTableColumnHeader v-for="col in columns" :key="col.id" :value="col.id">
            {{ col.label }}
          </XhTableColumnHeader>
        </XhTableRow>
      </XhTableHeader>
      <XhTableBody>
        <XhTableRow v-for="t in tasks" :key="t.id" :value="t.id">
          <XhTableCell value="name">{{ t.name }}</XhTableCell>
          <XhTableCell value="owner">{{ t.owner }}</XhTableCell>
        </XhTableRow>
      </XhTableBody>
      <XhTableLoadingState>正在取数…</XhTableLoadingState>
      <XhTableEmpty>还没有任务，点「取数」拉一份。</XhTableEmpty>
    </XhTableRoot>
  </div>
</template>

脚注合计

footer 把行号空间的最后一行留给脚注；脚注单元格不属于任何数据行，也就没有选中与禁用可言

采购清单

条目

数量

金额

键盘

2

¥ 1280

鼠标

3

¥ 447

显示器支架

1

¥ 320

合计

6

¥ 2047

<script setup lang="ts">
import { computed } from "vue";
import {
  XhTableBody,
  XhTableCaption,
  XhTableCell,
  XhTableColumnHeader,
  XhTableFooter,
  XhTableHeader,
  XhTableRoot,
  XhTableRow,
} from "@xihan-ui/vue";

const columns = [
  { id: "item", label: "条目", width: "10rem" },
  { id: "count", label: "数量", width: "5rem" },
  { id: "amount", label: "金额" },
];

const lines = [
  { id: "l1", item: "键盘", count: 2, amount: 1280 },
  { id: "l2", item: "鼠标", count: 3, amount: 447 },
  { id: "l3", item: "显示器支架", count: 1, amount: 320 },
];

const rows = lines.map((l) => ({ id: l.id }));

const totalCount = computed(() => lines.reduce((sum, l) => sum + l.count, 0));
const totalAmount = computed(() => lines.reduce((sum, l) => sum + l.amount, 0));
</script>

<template>
  <div style="width: 100%; max-width: 560px">
    <XhTableRoot :columns="columns" :rows="rows" footer>
      <XhTableCaption>采购清单</XhTableCaption>
      <XhTableHeader>
        <XhTableRow>
          <XhTableColumnHeader v-for="col in columns" :key="col.id" :value="col.id">
            {{ col.label }}
          </XhTableColumnHeader>
        </XhTableRow>
      </XhTableHeader>
      <XhTableBody>
        <XhTableRow v-for="l in lines" :key="l.id" :value="l.id">
          <XhTableCell value="item">{{ l.item }}</XhTableCell>
          <XhTableCell value="count">{{ l.count }}</XhTableCell>
          <XhTableCell value="amount">¥ {{ l.amount }}</XhTableCell>
        </XhTableRow>
      </XhTableBody>
      <XhTableFooter>
        <!-- 脚注行不给 value：它占的是行号空间的最后一行 -->
        <XhTableRow>
          <XhTableCell value="item">合计</XhTableCell>
          <XhTableCell value="count">{{ totalCount }}</XhTableCell>
          <XhTableCell value="amount">¥ {{ totalAmount }}</XhTableCell>
        </XhTableRow>
      </XhTableFooter>
    </XhTableRoot>
  </div>
</template>

表头吸顶与列吸附

root 自己就是那个滚动容器：stickyHeader 钉住表头，列上标 sticky 的钉住那一列

姓名

部门

城市

分机

邮箱

员工 1

平台研发

杭州

8100

member1@example.com

员工 2

前端体验

上海

8101

member2@example.com

员工 3

基础架构

北京

8102

member3@example.com

员工 4

质量保障

成都

8103

member4@example.com

员工 5

平台研发

杭州

8104

member5@example.com

员工 6

前端体验

上海

8105

member6@example.com

员工 7

基础架构

北京

8106

member7@example.com

员工 8

质量保障

成都

8107

member8@example.com

员工 9

平台研发

杭州

8108

member9@example.com

员工 10

前端体验

上海

8109

member10@example.com

员工 11

基础架构

北京

8110

member11@example.com

员工 12

质量保障

成都

8111

member12@example.com

员工 13

平台研发

杭州

8112

member13@example.com

员工 14

前端体验

上海

8113

member14@example.com

员工 15

基础架构

北京

8114

member15@example.com

员工 16

质量保障

成都

8115

member16@example.com

<script setup lang="ts">
import {
  XhTableBody,
  XhTableCell,
  XhTableColumnHeader,
  XhTableHeader,
  XhTableRoot,
  XhTableRow,
} from "@xihan-ui/vue";

// 首列吸附，其余列给足宽度让表格横向溢出，滚起来才看得出钉住的效果
const columns = [
  { id: "name", label: "姓名", width: "7rem", sticky: true },
  { id: "dept", label: "部门", width: "9rem" },
  { id: "city", label: "城市", width: "7rem" },
  { id: "ext", label: "分机", width: "7rem" },
  { id: "mail", label: "邮箱", width: "13rem" },
];

const depts = ["平台研发", "前端体验", "基础架构", "质量保障"];
const cities = ["杭州", "上海", "北京", "成都"];

const members = Array.from({ length: 16 }, (_, i) => ({
  id: `u${i + 1}`,
  name: `员工 ${i + 1}`,
  dept: depts[i % depts.length],
  city: cities[i % cities.length],
  ext: `8${(100 + i).toString()}`,
  mail: `member${i + 1}@example.com`,
}));

const rows = members.map((m) => ({ id: m.id }));
</script>

<template>
  <div style="width: 100%; max-width: 420px">
    <XhTableRoot :columns="columns" :rows="rows" sticky-header>
      <XhTableHeader>
        <XhTableRow>
          <XhTableColumnHeader v-for="col in columns" :key="col.id" :value="col.id">
            {{ col.label }}
          </XhTableColumnHeader>
        </XhTableRow>
      </XhTableHeader>
      <XhTableBody>
        <XhTableRow v-for="m in members" :key="m.id" :value="m.id">
          <XhTableCell value="name">{{ m.name }}</XhTableCell>
          <XhTableCell value="dept">{{ m.dept }}</XhTableCell>
          <XhTableCell value="city">{{ m.city }}</XhTableCell>
          <XhTableCell value="ext">{{ m.ext }}</XhTableCell>
          <XhTableCell value="mail">{{ m.mail }}</XhTableCell>
        </XhTableRow>
      </XhTableBody>
    </XhTableRoot>
  </div>
</template>

单选

selectionMode 给 single：选中集合最多一个元素，点已选中的那行再点一次就清空，焦点行按空格同理

套餐

价格

●

入门版

¥ 0 / 月

●

团队版

¥ 99 / 月

●

企业版

¥ 399 / 月

已选：p2

<script setup lang="ts">
import { ref } from "vue";
import {
  XhTableBody,
  XhTableCell,
  XhTableColumnHeader,
  XhTableHeader,
  XhTableRoot,
  XhTableRow,
  XhTableRowSelectTrigger,
} from "@xihan-ui/vue";

// 单选下全选把手不生效，表头那一格空着即可
const columns = [
  { id: "select", width: "3rem" },
  { id: "plan", label: "套餐", width: "8rem" },
  { id: "price", label: "价格" },
];

const plans = [
  { id: "p1", plan: "入门版", price: "¥ 0 / 月" },
  { id: "p2", plan: "团队版", price: "¥ 99 / 月" },
  { id: "p3", plan: "企业版", price: "¥ 399 / 月" },
];

const rows = plans.map((p) => ({ id: p.id }));

const selection = ref<string[]>(["p2"]);
</script>

<template>
  <div style="width: 100%; max-width: 480px; display: grid; gap: 12px">
    <XhTableRoot
      v-model:selection="selection"
      :columns="columns"
      :rows="rows"
      selection-mode="single"
    >
      <XhTableHeader>
        <XhTableRow>
          <XhTableColumnHeader value="select" />
          <XhTableColumnHeader value="plan">套餐</XhTableColumnHeader>
          <XhTableColumnHeader value="price">价格</XhTableColumnHeader>
        </XhTableRow>
      </XhTableHeader>
      <XhTableBody>
        <XhTableRow v-for="p in plans" :key="p.id" :value="p.id">
          <XhTableCell value="select">
            <XhTableRowSelectTrigger>●</XhTableRowSelectTrigger>
          </XhTableCell>
          <XhTableCell value="plan">{{ p.plan }}</XhTableCell>
          <XhTableCell value="price">{{ p.price }}</XhTableCell>
        </XhTableRow>
      </XhTableBody>
    </XhTableRoot>
    <span>已选：{{ selection.length ? selection.join("、") : "（无）" }}</span>
  </div>
</template>

跨列单元格

colspan 从它自己那一列往后算，报成 aria-colspan；1 与省略同义，所以只在真跨了列时写

交付单量

小组

上半年

下半年

平台研发

42

51

前端体验

36

39

全年

168

<script setup lang="ts">
import {
  XhTableBody,
  XhTableCaption,
  XhTableCell,
  XhTableColumnHeader,
  XhTableHeader,
  XhTableRoot,
  XhTableRow,
} from "@xihan-ui/vue";

const columns = [
  { id: "team", label: "小组", width: "8rem" },
  { id: "h1", label: "上半年" },
  { id: "h2", label: "下半年" },
];

const teams = [
  { id: "t1", team: "平台研发", h1: "42", h2: "51" },
  { id: "t2", team: "前端体验", h1: "36", h2: "39" },
];

// 汇总行也占一个行号，只是它那格横跨了两列
const rows = [...teams.map((t) => ({ id: t.id })), { id: "sum" }];
</script>

<template>
  <div style="width: 100%; max-width: 520px">
    <XhTableRoot :columns="columns" :rows="rows">
      <XhTableCaption>交付单量</XhTableCaption>
      <XhTableHeader>
        <XhTableRow>
          <XhTableColumnHeader v-for="col in columns" :key="col.id" :value="col.id">
            {{ col.label }}
          </XhTableColumnHeader>
        </XhTableRow>
      </XhTableHeader>
      <XhTableBody>
        <XhTableRow v-for="t in teams" :key="t.id" :value="t.id">
          <XhTableCell value="team">{{ t.team }}</XhTableCell>
          <XhTableCell value="h1">{{ t.h1 }}</XhTableCell>
          <XhTableCell value="h2">{{ t.h2 }}</XhTableCell>
        </XhTableRow>
        <XhTableRow value="sum">
          <XhTableCell value="team">全年</XhTableCell>
          <!-- 从 h1 起跨两列，这一行因此只写两个格子 -->
          <XhTableCell value="h1" :colspan="2">168</XhTableCell>
        </XhTableRow>
      </XhTableBody>
    </XhTableRoot>
  </div>
</template>

单元格就地编辑

表体的方向键与 Home/End 是挂在 body 上的冒泡监听，可编辑控件上掐断冒泡这些键就回归输入框自己

采购清单

条目

数量

备注

键盘

鼠标

显示器支架

合计 6 件

<script setup lang="ts">
import { ref } from "vue";
import {
  XhTableBody,
  XhTableCaption,
  XhTableCell,
  XhTableColumnHeader,
  XhTableHeader,
  XhTableRoot,
  XhTableRow,
} from "@xihan-ui/vue";

const columns = [
  { id: "item", label: "条目", width: "9rem" },
  { id: "count", label: "数量", width: "6rem" },
  { id: "note", label: "备注" },
];

const lines = ref([
  { id: "l1", item: "键盘", count: 2, note: "机械轴" },
  { id: "l2", item: "鼠标", count: 3, note: "无线" },
  { id: "l3", item: "显示器支架", count: 1, note: "" },
]);

// 行序不随编辑变化，rows 取一次即可
const rows = lines.value.map((line) => ({ id: line.id }));

// Escape 把焦点交还所在行，表体的方向键随即恢复
function onEditKeydown(event: KeyboardEvent): void {
  if (event.key !== "Escape") return;
  const input = event.currentTarget as HTMLElement;
  input.closest<HTMLElement>("[data-part='row']")?.focus();
}
</script>

<template>
  <div style="width: 100%; max-width: 560px; display: grid; gap: 12px">
    <XhTableRoot :columns="columns" :rows="rows">
      <XhTableCaption>采购清单</XhTableCaption>
      <XhTableHeader>
        <XhTableRow>
          <XhTableColumnHeader v-for="col in columns" :key="col.id" :value="col.id">
            {{ col.label }}
          </XhTableColumnHeader>
        </XhTableRow>
      </XhTableHeader>
      <XhTableBody>
        <XhTableRow v-for="line in lines" :key="line.id" :value="line.id">
          <XhTableCell value="item">{{ line.item }}</XhTableCell>
          <XhTableCell value="count">
            <!-- keydown 掐断冒泡：不然上下键与 Home/End 会被表体收走去搬焦点行 -->
            <input
              v-model.number="line.count"
              type="number"
              min="0"
              :aria-label="`${line.item} 数量`"
              style="inline-size: 100%; min-inline-size: 0"
              @keydown.stop="onEditKeydown"
            />
          </XhTableCell>
          <XhTableCell value="note">
            <input
              v-model="line.note"
              type="text"
              placeholder="可以打空格"
              :aria-label="`${line.item} 备注`"
              style="inline-size: 100%; min-inline-size: 0"
              @keydown.stop="onEditKeydown"
            />
          </XhTableCell>
        </XhTableRow>
      </XhTableBody>
    </XhTableRoot>
    <span>
      合计 {{ lines.reduce((sum, line) => sum + (line.count || 0), 0) }} 件
    </span>
  </div>
</template>

多行表头与表头分组

表头写几行就是几行；分组格的跨列数与两行表头的行号由标记自报，columns 仍只登记叶子列

季度交付单量

上半年

下半年

小组

Q1

Q2

Q3

Q4

平台研发

12

15

18

21

前端体验

9

11

14

16

基础架构

7

8

10

12

<script setup lang="ts">
import {
  XhTableBody,
  XhTableCaption,
  XhTableCell,
  XhTableColumnHeader,
  XhTableHeader,
  XhTableRoot,
  XhTableRow,
} from "@xihan-ui/vue";

// 只有叶子列进 columns：列号与列总数按它算
const columns = [
  { id: "team", label: "小组", width: "8rem" },
  { id: "q1", label: "Q1", width: "5rem" },
  { id: "q2", label: "Q2", width: "5rem" },
  { id: "q3", label: "Q3", width: "5rem" },
  { id: "q4", label: "Q4", width: "5rem" },
];

const teams = [
  { id: "t1", team: "平台研发", q1: 12, q2: 15, q3: 18, q4: 21 },
  { id: "t2", team: "前端体验", q1: 9, q2: 11, q3: 14, q4: 16 },
  { id: "t3", team: "基础架构", q1: 7, q2: 8, q3: 10, q4: 12 },
];

const rows = teams.map((t) => ({ id: t.id }));

// 分组格宽度取两列之和，伸缩系数也翻倍，两行表头才对得齐
const groupStyle = { inlineSize: "10rem", flexGrow: 2 };
</script>

<template>
  <div style="width: 100%; max-width: 620px">
    <!-- 表头占两行，行号空间比缺省的多一行，总行数在这里自报 -->
    <XhTableRoot :columns="columns" :rows="rows" :aria-rowcount="teams.length + 2">
      <XhTableCaption>季度交付单量</XhTableCaption>
      <XhTableHeader>
        <XhTableRow>
          <XhTableColumnHeader value="team" />
          <XhTableColumnHeader value="q1" :style="groupStyle" :aria-colspan="2">
            上半年
          </XhTableColumnHeader>
          <XhTableColumnHeader value="q3" :style="groupStyle" :aria-colspan="2">
            下半年
          </XhTableColumnHeader>
        </XhTableRow>
        <!-- 第二行表头自报行号：缺省那条恒为 1 -->
        <XhTableRow :aria-rowindex="2">
          <XhTableColumnHeader v-for="col in columns" :key="col.id" :value="col.id">
            {{ col.label }}
          </XhTableColumnHeader>
        </XhTableRow>
      </XhTableHeader>
      <XhTableBody>
        <!-- 数据行也往后挪一行 -->
        <XhTableRow
          v-for="(t, i) in teams"
          :key="t.id"
          :value="t.id"
          :aria-rowindex="i + 3"
        >
          <XhTableCell value="team">{{ t.team }}</XhTableCell>
          <XhTableCell value="q1">{{ t.q1 }}</XhTableCell>
          <XhTableCell value="q2">{{ t.q2 }}</XhTableCell>
          <XhTableCell value="q3">{{ t.q3 }}</XhTableCell>
          <XhTableCell value="q4">{{ t.q4 }}</XhTableCell>
        </XhTableRow>
      </XhTableBody>
    </XhTableRoot>
  </div>
</template>

列过滤

过滤把手是列标题里的一段内容，过滤结果就是宿主算好后传进来的那份 rows；表头是表体的兄弟，把手上的按键不会被表体收走

姓名

部门

城市

赵一

平台研发

杭州

钱二

前端体验

上海

孙三

基础架构

北京

李四

前端体验

杭州

周五

质量保障

成都

吴六

平台研发

上海

命中 6 / 6 人 · 部门：不限 · 城市：不限

<script setup lang="ts">
import { computed, ref } from "vue";
import {
  XhPopoverContent,
  XhPopoverPositioner,
  XhPopoverRoot,
  XhPopoverTitle,
  XhPopoverTrigger,
  XhTableBody,
  XhTableCell,
  XhTableColumnHeader,
  XhTableEmpty,
  XhTableHeader,
  XhTableRoot,
  XhTableRow,
} from "@xihan-ui/vue";

const columns = [
  { id: "name", label: "姓名", width: "7rem" },
  { id: "dept", label: "部门", width: "9rem" },
  { id: "city", label: "城市" },
];

const members = [
  { id: "u1", name: "赵一", dept: "平台研发", city: "杭州" },
  { id: "u2", name: "钱二", dept: "前端体验", city: "上海" },
  { id: "u3", name: "孙三", dept: "基础架构", city: "北京" },
  { id: "u4", name: "李四", dept: "前端体验", city: "杭州" },
  { id: "u5", name: "周五", dept: "质量保障", city: "成都" },
  { id: "u6", name: "吴六", dept: "平台研发", city: "上海" },
];

const deptOptions = [...new Set(members.map((m) => m.dept))];
const cityOptions = [...new Set(members.map((m) => m.city))];

// 过滤态由宿主持有，一个都没勾就是不过滤
const deptFilter = ref<string[]>([]);
const cityFilter = ref<string[]>([]);

const visible = computed(() =>
  members.filter(
    (m) =>
      (deptFilter.value.length === 0 || deptFilter.value.includes(m.dept)) &&
      (cityFilter.value.length === 0 || cityFilter.value.includes(m.city))
  )
);

// 行序的事实源跟着过滤结果走
const rows = computed(() => visible.value.map((m) => ({ id: m.id })));

const menuStyle = { display: "grid", gap: "6px", minInlineSize: "8rem" };
const optionStyle = { display: "flex", alignItems: "center", gap: "6px" };
</script>

<template>
  <div style="width: 100%; max-width: 560px; display: grid; gap: 12px">
    <XhTableRoot :columns="columns" :rows="rows">
      <XhTableHeader>
        <XhTableRow>
          <XhTableColumnHeader value="name">姓名</XhTableColumnHeader>
          <XhTableColumnHeader value="dept">
            部门
            <XhPopoverRoot placement="bottom-start" size="sm">
              <XhPopoverTrigger aria-label="按部门过滤">
                {{ deptFilter.length ? "▾●" : "▾" }}
              </XhPopoverTrigger>
              <XhPopoverPositioner>
                <XhPopoverContent>
                  <XhPopoverTitle>按部门过滤</XhPopoverTitle>
                  <div :style="menuStyle">
                    <label v-for="d in deptOptions" :key="d" :style="optionStyle">
                      <input v-model="deptFilter" type="checkbox" :value="d" />
                      {{ d }}
                    </label>
                    <button type="button" @click="deptFilter = []">不限</button>
                  </div>
                </XhPopoverContent>
              </XhPopoverPositioner>
            </XhPopoverRoot>
          </XhTableColumnHeader>
          <XhTableColumnHeader value="city">
            城市
            <XhPopoverRoot placement="bottom-start" size="sm">
              <XhPopoverTrigger aria-label="按城市过滤">
                {{ cityFilter.length ? "▾●" : "▾" }}
              </XhPopoverTrigger>
              <XhPopoverPositioner>
                <XhPopoverContent>
                  <XhPopoverTitle>按城市过滤</XhPopoverTitle>
                  <div :style="menuStyle">
                    <label v-for="c in cityOptions" :key="c" :style="optionStyle">
                      <input v-model="cityFilter" type="checkbox" :value="c" />
                      {{ c }}
                    </label>
                    <button type="button" @click="cityFilter = []">不限</button>
                  </div>
                </XhPopoverContent>
              </XhPopoverPositioner>
            </XhPopoverRoot>
          </XhTableColumnHeader>
        </XhTableRow>
      </XhTableHeader>
      <XhTableBody>
        <XhTableRow v-for="m in visible" :key="m.id" :value="m.id">
          <XhTableCell value="name">{{ m.name }}</XhTableCell>
          <XhTableCell value="dept">{{ m.dept }}</XhTableCell>
          <XhTableCell value="city">{{ m.city }}</XhTableCell>
        </XhTableRow>
      </XhTableBody>
      <XhTableEmpty>这组条件下没有人。</XhTableEmpty>
    </XhTableRoot>
    <span>
      命中 {{ visible.length }} / {{ members.length }} 人 · 部门：{{
        deptFilter.length ? deptFilter.join("、") : "不限"
      }}
      · 城市：{{ cityFilter.length ? cityFilter.join("、") : "不限" }}
    </span>
  </div>
</template>

树形表格

rows 按契约就是一条已摊平的可见行序列：层级三件套逐行自报，缩进落在首格的内边距上

组织

负责人

▾ 研发中心

赵一

▸ 前端组

钱二

服务端组

周五

▸ 运维中心

吴六

展开：rd

<script setup lang="ts">
import { computed, ref } from "vue";
import {
  XhTableBody,
  XhTableCell,
  XhTableColumnHeader,
  XhTableHeader,
  XhTableRoot,
  XhTableRow,
} from "@xihan-ui/vue";

interface Node {
  id: string;
  label: string;
  owner: string;
  children?: Node[];
}

const columns = [
  { id: "name", label: "组织", width: "13rem" },
  { id: "owner", label: "负责人" },
];

const tree: Node[] = [
  {
    id: "rd",
    label: "研发中心",
    owner: "赵一",
    children: [
      {
        id: "rd-web",
        label: "前端组",
        owner: "钱二",
        children: [
          { id: "rd-web-1", label: "组件库", owner: "孙三" },
          { id: "rd-web-2", label: "控制台", owner: "李四" },
        ],
      },
      { id: "rd-api", label: "服务端组", owner: "周五" },
    ],
  },
  {
    id: "ops",
    label: "运维中心",
    owner: "吴六",
    children: [{ id: "ops-1", label: "值班平台", owner: "郑七" }],
  },
];

const expanded = ref<string[]>(["rd"]);

interface FlatRow {
  id: string;
  label: string;
  owner: string;
  level: number;
  pos: number;
  size: number;
  branch: boolean;
  open: boolean;
}

// 收起分支的子树整段不出现在序列里，行号因此永远连续
const flat = computed<FlatRow[]>(() => {
  const out: FlatRow[] = [];
  const walk = (nodes: Node[], level: number): void => {
    nodes.forEach((node, i) => {
      const branch = !!node.children?.length;
      const open = branch && expanded.value.includes(node.id);
      out.push({
        id: node.id,
        label: node.label,
        owner: node.owner,
        level,
        pos: i + 1,
        size: nodes.length,
        branch,
        open,
      });
      if (open) walk(node.children!, level + 1);
    });
  };
  walk(tree, 1);
  return out;
});

const rows = computed(() => flat.value.map((row) => ({ id: row.id })));

function toggle(id: string): void {
  expanded.value = expanded.value.includes(id)
    ? expanded.value.filter((v) => v !== id)
    : [...expanded.value, id];
}

// 焦点行是父级时左右方向键切换开合；连接层遇到不可展开的行原样放行这两个键
function onBodyKeydown(event: KeyboardEvent, focused: string | null): void {
  if (focused == null) return;
  const row = flat.value.find((r) => r.id === focused);
  if (!row?.branch) return;
  const wantOpen = event.key === "ArrowRight";
  const wantClose = event.key === "ArrowLeft";
  if ((wantOpen && !row.open) || (wantClose && row.open)) {
    event.preventDefault();
    toggle(focused);
  }
}

const twistyStyle = {
  display: "inline-flex",
  flex: "none",
  alignItems: "center",
  justifyContent: "center",
  inlineSize: "1rem",
  blockSize: "1rem",
  cursor: "pointer",
};
</script>

<template>
  <div style="width: 100%; max-width: 520px; display: grid; gap: 12px">
    <!-- 行有层级，root 报 treegrid -->
    <XhTableRoot v-slot="{ focusedRow }" :columns="columns" :rows="rows" role="treegrid">
      <XhTableHeader>
        <XhTableRow>
          <XhTableColumnHeader v-for="col in columns" :key="col.id" :value="col.id">
            {{ col.label }}
          </XhTableColumnHeader>
        </XhTableRow>
      </XhTableHeader>
      <XhTableBody @keydown="onBodyKeydown($event, focusedRow)">
        <XhTableRow
          v-for="row in flat"
          :key="row.id"
          :value="row.id"
          :aria-level="row.level"
          :aria-posinset="row.pos"
          :aria-setsize="row.size"
          :aria-expanded="row.branch ? String(row.open) : undefined"
        >
          <!-- 缩进是首格的内边距，与层级号同源 -->
          <XhTableCell
            value="name"
            :style="{ paddingInlineStart: `${row.level * 16}px` }"
          >
            <!-- 开合箭头只服务指针，键盘那一路走左右方向键，因此对读屏隐藏 -->
            <span
              v-if="row.branch"
              aria-hidden="true"
              :style="twistyStyle"
              @click="toggle(row.id)"
            >
              {{ row.open ? "▾" : "▸" }}
            </span>
            <span v-else aria-hidden="true" :style="twistyStyle" />
            {{ row.label }}
          </XhTableCell>
          <XhTableCell value="owner">{{ row.owner }}</XhTableCell>
        </XhTableRow>
      </XhTableBody>
    </XhTableRoot>
    <span>展开：{{ expanded.length ? expanded.join("、") : "（无）" }}</span>
  </div>
</template>

拖拽调列宽

列宽的事实源是 columns[].width，把手只是列标题里的一段标记：按下量起点，移动改宽度，连接层随即写进列标题与整列单元格

拖动列标题右侧那条竖线

姓名

部门

城市

赵一

平台研发

杭州

钱二

前端体验

上海

孙三

基础架构

北京

李四

质量保障

成都

列宽：姓名 120px · 部门 150px · 城市 120px

<script setup lang="ts">
import { ref } from "vue";
import {
  XhTableBody,
  XhTableCaption,
  XhTableCell,
  XhTableColumnHeader,
  XhTableHeader,
  XhTableRoot,
  XhTableRow,
} from "@xihan-ui/vue";

// 列宽写成数字即按 px 处理
const columns = ref([
  { id: "name", label: "姓名", width: 120 },
  { id: "dept", label: "部门", width: 150 },
  { id: "city", label: "城市", width: 120 },
]);

const members = [
  { id: "u1", name: "赵一", dept: "平台研发", city: "杭州" },
  { id: "u2", name: "钱二", dept: "前端体验", city: "上海" },
  { id: "u3", name: "孙三", dept: "基础架构", city: "北京" },
  { id: "u4", name: "李四", dept: "质量保障", city: "成都" },
];

const rows = members.map((m) => ({ id: m.id }));

const MIN_WIDTH = 72;

let grabbed: { id: string; startX: number; startWidth: number } | null = null;

function onGrab(event: PointerEvent, id: string): void {
  const col = columns.value.find((c) => c.id === id);
  if (!col) return;
  grabbed = { id, startX: event.clientX, startWidth: col.width };
  // 捕获指针：手滑出把手后的 move / up 仍送到这里
  (event.currentTarget as HTMLElement).setPointerCapture(event.pointerId);
  event.preventDefault();
}

function onDrag(event: PointerEvent): void {
  if (!grabbed) return;
  const col = columns.value.find((c) => c.id === grabbed!.id);
  if (!col) return;
  col.width = Math.max(MIN_WIDTH, grabbed.startWidth + event.clientX - grabbed.startX);
}

function onRelease(): void {
  grabbed = null;
}

const handleStyle = {
  flex: "none",
  alignSelf: "stretch",
  inlineSize: "6px",
  cursor: "col-resize",
  background: "var(--xh-border-default)",
  touchAction: "none",
};
</script>

<template>
  <div style="width: 100%; max-width: 560px; display: grid; gap: 12px">
    <XhTableRoot :columns="columns" :rows="rows">
      <XhTableCaption>拖动列标题右侧那条竖线</XhTableCaption>
      <XhTableHeader>
        <XhTableRow>
          <XhTableColumnHeader v-for="col in columns" :key="col.id" :value="col.id">
            <span style="flex: 1; overflow: hidden; text-overflow: ellipsis">
              {{ col.label }}
            </span>
            <!-- 把手与排序把手是兄弟节点，拖它不会连带触发排序 -->
            <span
              aria-hidden="true"
              :style="handleStyle"
              @pointerdown="onGrab($event, col.id)"
              @pointermove="onDrag"
              @pointerup="onRelease"
              @pointercancel="onRelease"
            />
          </XhTableColumnHeader>
        </XhTableRow>
      </XhTableHeader>
      <XhTableBody>
        <XhTableRow v-for="m in members" :key="m.id" :value="m.id">
          <XhTableCell value="name">{{ m.name }}</XhTableCell>
          <XhTableCell value="dept">{{ m.dept }}</XhTableCell>
          <XhTableCell value="city">{{ m.city }}</XhTableCell>
        </XhTableRow>
      </XhTableBody>
    </XhTableRoot>
    <span>列宽：{{ columns.map((c) => `${c.label} ${c.width}px`).join(" · ") }}</span>
  </div>
</template>

只渲窗口内的行

全量 rows 照常交给 root（那只是行序与行号的元信息，不产生 DOM），标记里只渲可见那一段，首尾用两块空白撑出真实滚动高度

编号

姓名

部门

#1

员工 1

平台研发

#2

员工 2

前端体验

#3

员工 3

基础架构

#4

员工 4

质量保障

#5

员工 5

平台研发

#6

员工 6

前端体验

#7

员工 7

基础架构

#8

员工 8

质量保障

#9

员工 9

平台研发

#10

员工 10

前端体验

#11

员工 11

基础架构

#12

员工 12

质量保障

#13

员工 13

平台研发

#14

员工 14

前端体验

#15

员工 15

基础架构

#16

员工 16

质量保障

#17

员工 17

平台研发

#18

员工 18

前端体验

共 2000 行，此刻在 DOM 里的是第 1 – 18 行

<script setup lang="ts">
import { computed, ref } from "vue";
import {
  XhTableBody,
  XhTableCell,
  XhTableColumnHeader,
  XhTableHeader,
  XhTableRoot,
  XhTableRow,
} from "@xihan-ui/vue";

const columns = [
  { id: "no", label: "编号", width: "6rem" },
  { id: "name", label: "姓名", width: "8rem" },
  { id: "dept", label: "部门" },
];

const depts = ["平台研发", "前端体验", "基础架构", "质量保障"];

const people = Array.from({ length: 2000 }, (_, i) => ({
  id: `u${i + 1}`,
  no: `#${i + 1}`,
  name: `员工 ${i + 1}`,
  dept: depts[i % depts.length],
}));

// 行号与总数按全量算，与渲染了哪几行无关
const rows = people.map((p) => ({ id: p.id }));

// 行高写死才算得出窗口；上下各多渲几行做缓冲
const ROW_H = 36;
const WINDOW = 18;
const OVERSCAN = 4;

const start = ref(0);
const end = computed(() => Math.min(people.length, start.value + WINDOW));
const visible = computed(() => people.slice(start.value, end.value));

const bodyStyle = computed(() => ({
  paddingBlockStart: `${start.value * ROW_H}px`,
  paddingBlockEnd: `${(people.length - end.value) * ROW_H}px`,
}));

const rowStyle = { blockSize: `${ROW_H}px` };

function onScroll(event: Event): void {
  const top = (event.target as HTMLElement).scrollTop;
  const first = Math.floor(top / ROW_H) - OVERSCAN;
  start.value = Math.min(Math.max(0, first), Math.max(0, people.length - WINDOW));
}
</script>

<template>
  <div style="width: 100%; max-width: 520px; display: grid; gap: 12px">
    <!-- root 自己就是那个滚动容器，滚动量直接从它身上读 -->
    <XhTableRoot :columns="columns" :rows="rows" sticky-header @scroll="onScroll">
      <XhTableHeader>
        <XhTableRow :style="rowStyle">
          <XhTableColumnHeader v-for="col in columns" :key="col.id" :value="col.id">
            {{ col.label }}
          </XhTableColumnHeader>
        </XhTableRow>
      </XhTableHeader>
      <XhTableBody :style="bodyStyle">
        <XhTableRow v-for="p in visible" :key="p.id" :value="p.id" :style="rowStyle">
          <XhTableCell value="no">{{ p.no }}</XhTableCell>
          <XhTableCell value="name">{{ p.name }}</XhTableCell>
          <XhTableCell value="dept">{{ p.dept }}</XhTableCell>
        </XhTableRow>
      </XhTableBody>
    </XhTableRoot>
    <span>
      共 {{ people.length }} 行，此刻在 DOM 里的是第 {{ start + 1 }} –
      {{ end }} 行
    </span>
  </div>
</template>

产物

层	值
自定义元素	<xh-table>
Vue 组件	XhTableBody XhTableCaption XhTableCell XhTableColumnHeader XhTableEmpty XhTableExpandTrigger XhTableExpandedRow XhTableFooter XhTableHeader XhTableLoadingState XhTableRoot XhTableRow XhTableRowSelectTrigger XhTableSelectAllTrigger XhTableSortTrigger
组合式函数	useTable
状态机	tableMachine
皮肤	@xihan-ui/styles/table.css

解剖

部件名即 data-part 属性值，也是皮肤的选择器。加粗的是必备部件，不渲染它组件不工作（Web Components 适配器会在诊断通道上报 wc.missing-part）。

data-scope="table"：root · header · body · footer · row · column-header · cell · caption · select-all-trigger · row-select-trigger · sort-trigger · expand-trigger · expanded-row · empty · loading-state

Props

属性	类型	必填	说明
columns	TableColumnDef[]		列定义，列号与列总数的唯一事实源。缺省为空表。
rows	TableRowDef[]		行定义，行序与行号的唯一事实源。缺省为空表。
sort	TableSortDescriptor[]		排序链。给定即受控：cell 直读 prop，写只发 onSortChange 不落内部值。
defaultSort	TableSortDescriptor[]
selection	TableSelection		选中集合。给定即受控，语义同上。
defaultSelection	TableSelection
expanded	string[]		展开集合。给定即受控，语义同上。
defaultExpanded	string[]
selectionMode	TableSelectionMode		默认 none：不声明则没有选择机制，行也不报 aria-selected。
loading	boolean		数据在路上：root 报 aria-busy，表体为空时加载态节点显形。
empty	boolean		显式声明表体为空；缺省按 rows 是否为空推导。
stickyHeader	boolean		表头吸顶：只落 data-sticky，钉住的实现归皮肤。
footer	boolean		表格带脚注行。行号空间的最后一行留给它，aria-rowcount 也把它算进去。
loop	boolean		上下键走到首尾是否回绕，默认 false。
dir	Direction		文字方向，默认 ltr；只对调左右方向键的「展开/收起」语义。
size	Size		密度：sm / md / lg。只换单元格的纵向内边距与字号，列宽算法不受影响。
onSortChange	(details: TableSortChangeDetails) => void
onSelectionChange	(details: TableSelectionChangeDetails) => void
onExpandedChange	(details: TableExpandedChangeDetails) => void

状态机

状态：idle

事件：SORT.SET · SORT.TOGGLE · SELECTION.SET · ROW.SELECT · SELECTION.ALL_TOGGLE · EXPANDED.SET · ROW.EXPAND · ROW.COLLAPSE · ROW.EXPAND_TOGGLE · ROW.FOCUS · TABLE.BLUR

connect API

useTable 产出的对象。getXxxProps() 铺到对应部件的宿主元素上，其余是可读状态与操作入口。

成员	类型	说明
columns	readonly TableColumnDef[]	作者给的列定义。
rows	readonly TableRowDef[]	作者给的行定义。
visibleRows	readonly TableVisibleRow[]	展开摊平后的可见行序列（详情行插在它所属数据行之后）。
sort	TableSortDescriptor[]
selection	TableSelection
selectionState	TableSelectionState	全选把手的三态，只按可选行（未禁用）算。
selectionMode	TableSelectionMode
expandedValue	string[]
focusedRow	string | null	焦点锚点；焦点不在表体里时为 null。
loading	boolean
empty	boolean	表体为空（显式声明或 rows 为空）。
rowCount	number	aria-rowcount：表头行 + 可见行 + 脚注行。
columnCount	number	aria-colcount：列定义的条数。
isSelected	(value: string) => boolean
isExpanded	(value: string) => boolean
sortDirection	(value: string) => TableSortDirection | null	该列当前的排序方向；不参与排序时为 null。
sortPriority	(value: string) => number	该列在排序链里的优先级，1 起算；不参与排序时为 0。
setSort	(next: TableSortDescriptor[]) => void
toggleSort	(value: string, options?: { append?: boolean }) => void
setSelection	(next: TableSelection) => void
selectRow	(value: string) => void
toggleSelectAll	() => void
setExpandedValue	(next: string[]) => void
expandRow	(value: string) => void
collapseRow	(value: string) => void
toggleExpandRow	(value: string) => void
getRootProps	() => T['element']
getCaptionProps	() => T['element']
getHeaderProps	() => T['element']
getBodyProps	() => T['element']
getFooterProps	() => T['element']
getHeaderRowProps	() => T['element']	表头那一行：恒占行号空间的第 1 行。
getFooterRowProps	() => T['element']	脚注那一行：占行号空间的最后一行。
getRowProps	(props: TableRowProps) => T['element']
getColumnHeaderProps	(props: TableColumnProps) => T['element']
getCellProps	(props: TableCellProps) => T['element']
getSelectAllTriggerProps	() => T['element']
getRowSelectTriggerProps	(props: TableRowProps) => T['element']
getSortTriggerProps	(props: TableColumnProps) => T['element']
getExpandTriggerProps	(props: TableRowProps) => T['element']
getExpandedRowProps	(props: TableRowProps) => T['element']
getEmptyProps	() => T['element']
getLoadingStateProps	() => T['element']

键盘

规格出处：W3C APG

按键	生效条件	行为
Tab / Shift+Tab	focus outside the table body	表体只占一个 Tab 位：焦点进入锚点行，无锚点时先落 body 再由它转投；再按一次 Tab 整体离开表体
ArrowDown	focus in table body	焦点移到下一个可见数据行（禁用行跳过；详情行不是落点；loop 默认关，末行不回绕）
ArrowUp	focus in table body	焦点移到上一个可见数据行（禁用行跳过；loop 默认关，首行不回绕）
Home	focus in table body	焦点移到首个可见数据行
End	focus in table body	焦点移到末个可见数据行
Space	focus on row, selectionMode 非 none 且该行未禁用	切换焦点行的选中（单选替换、复选增删）；选不动时不吞这个键，页面照常滚动
ArrowRight	focus on 可展开且收起的行（dir=rtl 时改由 ArrowLeft 承担）	就地展开当前行，焦点不动；不可展开、已展开或禁用的行上什么都不做且不吞键
ArrowLeft	focus on 可展开且已展开的行（dir=rtl 时改由 ArrowRight 承担）	就地收起当前行，焦点不动；其余情形什么都不做且不吞键
Enter / Space	focus on sort-trigger, 该列 sortable	排序方向按 升序 → 降序 → 不排序 循环；按住 Shift 是追加到排序链而不是替换整条链
Enter / Space	focus on select-all-trigger, selectionMode=multiple	当前可选行全选中就整段清空，否则整段选上；三态由 aria-checked 报出（半选为 mixed）