table-state

用途

table-state 用于在 React 中读取和控制 TanStack Table v9 的表格状态。它面向需要处理受跟踪读取、订阅、受控状态切片以及框架特定响应式边界的场景。

开始前，文档要求先运行 intent load @tanstack/table-core#table-state，以了解共享所有权、初始化、更新和重置。状态修复不需要加载 setup 指导。

读取响应式状态

useTable 默认会选取所有已注册状态。它的可选第二参数 selector 用于控制重渲染以及 table.state 的形状。table.atoms.<slice>.get() 和 table.store.state 是当前快照，不是 React 订阅。

在 owner 渲染中使用被选中的 table.state。若需要更窄的边界，可使用 table.Subscribe 或来自 @tanstack/react-store 的 useSelector。没有 source 时，table.Subscribe 从 table.store 选取；有 source 时，它订阅该 atom 或 store。建议先使用默认 selector，直到渲染成本需要收窄为止。

控制状态切片

保持 features、columns 和 data 稳定。注册拥有受控切片的 feature。以下示例控制分页，但不添加客户端行处理：

import { useState } from 'react'
import {
  rowPaginationFeature,
  tableFeatures,
  useTable,
  type PaginationState,
} from '@tanstack/react-table'

const features = tableFeatures({ rowPaginationFeature })
const columns = [{ accessorKey: 'name' }]
const data = [{ name: 'Ada' }]

export function PageControl() {
  const [pagination, setPagination] = useState<PaginationState>({
    pageIndex: 0,
    pageSize: 20,
  })
  const table = useTable({
    features,
    columns,
    data,
    state: { pagination },
    onPaginationChange: setPagination,
  })
  return (
    <button onClick={() => table.setPageSize(50)}>
      {table.state.pagination.pageSize} rows per page
    </button>
  )
}

React setter 同时接受值和函数式更新器。需要同时提供当前的 state.pagination 与 onPaginationChange；仅提供回调无法保持表格同步。

对于外部拥有的 atom，使用 @tanstack/react-store 的 useCreateAtom 创建它，通过 atoms.<slice> 传入，并在其他 UI 需要其值时用 useSelector 订阅。

响应式边界

对于 React Compiler 记忆化的子组件，将 Subscribe 放在隐藏 builder 方法读取的组件内部，或将选中的值作为会变化的 prop 传入。忽略其值的外部订阅无法刷新稳定的子组件。在 core 类型的 cell/header 上下文中，导入独立的 Subscribe。

关于外部 atom 示例、selector 依赖、细粒度边界和 React Compiler 问题，请阅读 reactivity 详情。如果此任务会改变处理类 feature，请运行 intent load @tanstack/table-core#table-features 并阅读相关 feature 参考。

API 发现

检查 node_modules/@tanstack/react-table/dist/useTable.d.ts 和 Subscribe.d.ts，以及已安装的 @tanstack/react-store 声明文件中的 atom hooks。

适用场景与限制

该技能适用于 React 中使用 TanStack Table v9 的表格状态读取、订阅、受控切片和响应式边界处理。文档未提供其他框架、版本兼容性、性能基准或收费信息。