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、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 = [...]）。書き込み可能なアトムは shallowRef を使うため（dist/reactivity.js:50-52）、インプレースの push／splice は追跡されません。
2. features と columns は安定した状態に保ち、レンダーごとに配列を再構築しないでください。
3. FlexRender の省略記法 :cell、:header、:footer を使ってレンダリングしてください。従来の :render／:props 形式も引き続きコンパイルできますが、これは移行対象であり、標準の形式ではありません（dist/FlexRender.d.ts:28-41）。
4. 行、セル、列、ヘッダーのメソッドを分割代入したり、スプレッド構文で展開したりしないでください。これらは this を使うプロトタイプメソッドです。const read = row.getValue ではなく、row.getValue('name') を使ってください。
5. JSX では、レンダー関数を明示的な children プロパティとして table.Subscribe に渡してください。Vue の JSX では子要素がスロットになります（dist/useTable.d.ts:9-11）。
6. サーバー駆動のテーブルでは、manualPagination: true のように manual* オプションを設定し、rowCount を渡してください。
7. stockFeatures を指定するとすべての機能が追加されます。一時的な監査用の橋渡しとしてのみ使用し、本番では使用しないでください。

よくある間違い

• HIGH：getSortedRowModel オプションを残したまま useVueTable を useTable に名前変更する。行モデルとレジストリを 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、型付きコンテキストフック（dist/createTableHook.d.ts:136-153）を取得します。登録済みコンポーネントがフックモジュールをインポートするときに循環推論が発生しないよう、コンテキストフックは明示的な型を指定してエクスポートしてください（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 の組み合わせパターン。

パッケージに含まれるその他の内容

パッケージには独自のエージェントスキル（getting-started、table-state、migrate-v8-to-v9、create-table-hook、with-tanstack-query、with-tanstack-virtual）が skills/ に含まれており、コーディングエージェントに組み込むための npx @tanstack/intent@latest install が記載されています（README.md:70-78）。正確な API はインストール済みの node_modules/@tanstack/vue-table/dist/index.d.ts で確認してください。v8 の記憶をもとに v9 を再構成しないでください。