client-vs-server

このスキルは、core と table-features を基盤としています。モデルのパイプラインとプラグインスロットについて、先にこれらをお読みください。

セットアップ

import {
  rowPaginationFeature,
  rowSortingFeature,
  tableFeatures,
} from '@tanstack/table-core'

export const features = tableFeatures({
  rowSortingFeature,
  rowPaginationFeature,
})
export const serverOptions = {
  manualSorting: true,
  manualPagination: true,
  rowCount: 12_450,
} as const

基本パターン

クライアントがパイプライン全体を担う

const features = tableFeatures({
  columnFilteringFeature,
  filteredRowModel: createFilteredRowModel(),
  rowSortingFeature,
  sortedRowModel: createSortedRowModel(),
  rowPaginationFeature,
  paginatedRowModel: createPaginatedRowModel(),
})

各ステージがすべての行を処理できるよう、データセット全体をクライアントに渡します。

サーバーが処理を担う

const options = {
  data: serverPage.rows,
  manualFiltering: true,
  manualSorting: true,
  manualPagination: true,
  rowCount: serverPage.total,
}

制御されたフィルター、並べ替え、ページネーションの状態をリクエスト／クエリキーに含めます。

よくある間違い

[CRITICAL] manual フラグをリクエストとして扱う

誤り：

const options = { manualSorting: true, data: unsortedRows }

正しい例：

const sortedPage = await fetchPage({ sorting })
const options = { manualSorting: true, data: sortedPage.rows }

manualSorting はクライアント側の並べ替えをバイパスするだけで、バックエンドを呼び出すことはありません。

出典：packages/table-core/src/features/row-sorting/rowSortingFeature.types.ts

[HIGH] manual pagination がデータを切り分けると期待する

誤り：

const options = { data: allRows, manualPagination: true }

正しい例：

const page = await fetchPage({ pageIndex, pageSize })
const options = {
  data: page.rows,
  manualPagination: true,
  rowCount: page.rowCount,
}

manual pagination は、data がすでに対象ページの内容を表していることを前提とします。安定したページ結果をそのまま渡してください。アプリケーションで意図的にカスタムのローカル切り分けを行う場合は、フレームワークの memo／computed プリミティブを使って導出し、実際の入力が変わるまで参照を安定させてください。

出典：docs/framework/react/guide/pagination.md#manual-server-side-pagination

[HIGH] 読み込んだページだけを誤って並べ替える

誤り：

const options = {
  data: serverPage.rows,
  manualPagination: true,
  manualSorting: false,
}

正しい例：

const options = {
  data: serverPage.rows,
  manualPagination: true,
  manualSorting: true,
}

クライアント側の並べ替えで確認できるのは読み込み済みの行だけなので、データベース全体を対象とする順序にはできません。

出典：docs/guide/row-models.md

[HIGH] 処理済みのデータやカラムをインラインで再生成する

誤り：

const options = {
  data: allRows.filter(matchesFilters).slice(pageStart, pageEnd),
  columns: makeColumns(),
}

正しい例：

const processedRows = pageResult.rows
const columns = sharedColumns
const options = { data: processedRows, columns }

data と columns はモデルへの入力です。モジュール定数、状態、またはアダプターの memo／computed プリミティブを使い、意味のある変更がない限り両方の参照を安定させてください。そうしないと、Table は行モデルとカラムモデルを繰り返し無効化し、一部のアダプターではレンダリングループに陥ることがあります。「Manual」とは処理の担当を示すものであり、テーブルオプション内で新しい配列を導出してよいという意味ではありません。

出典：docs/guide/data.md

API の調査

パイプラインの順序については node_modules/@tanstack/table-core/dist/core/row-models/coreRowModelsFeature.utils.d.ts を、各機能の manual* の仕様についてはそれぞれの .types.d.ts を確認してください。