x-next 1.12.0 → 1.14.0

package/AI_USAGE/components/table.md

@@ -0,0 +1,1414 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Table AI 使用
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+先读 [通用接入](../core.md)。公开导出：`Table, TableColumn, Tbody, Td, Th, Thead, Tr`；主要模型：v-model:selected-keys、v-model:expanded-keys。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./table-api.md)，包含本组件族全部子组件和别名。
+
+按需样式：`x-next/style/table`（包含 base.css、button.css、empty.css、form-checkbox.css、form-input.css、form-input-number.css、form-radio.css、form-select.css、pagination.css、scrollbar-v2.css、spin.css、table.css、trigger.css、tooltip.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+## 场景用法
+
+以下示例从本地 `src/docs/components/table.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./table-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于数据收集展示、分析整理和操作处理，适合中后台列表、配置项矩阵、数据明细和可批量处理的记录集合。
+
+
+### 何时使用
+
+- 需要展示结构化数据，并支持排序、筛选、分页、滚动或固定列。
+- 需要对数据行进行选择、展开、拖拽、合并或汇总。
+- 需要通过插槽或渲染函数定制表头、单元格、空态、分页两侧内容或内部表格元素。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Table as XTable } from 'x-next';
+import type { TableColumnData } from 'x-next';
+
+const columns: TableColumnData[] = [
+  { title: '名称', dataIndex: 'name' },
+  { title: '类型', dataIndex: 'type' },
+  { title: '状态', dataIndex: 'status' },
+];
+const data = [
+  { key: '1', name: 'Button', type: '通用', status: '稳定' },
+  { key: '2', name: 'Select', type: '表单', status: '维护中' },
+  { key: '3', name: 'Table', type: '数据展示', status: '改造中' },
+];
+</script>
+<template>
+<XTable :columns="columns" :data="data" />
+</template>
+```
+
+### 声明式列
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Table as XTable, TableColumn as XTableColumn } from 'x-next';
+
+const data = [
+  { key: '1', name: 'Button', status: '稳定' },
+  { key: '2', name: 'Table', status: '维护中' },
+];
+</script>
+<template>
+<XTable :data="data" :pagination="false">
+    <XTableColumn title="名称" data-index="name" />
+    <XTableColumn title="状态" data-index="status" />
+  </XTable>
+</template>
+```
+
+### 尺寸和边框
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Table as XTable } from 'x-next';
+import type { TableColumnData, TableData } from 'x-next';
+
+const sizes = ['mini', 'small', 'medium', 'large'] as const;
+const columns: TableColumnData[] = [
+  { title: '规格', dataIndex: 'name' },
+  { title: '说明', dataIndex: 'desc' },
+];
+
+const data: TableData[] = [
+  { key: '1', name: 'large', desc: '默认尺寸' },
+  { key: '2', name: 'small', desc: '紧凑展示' },
+];
+</script>
+<template>
+<XTable v-for="size in sizes" :key="size" :columns="columns" :data="data" :size="size" :pagination="false" />
+  <XTable
+    :columns="columns"
+    :data="data"
+    size="mini"
+    :bordered="{ wrapper: true, cell: true }"
+    :pagination="false"
+  />
+</template>
+```
+
+### 行选择器
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { Table as XTable } from 'x-next';
+import type { TableColumnData, TableData } from 'x-next';
+
+const selectedKeys = ref<(string | number)[]>(['1', '2']);
+
+const columns: TableColumnData[] = [
+  { title: '姓名', dataIndex: 'name', width: 140 },
+  { title: '薪资', dataIndex: 'salary', width: 120 },
+  { title: '城市', dataIndex: 'city', width: 120 },
+  { title: '邮箱', dataIndex: 'email', width: 220 },
+];
+
+const data: TableData[] = [
+  { key: '1', name: 'Jane', salary: 23000, city: 'London', email: 'jane@example.com' },
+  { key: '2', name: 'Alisa', salary: 25000, city: 'Paris', email: 'alisa@example.com' },
+  { key: '3', name: 'Kevin', salary: 22000, city: 'London', email: 'kevin@example.com', disabled: true },
+  { key: '4', name: 'Ed', salary: 17000, city: 'Tokyo', email: 'ed@example.com' },
+];
+</script>
+<template>
+<XTable
+    v-model:selected-keys="selectedKeys"
+    :columns="columns"
+    :data="data"
+    :row-selection="{ type: 'checkbox', showCheckedAll: true, onlyCurrent: false }"
+    :pagination="{ pageSize: 3 }"
+  />
+</template>
+```
+
+### 单选
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { Table as XTable } from 'x-next';
+import type { TableColumnData, TableData } from 'x-next';
+
+const columns: TableColumnData[] = [
+  { title: '姓名', dataIndex: 'name', width: 140 },
+  { title: '薪资', dataIndex: 'salary', width: 120 },
+  { title: '城市', dataIndex: 'city', width: 120 },
+  { title: '邮箱', dataIndex: 'email', width: 220 },
+];
+
+const data: TableData[] = [
+  { key: '1', name: 'Jane', salary: 23000, city: 'London', email: 'jane@example.com' },
+  { key: '2', name: 'Alisa', salary: 25000, city: 'Paris', email: 'alisa@example.com' },
+  { key: '3', name: 'Kevin', salary: 22000, city: 'London', email: 'kevin@example.com', disabled: true },
+  { key: '4', name: 'Ed', salary: 17000, city: 'Tokyo', email: 'ed@example.com' },
+];
+
+const selectedKeys = ref<(string | number)[]>(['2']);
+</script>
+<template>
+<XTable
+    v-model:selected-keys="selectedKeys"
+    :columns="columns"
+    :data="data"
+    :row-selection="{ type: 'radio' }"
+    :pagination="false"
+  />
+</template>
+```
+
+### 展开行
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+const expandable = {
+  title: '展开',
+  width: 72,
+};
+
+import { ref } from 'vue';
+import { Table as XTable } from 'x-next';
+import type { TableColumnData, TableData } from 'x-next';
+
+const columns: TableColumnData[] = [
+  { title: '姓名', dataIndex: 'name', width: 140 },
+  { title: '薪资', dataIndex: 'salary', width: 120 },
+  { title: '城市', dataIndex: 'city', width: 120 },
+  { title: '邮箱', dataIndex: 'email', width: 220 },
+];
+
+const data: TableData[] = [
+  { key: '1', name: 'Jane', salary: 23000, city: 'London', email: 'jane@example.com' },
+  { key: '2', name: 'Alisa', salary: 25000, city: 'Paris', email: 'alisa@example.com' },
+  { key: '3', name: 'Kevin', salary: 22000, city: 'London', email: 'kevin@example.com', disabled: true },
+  { key: '4', name: 'Ed', salary: 17000, city: 'Tokyo', email: 'ed@example.com' },
+];
+
+const expandedKeys = ref<(string | number)[]>(['1']);
+</script>
+<template>
+<XTable
+    v-model:expanded-keys="expandedKeys"
+    :columns="columns"
+    :data="data"
+    :expandable="{ title: '展开', width: 72 }"
+  >
+    <template #expand-row="{ record }">
+      {{ record.expand || `${record.name} 暂无额外说明。` }}
+    </template>
+  </XTable>
+</template>
+```
+
+### 树形数据
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Table as XTable } from 'x-next';
+import type { TableColumnData, TableData } from 'x-next';
+
+const columns: TableColumnData[] = [
+  { title: '名称', dataIndex: 'name' },
+  { title: '类型', dataIndex: 'type' },
+  { title: '状态', dataIndex: 'status' },
+];
+
+const data: TableData[] = [
+  {
+    key: '1',
+    name: '数据录入',
+    type: '表单',
+    status: '稳定',
+    children: [
+      { key: '1-1', name: 'Input', type: '表单', status: '稳定' },
+      { key: '1-2', name: 'Select', type: '表单', status: '维护中' },
+    ],
+  },
+  {
+    key: '2',
+    name: '数据展示',
+    type: '展示',
+    status: '改造中',
+    children: [
+      { key: '2-1', name: 'Table', type: '展示', status: '改造中' },
+      { key: '2-2', name: 'Timeline', type: '展示', status: '稳定' },
+    ],
+  },
+];
+</script>
+<template>
+<XTable
+    :columns="columns"
+    :data="data"
+    :default-expanded-keys="['1']"
+    :pagination="false"
+  />
+</template>
+```
+
+### 排序和筛选
+
+可排序表头可通过 `Tab` 聚焦，并使用 `Enter` 或 `Space` 切换排序；读屏软件可从 `aria-sort` 获得当前顺序。筛选图标为原生按钮，会通过 `aria-expanded` 和 `aria-controls` 关联筛选弹层。
+
+键盘打开筛选会聚焦首个选项；单选选项可用方向键切换。按 `Escape` 关闭弹层并返回筛选按钮，未确认的选择不会改变表格结果。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { Table as XTable } from 'x-next';
+import type { TableColumnData, TableData, TableChangeExtra } from 'x-next';
+
+const columns: TableColumnData[] = [
+  {
+    title: '姓名',
+    dataIndex: 'name',
+    sortable: { sortDirections: ['ascend', 'descend'] },
+  },
+  {
+    title: '薪资',
+    dataIndex: 'salary',
+    filterable: {
+      filters: [{ text: '20000 以上', value: '20000' }],
+      filter: (values, record) => values.some((value) => record.salary > Number(value)),
+      multiple: true,
+    },
+  },
+];
+
+const data: TableData[] = [
+  { key: '1', name: 'Jane', salary: 23000, city: 'London', email: 'jane@example.com' },
+  { key: '2', name: 'Alisa', salary: 25000, city: 'Paris', email: 'alisa@example.com' },
+  { key: '3', name: 'Kevin', salary: 22000, city: 'London', email: 'kevin@example.com', disabled: true },
+  { key: '4', name: 'Ed', salary: 17000, city: 'Tokyo', email: 'ed@example.com' },
+];
+
+const alignLeft = ref(false);
+
+const log = ref('尚未排序或筛选');
+const handleChange = (_rows: TableData[], extra: TableChangeExtra, currentData: TableData[]) => {
+  log.value = `${extra.type}：共 ${currentData.length} 条符合条件`;
+};
+</script>
+<template>
+<XTable
+    :columns="columns"
+    :data="data"
+    :filter-icon-align-left="alignLeft"
+    @change="handleChange"
+  />
+
+  <p>{{ log }}</p>
+</template>
+```
+
+### 多列排序
+
+为参与多列排序的列声明 `sortable.sortPriority`，数字越大越先比较，相同优先级按列顺序比较。点击这些表头只改变各自条件；点击没有优先级的列仍切换为单列排序。每列支持 `sortOrder` 受控、默认方向和自定义比较函数。
+
+`change` 的 `extra.sorters` 给出全部有效条件，`extra.sorter` 保留第一个条件，兼容已有消费方。比较函数接收方向，需自行返回对应顺序；`sorter: true` 的列交给服务端排序。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+  import { Table as XTable, Button as XButton } from 'x-next';
+  import type {
+    TableColumnData,
+    TableData,
+    TableChangeExtra,
+  } from 'x-next';
+
+  const tableRef = ref<InstanceType<typeof XTable>>();
+  const log = ref('默认先按团队升序，再按积分降序；点击两个表头分别调整方向。');
+  const columns: TableColumnData[] = [
+    { title: '姓名', dataIndex: 'name' },
+    {
+      title: '团队',
+      dataIndex: 'team',
+      sortable: {
+        sortDirections: ['ascend', 'descend'],
+        sortPriority: 2,
+        defaultSortOrder: 'ascend',
+      },
+    },
+    {
+      title: '积分',
+      dataIndex: 'score',
+      sortable: {
+        sortDirections: ['ascend', 'descend'],
+        sortPriority: 1,
+        defaultSortOrder: 'descend',
+      },
+    },
+  ];
+  const data: TableData[] = [
+    { key: '1', name: 'Jane', team: 'B', score: 90 },
+    { key: '2', name: 'Alisa', team: 'A', score: 80 },
+    { key: '3', name: 'Kevin', team: 'A', score: 95 },
+    { key: '4', name: 'Ed', team: 'B', score: 85 },
+  ];
+  const handleChange = (_page: TableData[], extra: TableChangeExtra, rows: TableData[]) => {
+    log.value = `排序：${extra.sorters?.map((sorter) => `${sorter.field} ${sorter.direction}`).join(' → ') || '无'}；顺序：${rows.map((row) => row.name).join('、')}`;
+  };
+</script>
+<template>
+<div class="table-followup-demo">
+    <div class="table-followup-actions">
+      <XButton size="small" @click="tableRef?.resetSorters()">恢复默认排序</XButton>
+      <XButton size="small" @click="tableRef?.clearSorters()">清空排序</XButton>
+    </div>
+    <XTable
+      ref="tableRef"
+      :columns="columns"
+      :data="data"
+      :pagination="false"
+      @change="handleChange"
+    />
+    <span class="demo-inline-state" aria-live="polite">{{ log }}</span>
+  </div>
+</template>
+<style scoped>
+.table-followup-demo {
+    display: grid;
+    gap: 12px;
+    width: 100%;
+  }
+  .table-followup-actions {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 8px;
+  }
+</style>
+```
+
+### 分组表头、滚动和固定列
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Table as XTable } from 'x-next';
+import type { TableColumnData, TableData } from 'x-next';
+
+const columns: TableColumnData[] = [
+  {
+    title: '用户',
+    children: [
+      { title: '姓名', dataIndex: 'name', width: 140, fixed: 'left' as const },
+      { title: '城市', dataIndex: 'city', width: 120 },
+    ],
+  },
+  {
+    title: '工作信息',
+    children: [
+      { title: '薪资', dataIndex: 'salary', width: 120 },
+      { title: '邮箱', dataIndex: 'email', width: 260 },
+    ],
+  },
+  { title: '状态', dataIndex: 'status', width: 120, fixed: 'right' as const },
+];
+
+const data: TableData[] = [
+  { key: '1', name: 'Jane', salary: 23000, city: 'London', email: 'jane@example.com' },
+  { key: '2', name: 'Alisa', salary: 25000, city: 'Paris', email: 'alisa@example.com' },
+  { key: '3', name: 'Kevin', salary: 22000, city: 'London', email: 'kevin@example.com', disabled: true },
+  { key: '4', name: 'Ed', salary: 17000, city: 'Tokyo', email: 'ed@example.com' },
+];
+</script>
+<template>
+<XTable
+    :columns="columns"
+    :data="data"
+    :scroll="{ x: 900, y: 220 }"
+    :pagination="false"
+  />
+</template>
+```
+
+### 固定操作列与状态控制
+
+同时展示手柄、展开、选择和左右固定列。调整列宽会保留当前排序与筛选；只清空某一列时，其他列筛选继续生效。选中行在条纹和悬浮下仍保持选中反馈。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+const expandable = {
+  title: '展开',
+  width: 72,
+};
+
+import { ref } from 'vue';
+import { Table as XTable, Button as XButton } from 'x-next';
+import type { TableChangeExtra, TableColumnData, TableData } from 'x-next';
+
+const tableRef = ref<InstanceType<typeof XTable>>();
+const selectedKeys = ref<(string | number)[]>(['1']);
+const log = ref('可排序、筛选、调整列宽，并横向滚动检查固定列。');
+const data = ref<TableData[]>([
+  { key: '1', name: 'Jane', city: 'London', salary: 23000, desc: '基础组件维护' },
+  { key: '2', name: 'Alisa', city: 'Paris', salary: 25000, desc: '业务组件维护' },
+  { key: '3', name: 'Kevin', city: 'London', salary: 22000, desc: '文档维护', disabled: true },
+  { key: '4', name: 'Ed', city: 'Tokyo', salary: 17000, desc: '测试维护' },
+]);
+const columns: TableColumnData[] = [
+  {
+    title: '人员', fixed: 'left',
+    children: [{
+      title: '基本信息',
+      children: [{ title: '姓名', dataIndex: 'name', width: 140, minWidth: 100 }],
+    }],
+  },
+  {
+    title: '城市', dataIndex: 'city', width: 180,
+    filterable: {
+      filters: [{ text: 'London', value: 'London' }, { text: 'Paris', value: 'Paris' }],
+      defaultFilteredValue: ['London'],
+      filter: (values, record) => values.includes(record.city),
+    },
+  },
+  {
+    title: '薪资', dataIndex: 'salary', width: 180,
+    sortable: { sortDirections: ['ascend', 'descend'] },
+    filterable: {
+      filters: [{ text: '22000 以上', value: '22000' }],
+      filter: (values, record) => values.some(value => record.salary >= Number(value)),
+    },
+  },
+  { title: '说明', dataIndex: 'desc', width: 420, ellipsis: true, tooltip: true },
+  { title: '操作', width: 100, fixed: 'right', render: ({ record }) => record.disabled ? '只读' : '可维护' },
+];
+const handleChange = (_pageRows: TableData[], extra: TableChangeExtra, currentData: TableData[]) => {
+  if (extra.type === 'drag') data.value = currentData;
+  log.value = `${extra.type}：${currentData.map(row => row.name).join(' / ') || '空'}`;
+};
+</script>
+<template>
+<div class="table-combination-demo">
+    <div class="table-combination-actions">
+      <XButton size="small" @click="tableRef?.clearFilters('salary')">仅清空薪资筛选</XButton>
+      <XButton size="small" @click="tableRef?.clearFilters()">清空全部筛选</XButton>
+      <XButton size="small" @click="tableRef?.resetFilters()">恢复默认筛选</XButton>
+      <XButton size="small" @click="tableRef?.clearSorters()">清空排序</XButton>
+    </div>
+    <XTable
+      ref="tableRef"
+      v-model:selected-keys="selectedKeys"
+      :columns="columns"
+      :data="data"
+      :scroll="{ x: 1140, y: 180 }"
+      :row-selection="{ showCheckedAll: true }"
+      :expandable="{ expandedRowRender: record => `${record.name}：${record.desc}` }"
+      :draggable="{ type: 'handle' }"
+      :bordered="{ wrapper: true, cell: true }"
+      :pagination="false"
+      stripe
+      column-resizable
+      @change="handleChange"
+    />
+    <p aria-live="polite">{{ log }}；选中：{{ selectedKeys.join('、') || '无' }}</p>
+  </div>
+</template>
+<style scoped>
+.table-combination-demo { width: 100%; min-width: 0; }
+.table-combination-actions { display: flex; flex-wrap: wrap; gap: 8px; margin-bottom: 12px; }
+.table-combination-demo p { margin: 12px 0 0; font-size: 13px; }
+</style>
+```
+
+### 单元格合并
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Table as XTable } from 'x-next';
+import type { TableColumnData, TableData } from 'x-next';
+
+const spanMethod = ({ rowIndex, columnIndex }: { rowIndex: number; columnIndex: number }) => {
+  if (rowIndex === 1 && columnIndex === 1) {
+    return { rowspan: 2, colspan: 2 };
+  }
+};
+
+const columns: TableColumnData[] = [
+  { title: '姓名', dataIndex: 'name' },
+  { title: '薪资', dataIndex: 'salary' },
+  { title: '城市', dataIndex: 'city' },
+  { title: '邮箱', dataIndex: 'email' },
+];
+
+const data: TableData[] = [
+  { key: '1', name: 'Jane', salary: 23000, city: 'London', email: 'jane@example.com' },
+  { key: '2', name: 'Alisa', salary: 25000, city: 'Paris', email: 'alisa@example.com' },
+  { key: '3', name: 'Kevin', salary: 22000, city: 'London', email: 'kevin@example.com', disabled: true },
+  { key: '4', name: 'Ed', salary: 17000, city: 'Tokyo', email: 'ed@example.com' },
+];
+</script>
+<template>
+<XTable
+    :columns="columns"
+    :data="data"
+    :span-method="spanMethod"
+    :bordered="{ wrapper: true, cell: true }"
+  />
+</template>
+```
+
+### 总结行
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Table as XTable } from 'x-next';
+import type { TableColumnData, TableData } from 'x-next';
+
+const summary = ({ data }: { data: TableData[] }) => {
+  const total = data.reduce((acc, item) => {
+    acc.salary += item.salary;
+    return acc;
+  }, { name: '合计', salary: 0 });
+  return [total];
+};
+
+const columns: TableColumnData[] = [
+  { title: '姓名', dataIndex: 'name', width: 140 },
+  { title: '薪资', dataIndex: 'salary', width: 120 },
+  { title: '项目数', dataIndex: 'projects', width: 120 },
+  { title: '缺陷数', dataIndex: 'bugs', width: 120 },
+];
+
+const data: TableData[] = [
+  { key: '1', name: 'Jane Doe', salary: 23000, projects: 4, bugs: 2 },
+  { key: '2', name: 'Alisa Ross', salary: 25000, projects: 5, bugs: 1 },
+  { key: '3', name: 'Kevin Sandra', salary: 22000, projects: 3, bugs: 4 },
+  { key: '4', name: 'Ed Hellen', salary: 17000, projects: 2, bugs: 3 },
+];
+</script>
+<template>
+<XTable
+    :columns="columns"
+    :data="data"
+    :summary="summary"
+    summary-text="合计"
+  />
+</template>
+```
+
+### 省略与文本提示
+
+列配置 `ellipsis: true` 时超出宽度会截断。再开启 `tooltip` 后，悬浮会显示完整内容；`tooltip` 也可传入对象以配置 Tooltip 的属性。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Table as XTable } from 'x-next';
+import type { TableColumnData } from 'x-next';
+
+const columns: TableColumnData[] = [
+  { title: '名称', dataIndex: 'name', width: 160 },
+  // 截断并在悬浮时显示完整内容
+  { title: '描述', dataIndex: 'desc', ellipsis: true, tooltip: true },
+  // 只截断，不显示提示
+  { title: '备注', dataIndex: 'remark', width: 120, ellipsis: true },
+];
+const data = [{ key: '1', name: 'Button', desc: '很长的描述文本……', remark: '备注' }];
+</script>
+<template>
+<XTable :columns="columns" :data="data" :pagination="false" />
+</template>
+```
+
+### 吸顶表头
+
+`stickyHeader` 让表头在页面滚动时吸顶；传入数字可指定距离顶部的偏移量。需要纵向滚动时同时设置 `scroll.y`。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Table as XTable } from 'x-next';
+import type { TableColumnData, TableData } from 'x-next';
+
+const columns: TableColumnData[] = [
+  { title: '名称', dataIndex: 'name', width: 200 },
+  { title: '负责人', dataIndex: 'owner', width: 160 },
+  { title: '状态', dataIndex: 'status', width: 140 },
+];
+
+const data: TableData[] = Array.from({ length: 12 }, (_, index) => ({
+  key: String(index + 1),
+  name: `记录 ${index + 1}`,
+  owner: ['Jane', 'Alisa', 'Kevin', 'Ed'][index % 4],
+  status: index % 2 === 0 ? '已完成' : '处理中',
+}));
+</script>
+<template>
+<XTable
+    :columns="columns"
+    :data="data"
+    :sticky-header="48"
+    :scroll="{ y: 220 }"
+    :pagination="false"
+  />
+</template>
+```
+
+### 懒加载子树
+
+传入 `loadMore` 后展开箭头会在需要时异步拉取子节点。函数的第二个参数 `done` 用于回传子数据。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { Table as XTable } from 'x-next';
+import type { TableColumnData, TableData } from 'x-next';
+
+const data = ref([{ key: 'dept-1', name: '研发中心', type: '部门' }]);
+
+// done 回传子节点；子节点标记 isLeaf 后不再显示展开箭头
+const loadMore = (record: TableData, done: (children?: TableData[]) => void) => {
+  setTimeout(() => {
+    done([
+      { key: `${record.key}-1`, name: `${record.name} · 小组 1`, type: '小组', isLeaf: true },
+    ]);
+  }, 400);
+};
+
+const columns: TableColumnData[] = [
+  { title: '名称', dataIndex: 'name', width: 220 },
+  { title: '类型', dataIndex: 'type', width: 140 },
+];
+</script>
+<template>
+<XTable :columns="columns" :data="data" :load-more="loadMore" :pagination="false" />
+</template>
+```
+
+### 调整列宽
+
+拖动列边缘调整宽度，或用 `Tab` 聚焦列宽分隔符，再按左右方向键每次调整 10px。宽度不会小于列的 `minWidth`（至少 40px）；最后一列保留自动分配宽度。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Table as XTable } from 'x-next';
+import type { TableColumnData, TableData } from 'x-next';
+
+const columns: TableColumnData[] = [
+  { title: '姓名', dataIndex: 'name', width: 140, minWidth: 100 },
+  { title: '薪资', dataIndex: 'salary', width: 120 },
+  { title: '城市', dataIndex: 'city', width: 120 },
+  { title: '邮箱', dataIndex: 'email', width: 220 },
+];
+
+const data: TableData[] = [
+  { key: '1', name: 'Jane', salary: 23000, city: 'London', email: 'jane@example.com' },
+  { key: '2', name: 'Alisa', salary: 25000, city: 'Paris', email: 'alisa@example.com' },
+  { key: '3', name: 'Kevin', salary: 22000, city: 'London', email: 'kevin@example.com', disabled: true },
+  { key: '4', name: 'Ed', salary: 17000, city: 'Tokyo', email: 'ed@example.com' },
+];
+</script>
+<template>
+<XTable
+    :columns="columns"
+    :data="data"
+    column-resizable
+    :bordered="{ wrapper: true, cell: true }"
+  />
+</template>
+```
+
+### 拖拽排序
+
+默认手柄是可聚焦按钮，支持鼠标和触屏拖动；获得焦点后用 Alt + ↑ / ↓ 在当前页内移动同级行，`change` 回调与鼠标拖拽一致。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { Table as XTable } from 'x-next';
+import type { TableColumnData, TableData, TableChangeExtra } from 'x-next';
+
+const data = ref<TableData[]>([
+  { key: '1', name: 'Jane', salary: 23000, city: 'London', email: 'jane@example.com' },
+  { key: '2', name: 'Alisa', salary: 25000, city: 'Paris', email: 'alisa@example.com' },
+  { key: '3', name: 'Kevin', salary: 22000, city: 'London', email: 'kevin@example.com', disabled: true },
+  { key: '4', name: 'Ed', salary: 17000, city: 'Tokyo', email: 'ed@example.com' },
+]);
+const handleChange = (_pageRows: TableData[], extra: TableChangeExtra, currentData: TableData[]) => {
+  if (extra.type === 'drag') data.value = currentData;
+};
+
+const columns: TableColumnData[] = [
+  { title: '姓名', dataIndex: 'name', width: 140 },
+  { title: '薪资', dataIndex: 'salary', width: 120 },
+  { title: '城市', dataIndex: 'city', width: 120 },
+  { title: '邮箱', dataIndex: 'email', width: 220 },
+];
+</script>
+<template>
+<XTable
+    :columns="columns"
+    :data="data"
+    :draggable="{ type: 'handle', width: 40 }"
+    :pagination="false" @change="handleChange"
+  />
+</template>
+```
+
+### 键盘导航与行移动
+
+开启 `keyboardNavigation` 后，Tab 可进入表体，方向键移动到相邻可见单元格，Home / End 移至本行首尾，Ctrl + Home / End 移至全部可见数据首尾。树形展开行参与导航，虚拟窗口会挂载目标行；合并格导航跳过被跨行覆盖的单元格。
+
+单元格内的输入控件保留自己的方向键行为，Tab 可进入或离开控件。表格保留原生 table 语义。拖拽手柄或整行获得焦点后，Alt + ↑ / ↓ 移动当前页内的同级行；与鼠标拖拽一样通过 `change` 的第三个参数写回完整数据。触屏可按住手柄上下拖动，取消手势不提交。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { h, ref } from 'vue';
+  import { Table as XTable, Input as XInput } from 'x-next';
+  import type {
+    TableColumnData,
+    TableData,
+    TableChangeExtra,
+  } from 'x-next';
+
+  const log = ref('Tab 进入单元格后用方向键导航；手柄获得焦点后用 Alt + ↑ / ↓ 移动行。');
+  const data = ref<TableData[]>(
+    Array.from({ length: 80 }, (_, index) => ({
+      key: index + 1,
+      name: `任务 ${index + 1}`,
+      note: `备注 ${index + 1}`,
+    })),
+  );
+  const columns: TableColumnData[] = [
+    { title: '编号', dataIndex: 'key', width: 80 },
+    { title: '任务', dataIndex: 'name', width: 180 },
+    {
+      title: '可编辑备注',
+      dataIndex: 'note',
+      width: 220,
+      render: ({ record }) =>
+        h(XInput, {
+          modelValue: record.note as string,
+          size: 'small',
+          'aria-label': `任务 ${record.key} 备注`,
+          'onUpdate:modelValue': (value: string) => {
+            record.note = value;
+          },
+        }),
+    },
+  ];
+  const handleChange = (_page: TableData[], extra: TableChangeExtra, rows: TableData[]) => {
+    if (extra.type === 'drag') {
+      data.value = rows;
+      log.value = `已移动任务 ${extra.dragTarget?.key}；前五行：${rows
+        .slice(0, 5)
+        .map((row) => row.key)
+        .join('、')}`;
+    }
+  };
+</script>
+<template>
+<div class="table-keyboard-demo">
+    <XTable
+      keyboard-navigation
+      :columns="columns"
+      :data="data"
+      :draggable="{ type: 'handle', width: 48 }"
+      :virtual-list-props="{ height: 240, buffer: 5, estimatedSize: 40 }"
+      :pagination="false"
+      @change="handleChange"
+    />
+    <span class="demo-inline-state" aria-live="polite">{{ log }}</span>
+  </div>
+</template>
+<style scoped>
+.table-keyboard-demo {
+    display: grid;
+    gap: 12px;
+    width: 100%;
+  }
+</style>
+```
+
+### 行拖拽
+
+`draggable.type` 为 `'row'` 时整行可用鼠标拖动，也可聚焦整行后用 Alt + ↑ / ↓ 移动；为 `'handle'` 时通过手柄拖动，支持触屏（见上一节）。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { Table as XTable } from 'x-next';
+import type { TableColumnData, TableData, TableChangeExtra } from 'x-next';
+
+const data = ref<TableData[]>([
+  { key: '1', name: 'Jane', salary: 23000, city: 'London', email: 'jane@example.com' },
+  { key: '2', name: 'Alisa', salary: 25000, city: 'Paris', email: 'alisa@example.com' },
+  { key: '3', name: 'Kevin', salary: 22000, city: 'London', email: 'kevin@example.com', disabled: true },
+  { key: '4', name: 'Ed', salary: 17000, city: 'Tokyo', email: 'ed@example.com' },
+]);
+
+const onChange = (_pageRows: TableData[], extra: TableChangeExtra, currentData: TableData[]) => {
+  if (extra.type === 'drag') data.value = currentData;
+};
+
+const columns: TableColumnData[] = [
+  { title: '姓名', dataIndex: 'name', width: 140 },
+  { title: '薪资', dataIndex: 'salary', width: 120 },
+  { title: '城市', dataIndex: 'city', width: 120 },
+  { title: '邮箱', dataIndex: 'email', width: 220 },
+];
+</script>
+<template>
+<XTable :columns="columns" :data="data" :draggable="{ type: 'row' }" :pagination="false" @change="onChange" />
+</template>
+```
+
+### 可编辑单元格
+
+Table 没有内置的编辑态，用列的 `cell` 插槽即可实现：双击切换到输入控件，失焦或回车后写回数据。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { Table as XTable, Select as XSelect } from 'x-next';
+import type { TableColumnData, TableData } from 'x-next';
+
+const columns: TableColumnData[] = [
+  { title: '名称', dataIndex: 'name' },
+  // slotName 与 template 名一致
+  { title: '状态', dataIndex: 'status', slotName: 'statusCell' },
+];
+const data = ref([{ key: '1', name: 'Button', status: '待处理', editing: false }]);
+
+const startEdit = (record: TableData) => {
+  data.value = data.value.map((item) => ({ ...item, editing: item.key === record.key }));
+};
+const apply = (record: TableData, value: unknown) => {
+  data.value = data.value.map((item) =>
+    item.key === record.key ? { ...item, status: String(value ?? ''), editing: false } : item,
+  );
+};
+
+const options = ['待处理', '处理中', '已完成'];
+</script>
+<template>
+<XTable :columns="columns" :data="data" :pagination="false">
+    <template #statusCell="{ record }">
+      <!-- 非编辑态：双击进入编辑 -->
+      <span v-if="!record.editing" @dblclick="startEdit(record)">{{ record.status }}</span>
+      <!-- 编辑态：写入后退出 -->
+      <XSelect
+        v-else
+        :model-value="record.status"
+        :options="options"
+        @change="(value) => apply(record, value)"
+      />
+    </template>
+  </XTable>
+</template>
+```
+
+### 虚拟列表
+
+`estimatedSize` 用于估算未挂载行的高度；普通内容建议使用动态高度。`fixedSize: true` 只适合实际高度完全一致的行，估值必须与实际行高一致。包含树或展开详情时会使用动态高度；传入 `spanMethod` 时会回退普通滚动，以完整呈现跨行合并。
+
+Table 管理虚拟行的数据、身份和原生表格结构，`virtualListProps` 中的 `data`、`itemKey` 和 `component` 不会覆盖它们。通过 Table 的 `data` 和 `rowKey` 指定业务数据与键字段，记录键支持 `string` 和 `number`。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Table as XTable } from 'x-next';
+import type { TableColumnData, TableData } from 'x-next';
+
+const columns: TableColumnData[] = [
+  { title: '编号', dataIndex: 'key', width: 100 },
+  { title: '任务', dataIndex: 'name', width: 220 },
+  { title: '状态', dataIndex: 'status', width: 140 },
+  { title: '负责人', dataIndex: 'owner', width: 160 },
+];
+
+const data: TableData[] = Array.from({ length: 120 }, (_, index) => ({
+  key: String(index + 1),
+  name: `任务 ${index + 1}`,
+  status: index % 3 === 0 ? '待处理' : index % 3 === 1 ? '处理中' : '已完成',
+  owner: ['Jane', 'Alisa', 'Kevin', 'Ed'][index % 4],
+}));
+</script>
+<template>
+<XTable
+    :columns="columns"
+    :data="data"
+    :virtual-list-props="{ height: 260, fixedSize: false, estimatedSize: 39 }"
+    :pagination="false"
+  />
+</template>
+```
+
+### 虚拟行异步高度
+
+动态模式持续测量已挂载行；文本、图片和展开详情异步变高后，更新虚拟占位和定位偏移。下面的按钮模拟异步加载，先展开第一行，再观察详情从一段变成八段。未挂载内容仍通过 `estimatedSize` 估算，异步媒体预留尺寸可减少滚动位置变化。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+const expandable = {
+  title: '展开',
+  width: 72,
+};
+
+  import { onBeforeUnmount, ref } from 'vue';
+  import { Table as XTable, Button as XButton } from 'x-next';
+  import type { TableColumnData, TableData } from 'x-next';
+
+  const expandedKeys = ref<(string | number)[]>([1]);
+  const details = ref(['当前为短内容。点击按钮模拟异步请求。']);
+  const loading = ref(false);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const reset = () => {
+    clearTimeout(timer);
+    loading.value = false;
+    details.value = ['当前为短内容。点击按钮模拟异步请求。'];
+  };
+  const loadDetails = () => {
+    if (loading.value) return;
+    loading.value = true;
+    expandedKeys.value = [1];
+    timer = setTimeout(() => {
+      details.value = Array.from(
+        { length: 8 },
+        (_, index) => `异步详情 ${index + 1}：动态内容加载完成后，虚拟列表持续测量实际行高。`,
+      );
+      loading.value = false;
+    }, 600);
+  };
+  onBeforeUnmount(() => clearTimeout(timer));
+  const columns: TableColumnData[] = [
+    { title: '编号', dataIndex: 'key', width: 80 },
+    { title: '任务', dataIndex: 'name', width: 260 },
+  ];
+  const data: TableData[] = Array.from({ length: 80 }, (_, index) => ({
+    key: index + 1,
+    name: `异步任务 ${index + 1}`,
+  }));
+</script>
+<template>
+<div class="table-height-demo">
+    <div class="table-height-actions">
+      <XButton size="small" :loading="loading" @click="loadDetails">异步加载详情</XButton>
+      <XButton size="small" @click="reset">恢复短内容</XButton>
+    </div>
+    <XTable
+      v-model:expanded-keys="expandedKeys"
+      :columns="columns"
+      :data="data"
+      :expandable="{ width: 48 }"
+      :virtual-list-props="{ height: 260, fixedSize: false, estimatedSize: 40, buffer: 3 }"
+      :pagination="false"
+    >
+      <template #expand-row="{ record }">
+        <div v-if="record.key === 1" class="table-height-details">
+          <p v-for="(line, index) in details" :key="index">{{ line }}</p>
+        </div>
+        <div v-else class="table-height-details">任务 {{ record.key }} 的详情</div>
+      </template>
+    </XTable>
+    <span class="demo-inline-state" aria-live="polite"
+      >第一行详情：{{ details.length }} 段；展开后异步变高，滚动仍按实际高度定位。</span
+    >
+  </div>
+</template>
+<style scoped>
+.table-height-demo {
+    display: grid;
+    gap: 12px;
+    width: 100%;
+  }
+  .table-height-actions {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 8px;
+  }
+  .table-height-details {
+    padding: 12px;
+  }
+  .table-height-details p {
+    margin: 0 0 8px;
+  }
+  .table-height-details p:last-child {
+    margin-bottom: 0;
+  }
+</style>
+```
+
+### 自定义渲染和插槽
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Table as XTable } from 'x-next';
+import type { TableColumnData, TableData } from 'x-next';
+
+const columns: TableColumnData[] = [
+  { title: '名称', dataIndex: 'name', slotName: 'nameCell' },
+  { title: '状态', dataIndex: 'status' },
+];
+
+const data: TableData[] = [
+  { key: '1', name: 'Button', type: '通用', status: '稳定' },
+  { key: '2', name: 'Select', type: '表单', status: '维护中' },
+  { key: '3', name: 'Table', type: '数据展示', status: '改造中' },
+];
+</script>
+<template>
+<XTable :columns="columns" :data="data">
+    <template #nameCell="{ record }">
+      <strong>{{ record.name }}</strong>
+    </template>
+  </XTable>
+</template>
+```
+
+### 空态和加载
+
+`loading` 为 `true` 时使用标准主题色圆环，默认主题下为蓝色。需要提示文字、延迟或圆点动画时，可传入 Spin 配置，例如 `{ loading: true, tip: '加载中', delay: 200 }` 或 `{ loading: true, dot: 'color' }`。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { Button as XButton, Table as XTable } from 'x-next';
+import type { TableColumnData, TableData } from 'x-next';
+
+const loading = ref(true);
+
+const columns: TableColumnData[] = [
+  { title: '名称', dataIndex: 'name' },
+  { title: '类型', dataIndex: 'type' },
+  { title: '状态', dataIndex: 'status' },
+];
+
+const data: TableData[] = [
+  { key: '1', name: 'Button', type: '通用', status: '稳定' },
+  { key: '2', name: 'Select', type: '表单', status: '维护中' },
+  { key: '3', name: 'Table', type: '数据展示', status: '改造中' },
+];
+</script>
+<template>
+<XTable :columns="columns" :data="[]" :pagination="false">
+    <template #empty>暂无匹配数据</template>
+  </XTable>
+  <XButton size="small" @click="loading = !loading">
+    {{ loading ? '结束加载' : '开始加载' }}
+  </XButton>
+  <XTable :columns="columns" :data="data" :loading="loading" :pagination="false" />
+</template>
+```
+
+### 命令式方法
+
+通过 ref 调用 `select` / `expand` / `resetFilters` / `clearSorters` 等方法操作表格状态。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { Table as XTable, Button as XButton } from 'x-next';
+import type { TableColumnData } from 'x-next';
+
+const tableRef = ref<InstanceType<typeof XTable>>();
+const data = [{ key: '1', name: 'Button' }, { key: '2', name: 'Table' }];
+
+const columns: TableColumnData[] = [{ title: '名称', dataIndex: 'name' }];
+</script>
+<template>
+<XButton @click="tableRef?.select('2', true)">选中第 2 行</XButton>
+  <XButton @click="tableRef?.selectAll(true)">全选</XButton>
+  <XTable ref="tableRef" :columns="columns" :data="data" :row-selection="{ type: 'checkbox' }" />
+</template>
+```
+
+### 自定义筛选弹层
+
+`filterable.slotName` 指定弹层内容所用的具名插槽，插槽参数含 `filterValue`、`setFilterValue`、`handleFilterConfirm`、`handleFilterReset`。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { Table as XTable, Button as XButton, Checkbox as XCheckbox, CheckboxGroup as XCheckboxGroup } from 'x-next';
+import type { TableColumnData, TableData } from 'x-next';
+
+const columns: TableColumnData[] = [
+  { title: '名称', dataIndex: 'name' },
+  {
+    title: '状态',
+    dataIndex: 'status',
+    filterable: {
+      filters: [{ text: '待处理', value: '待处理' }],
+      filter: (values, record) => values.length === 0 || values.includes(record.status),
+      multiple: true,
+      // 与 template 名一致
+      slotName: 'statusFilter',
+    },
+  },
+];
+
+const data: TableData[] = [
+  { key: '1', name: 'Button', status: '待处理', owner: 'Jane' },
+  { key: '2', name: 'Table', status: '处理中', owner: 'Alisa' },
+  { key: '3', name: 'Select', status: '已完成', owner: 'Kevin' },
+  { key: '4', name: 'Input', status: '待处理', owner: 'Ed' },
+];
+
+const log = ref('未筛选');
+const onFilterChange = (field: string, values: string[]) => {
+  log.value = `${field}: ${values.join('、') || '清空'}`;
+};
+</script>
+<template>
+<XTable :columns="columns" :data="data" @filter-change="onFilterChange">
+    <template #statusFilter="{ filterValue, setFilterValue, handleFilterConfirm, handleFilterReset }">
+      <XCheckboxGroup :model-value="filterValue" @change="setFilterValue">
+        <XCheckbox value="待处理">待处理</XCheckbox>
+        <XCheckbox value="处理中">处理中</XCheckbox>
+      </XCheckboxGroup>
+      <XButton size="mini" @click="handleFilterReset">重置</XButton>
+      <XButton size="mini" type="primary" @click="handleFilterConfirm">确认</XButton>
+    </template>
+  </XTable>
+
+  <p>{{ log }}</p>
+</template>
+```
+
+### 自定义展开图标
+
+`expand-icon` 插槽可替换默认的展开箭头，参数为 `{ expanded, record }`。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+const expandable = {
+  title: '展开',
+  width: 72,
+};
+
+import { Table as XTable } from 'x-next';
+import type { TableColumnData, TableData } from 'x-next';
+
+const columns: TableColumnData[] = [
+  { title: '名称', dataIndex: 'name', width: 180 },
+  { title: '说明', dataIndex: 'desc' },
+];
+
+const data: TableData[] = [
+  { key: '1', name: 'Button', desc: '触发即时操作' },
+  { key: '2', name: 'Table', desc: '数据收集与展示' },
+];
+
+const render = (record: TableData) => `详情：${record.desc}`;
+</script>
+<template>
+<XTable :columns="columns" :data="data" :expandable="{ expandedRowRender: render }">
+    <template #expand-icon="{ expanded }">
+      <span>{{ expanded ? '−' : '+' }}</span>
+    </template>
+  </XTable>
+</template>
+```
+
+### 分页两侧与总结行插槽
+
+`pagination-left` / `pagination-right` 用于在分页器两侧补充内容；`summary-cell` 用于自定义总结行的单元格。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { Table as XTable, Button as XButton } from 'x-next';
+import type { TableColumnData, TableData } from 'x-next';
+
+const columns: TableColumnData[] = [
+  { title: '名称', dataIndex: 'name', width: 180 },
+  { title: '状态', dataIndex: 'status', width: 140 },
+  { title: '负责人', dataIndex: 'owner' },
+];
+
+const data = ref<TableData[]>([
+  { key: '1', name: 'Button', status: '待处理', owner: 'Jane' },
+  { key: '2', name: 'Table', status: '处理中', owner: 'Alisa' },
+  { key: '3', name: 'Select', status: '已完成', owner: 'Kevin' },
+]);
+
+const log = ref('尚未刷新');
+</script>
+<template>
+<XTable :columns="columns" :data="data" :pagination="{ pageSize: 2 }" :summary="true">
+    <template #pagination-left>
+      <span>共 {{ data.length }} 条记录</span>
+    </template>
+    <template #pagination-right>
+      <XButton size="mini" @click="log = '已刷新'">刷新</XButton>
+    </template>
+  </XTable>
+
+  <p>{{ log }}</p>
+</template>
+```
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Table as XTable } from 'x-next';
+import type { TableColumnData, TableData } from 'x-next';
+
+const columns: TableColumnData[] = [
+  { title: '姓名', dataIndex: 'name' },
+  { title: '薪资', dataIndex: 'salary' },
+  { title: '项目数', dataIndex: 'projects' },
+];
+
+const data: TableData[] = [
+  { key: '1', name: 'Jane Doe', salary: 23000, projects: 4 },
+  { key: '2', name: 'Alisa Ross', salary: 25000, projects: 5 },
+  { key: '3', name: 'Kevin Sandra', salary: 22000, projects: 3 },
+];
+
+const summaryText = (column: TableColumnData) => {
+  if (column.dataIndex === 'name') return '合计';
+  const field = column.dataIndex;
+  return field ? data.reduce((total, row) => total + Number(row[field] || 0), 0) : '';
+};
+</script>
+<template>
+<XTable :columns="columns" :data="data" :summary="true">
+    <!-- 参数为 { column, record, rowIndex } -->
+    <template #summary-cell="{ column }">
+      <strong>{{ summaryText(column) }}</strong>
+    </template>
+  </XTable>
+</template>
+```
+
+### 事件回调
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { Table as XTable } from 'x-next';
+import type { TableColumnData, TableData } from 'x-next';
+
+const columns: TableColumnData[] = [
+  { title: '姓名', dataIndex: 'name', width: 140 },
+  { title: '薪资', dataIndex: 'salary', width: 120 },
+  { title: '城市', dataIndex: 'city', width: 120 },
+  { title: '邮箱', dataIndex: 'email', width: 220 },
+];
+
+const data: TableData[] = [
+  { key: '1', name: 'Jane', salary: 23000, city: 'London', email: 'jane@example.com' },
+  { key: '2', name: 'Alisa', salary: 25000, city: 'Paris', email: 'alisa@example.com' },
+  { key: '3', name: 'Kevin', salary: 22000, city: 'London', email: 'kevin@example.com', disabled: true },
+  { key: '4', name: 'Ed', salary: 17000, city: 'Tokyo', email: 'ed@example.com' },
+];
+
+const logs = ref<string[]>([]);
+const handleRowClick = (record: TableData) => logs.value.push(`行：${record.name}`);
+const handleCellClick = (record: TableData, column: TableColumnData) => logs.value.push(`单元格：${record.name}/${column.dataIndex}`);
+const handleHeaderClick = (column: TableColumnData) => logs.value.push(`表头：${column.title}`);
+</script>
+<template>
+<XTable
+    :columns="columns"
+    :data="data"
+    @row-click="handleRowClick"
+    @cell-click="handleCellClick"
+    @header-click="handleHeaderClick"
+  />
+
+  <p v-for="(log, index) in logs" :key="index">{{ log }}</p>
+</template>
+```
+
+### 类型说明
+
+| 类型 | 说明 |
+| --- | --- |
+| `TableData` | 行数据，默认用 `key` 作为唯一标识，可包含 `children`、`expand`、`disabled`、`isLeaf` |
+| `TableSortable` | 排序配置，包含 `sortDirections`、`sorter`、`sortOrder`、`defaultSortOrder`、`sortPriority` |
+| `TableFilterable` | 筛选配置，包含 `filters`、`filter`、`multiple`、`filteredValue`、`defaultFilteredValue`、`renderContent`、`icon`、`triggerProps`、`alignLeft`、`slotName` |
+| `TableRowSelection` | 行选择配置，包含 `type`、`selectedRowKeys`、`defaultSelectedRowKeys`、`showCheckedAll`、`title`、`width`、`fixed`、`checkStrictly`、`onlyCurrent` |
+| `TableExpandable` | 展开行配置，包含 `expandedRowKeys`、`defaultExpandedRowKeys`、`defaultExpandAllRows`、`expandedRowRender`、`icon`、`title`、`width`、`fixed` |
+| `TableDraggable` | 拖拽配置，包含 `type`、`title`、`width`、`fixed` |
+| `TableChangeExtra` | `change` 事件附加信息，包含 `type`、`page`、`pageSize`、`sorter`、`sorters`、`filters`、`dragTarget` |
+
+
+### 元素插槽
+
+`tbody`、`thead`、`tr`、`td`、`th` 是内部元素插槽，可替换表格的原生元素（例如给 `tbody` 加原生属性、给 `td` 挂自定义指令）。
+
+**使用契约**：插槽内只提供**单一空元素**，让 Table 把原有的 children、class、style 和事件合并到该元素上。若自行写死内容，会覆盖表格原本的行、列和事件结构。
+
+也可用于 `tr` / `td` / `th` / `thead`。`tr` / `td` / `th` 会传入行与列信息（见上方 Slots 表）；`tbody` 与 `thead` 不传参数——children、attrs 与事件统一由 Table 合并到插槽返回的元素上。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Table as XTable } from 'x-next';
+import type { TableColumnData, TableData } from 'x-next';
+
+const columns: TableColumnData[] = [
+  { title: '名称', dataIndex: 'name' },
+  { title: '类型', dataIndex: 'type' },
+  { title: '状态', dataIndex: 'status' },
+];
+
+const data: TableData[] = [
+  { key: '1', name: 'Button', type: '通用', status: '稳定' },
+  { key: '2', name: 'Select', type: '表单', status: '维护中' },
+  { key: '3', name: 'Table', type: '数据展示', status: '改造中' },
+];
+</script>
+<template>
+<XTable :columns="columns" :data="data" :pagination="false">
+    <!-- 只写单一空元素，Table 会把 children / class / 事件合并进来 -->
+    <!-- tbody 插槽不接收参数：Table 会把 children/attrs 合并到返回的元素上 -->
+    <template #tbody>
+      <tbody v-bind="{ class: 'custom-table-body', 'data-custom-body': 'true' }" />
+    </template>
+  </XTable>
+</template>
+```
+
+### 已知限制
+
+- 拖拽排序和键盘行移动都要求业务在 `change` 中写回第三个参数。键盘移动限定当前页内同级行；触屏拖动通过手柄进行，整行模式保留页面的触屏滚动。
+- 非受控分页下筛选、排序和每页数量变化会自动回到第一页；受控分页需要业务同步 `pagination.current`。
+- 单选 `select` 只取数组中的第一个 key，`select(key, false)` 可取消选中；`selectAll` 仅用于多选。
+- `checkStrictly: false` 时父子联动与全选只选可用叶子，禁用叶子不参与联动。
+- `change` 的第一个参数为当前页数据，第三个参数为筛选、排序或拖拽后的全量业务数据；维护完整列表时使用第三个参数。
+- `loadMore` 调用 `done(undefined)` 可结束本次加载并允许重试；`done([])` 表示已加载的空子树。替换原始记录后，同 key 不会复用旧记录的懒加载缓存。
+- 虚拟动态行持续测量已挂载内容，未挂载行仍使用估值；异步媒体建议预留尺寸以减少跳动。跨行合并使用普通滚动。单元格导航是可选能力，编辑、复制粘贴和校验规则仍由业务实现。
+
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./table-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。