tanstack-preact-table-with-tanstack-query

用途

该技能用于在 Preact 应用中把 TanStack Table v9 与 @tanstack/preact-query 组合起来，构建由服务端处理过滤、排序和分页的表格。它建立在 @tanstack/table-core 的 client-vs-server、getting-started 和 table-state 概念之上。

主要能力

• 使用 @tanstack/preact-query 的 useQuery 获取已经处理好的行数据。
• 使用 @tanstack/preact-store 的 useCreateAtom 与 useSelector 管理表格状态。
• 使用 @tanstack/preact-table 的 tableFeatures、rowPaginationFeature 和 useTable 创建表格。
• 通过 manualPagination 等手动标志声明服务端处理边界。
• 使用 keepPreviousData 在分页切换时保留上一页数据。
• 通过 rowCount 接收服务端返回的总行数。

使用方式

资料给出的设置示例：

import { keepPreviousData, useQuery } from '@tanstack/preact-query'
import { useCreateAtom, useSelector } from '@tanstack/preact-store'
import {
  rowPaginationFeature,
  tableFeatures,
  useTable,
} from '@tanstack/preact-table'

const features = tableFeatures({ rowPaginationFeature })
const emptyRows: Array<{ id: string }> = []
const paginationAtom = useCreateAtom({ pageIndex: 0, pageSize: 20 })
const pagination = useSelector(paginationAtom, (value) => value)
const result = useQuery({
  queryKey: ['people', pagination],
  queryFn: () => fetchPeople(pagination),
  placeholderData: keepPreviousData,
})
const table = useTable({
  features,
  columns,
  data: result.data?.rows ?? emptyRows,
  rowCount: result.data?.rowCount,
  atoms: { pagination: paginationAtom },
  manualPagination: true,
})

核心模式包括：

• 以每个服务端拥有的切片作为请求键：

useQuery({
  queryKey: ['people', pagination, sorting],
  queryFn: () => fetchPeople({ pagination, sorting }),
})

• 直接传入缓存的行数据：

useTable({ features, columns, data: result.data?.rows ?? emptyRows })

常见错误

• 导入 React Query API：应使用 @tanstack/preact-query，而不是 @tanstack/react-query。整个组合中应使用原生 Preact Query 与 Store 集成。
• 复用同一个缓存键：每个经过服务端处理的结果都需要一个包含其请求状态的键，例如 ['people', pagination]，而不是 ['people']。
• 期望手动标志去获取数据：手动分页会绕过本地处理，它既不会调用后端，也不会凭空生成总数。正确做法是传入 data: result.data?.rows ?? emptyRows 和 rowCount: result.data?.rowCount。

适用场景

适用于需要在 Preact 中实现服务端分页、排序或过滤的表格界面，并且希望用 TanStack Query 管理数据获取与缓存。

限制

资料未提供具体的安装命令、版本要求、完整 API 列表或性能数据。API 发现方式为：检查已安装的 node_modules/@tanstack/preact-table/dist/index.d.ts 及相关核心功能源码，并检查 @tanstack/preact-query 源码以获取确切的查询 API。