tanstack-vue-table-skilld

@tanstack/vue-table 9.2.4

适用于 Vue 3 的无头表格适配器。重新导出 @tanstack/table-core 9.2.4 的所有内容，并提供 Vue 绑定：useTable、FlexRender、flexRender、createTableHook（dist/index.d.ts:4-5）。

环境限制：需要 vue >=3.2 peer dependency、Node >=20，运行时依赖为 @tanstack/store ^0.11.1（package.json:34-53）。

此 Skill 仅面向 v9。使用 useVueTable、getCoreRowModel() 或 onStateChange 的代码属于 v8；请先按照从 v8 迁移到 v9进行迁移。

快速开始

<script setup lang="ts">
import { ref } from 'vue'
import { FlexRender, tableFeatures, useTable } from '@tanstack/vue-table'

type Person = { name: string; age: number }
const features = tableFeatures({})
const columns = [
  { accessorKey: 'name', header: 'Name' },
  { accessorKey: 'age', header: 'Age' },
]
const data = ref<Person[]>([{ name: 'Ada', age: 36 }])
const table = useTable({ features, columns, data })
</script>

<template>
  <table>
    <thead>
      <tr v-for="group in table.getHeaderGroups()" :key="group.id">
        <th v-for="header in group.headers" :key="header.id">
          <FlexRender v-if="!header.isPlaceholder" :header="header" />
        </th>
      </tr>
    </thead>
    <tbody>
      <tr v-for="row in table.getRowModel().rows" :key="row.id">
        <td v-for="cell in row.getAllCells()" :key="cell.id">
          <FlexRender :cell="cell" />
        </td>
      </tr>
    </tbody>
  </table>
</template>

来源：skills/getting-started/SKILL.md（随软件包提供）。

显式添加功能

除了核心功能之外，必须注册每项功能；每个行模型插槽都必须在同一次 tableFeatures 调用中跟在其前置功能之后。核心行模型会自动启用；没有 getCoreRowModel() 选项。

import {
  createSortedRowModel,
  rowSortingFeature,
  sortFn_alphanumeric,
  tableFeatures,
} from '@tanstack/vue-table'

const features = tableFeatures({
  rowSortingFeature,
  sortedRowModel: createSortedRowModel(),
  sortFns: { alphanumeric: sortFn_alphanumeric },
})

API 由功能控制：如果缺少 table.atoms.pagination，说明尚未注册 rowPaginationFeature。完整的功能和插槽列表请参阅：API 概览。

每个状态切片只在一个位置管理

状态基于原子。请在受追踪的边界内（模板、computed、watch 或 table.Subscribe）读取状态；直接读取只会得到快照。

const pageIndex = computed(() => table.atoms.pagination.get().pageIndex)

受控切片需要响应式 state，以及对应的 on[State]Change 回调，用于解析值或函数形式的更新器：

const pagination = ref<PaginationState>({ pageIndex: 0, pageSize: 20 })
const state = computed(() => ({ pagination: pagination.value }))
const onPaginationChange = (next: PaginationState | ((old: PaginationState) => PaginationState)) => {
  pagination.value = typeof next === 'function' ? next(pagination.value) : next
}
// pass state and onPaginationChange to useTable

每个切片只能由一个来源管理：内部默认值、initialState、外部 atoms，或 state + 回调。不要同时使用 atoms.pagination 和 state.pagination。onStateChange 已不存在；请改为观察 table.store。详情请参阅：API 概览。

避免大多数错误的规则

1. 将 data 作为 ref/computed 传入，绝不要传入 data.value（dist/useTable.d.ts:13-19）。通过替换数组来更新它（.value = [...]）；原地执行 push/splice 不会被追踪，因为可写原子使用 shallowRef（dist/reactivity.js:50-52）。
2. 保持 features 和 columns 稳定；不要在每次渲染时重新创建数组。
3. 使用 FlexRender 简写进行渲染：:cell、:header、:footer。旧式 :render/:props 写法仍可编译，但它是待迁移的写法，而非默认写法（dist/FlexRender.d.ts:28-41）。
4. 绝不要解构或展开行、单元格、列或表头的方法；这些是使用 this 的原型方法。请使用 row.getValue('name')，不要写 const read = row.getValue。
5. 在 JSX 中，将渲染函数作为显式的 children prop 传给 table.Subscribe；Vue JSX 的子节点会变成插槽（dist/useTable.d.ts:9-11）。
6. 对于由服务器驱动的表格，请设置 manual* 选项（manualPagination: true），并传入 rowCount。
7. 可选的 stockFeatures 会捆绑所有功能；仅将其用作临时审查过渡方案，不要用于生产环境。

常见错误

• HIGH：将 useVueTable 改名为 useTable，却保留 getSortedRowModel 选项。请将行模型和注册表移入 tableFeatures（skills/migrate-v8-to-v9/SKILL.md:156-159）。
• HIGH：useTable({ data: data.value }) 会固定为单个快照；请传入 data（skills/getting-started/SKILL.md:85-99）。
• HIGH：在受追踪边界之外读取 table.atoms.sorting.get()；请用 computed 包裹（skills/table-state/SKILL.md:104-116）。
• HIGH：直接赋值更新器函数（pagination.value = next），而不是先解析它（skills/table-state/SKILL.md:146-161）。
• HIGH：columnPinning.left/right 已不存在；v9 使用逻辑固定位置 start/end（skills/migrate-v8-to-v9/SKILL.md:99-120）。
• HIGH：createColumnHelper<Person>() 现在需要先传入功能：createColumnHelper<typeof features, Person>()（skills/migrate-v8-to-v9/SKILL.md:147-148）。

可复用的应用约定

如需设置全应用的表格默认值，请使用 createTableHook({ features, tableComponents, cellComponents, headerComponents }) 获取 useAppTable、createAppColumnHelper 和带类型的上下文 Hook（dist/createTableHook.d.ts:136-153）。导出上下文 Hook 时请显式指定类型，避免注册的组件导入该 Hook 模块时出现循环类型推断（skills/create-table-hook/SKILL.md:62-84）。

集成

• TanStack Query：使用响应式键进行手动分页，并传入 rowCount 和计算后的数据。集成
• TanStack Virtual：对 table.getRowModel().rows 进行虚拟化，绝不要虚拟化源数组。集成

参考资料

• API 概览：导出项、子路径、useTable/Subscribe 类型、功能和插槽、原子模型。
• 从 v8 迁移到 v9：完整的破坏性变更对照、固定列重命名、TypeScript 变更、检查清单。
• 集成：TanStack Query 和 TanStack Virtual 的组合模式。

包中还包含

该包在 skills/ 下附带了自己的 Agent 技能（getting-started、table-state、migrate-v8-to-v9、create-table-hook、with-tanstack-query、with-tanstack-virtual），并提及 npx @tanstack/intent@latest install，用于将这些技能接入编码 Agent（README.md:70-78）。请在已安装的 node_modules/@tanstack/vue-table/dist/index.d.ts 中核实准确的 API；不要凭对 v8 的记忆还原 v9。