tanstack-alpine-table-table-state

用途

该技能用于在 Alpine.js 中配合 @tanstack/alpine-table 管理表格状态。它建立在 @tanstack/table-core#core 以及该包的入门技能之上，重点说明状态归属、响应式读取与更新方式。

状态心智模型

TanStack Table 主要是一个状态协调器。除非其他系统需要读取、持久化或驱动状态，否则应保持状态内部化。如果没有 initialState、atoms、state 或 on[State]Change，表格将拥有所有已注册的状态切片。

table.baseAtoms 是从解析后的初始状态初始化的内部可写原子。

table.atoms 是每个已注册切片当前所有者的只读派生原子。

table.store 将这些原子合并为一个只读扁平 store。

Alpine 适配器代理表格并将其订阅到 store。在 x-text、x-for、x-if、绑定属性、x-effect 或 Alpine getter 中的读取会自动具备响应性；事件处理器在被调用时读取当前值。状态基于功能，因此缺少状态或方法通常意味着该功能未注册。保持功能、列和源数据稳定；通过 getter 暴露变化的响应式数据，而不是在表格选项中过滤、映射或切片。

设置

import Alpine from 'alpinejs'
import {
  createTable,
  rowPaginationFeature,
  tableFeatures,
} from '@tanstack/alpine-table'
import type { PaginationState } from '@tanstack/alpine-table'

const features = tableFeatures({ rowPaginationFeature })

Alpine.data('pagedTable', () => {
  const local = Alpine.reactive<{ pagination: PaginationState }>({
    pagination: { pageIndex: 0, pageSize: 10 },
  })
  const table = createTable({
    features,
    columns: [],
    data: [],
    state: {
      get pagination() {
        return local.pagination
      },
    },
    onPaginationChange: (updater) => {
      local.pagination =
        typeof updater === 'function' ? updater(local.pagination) : updater
    },
  })

  return { table }
})

核心模式

在绑定中读取窄原子

使用 table.atoms.pagination.get().pageIndex 进行窄状态读取。代理会将绑定注册为响应式。

仅在需要门控宽泛代理更新时使用选择器

可选的第二个 createTable 参数会对选定状态进行浅比较。仅当显式原子订阅处理高频更新（如调整大小）时，才使用 () => ({})。

每个切片选择一个所有者

要么通过 atoms.pagination 使用外部原子，要么使用 Alpine 控制的 state.pagination 加 onPaginationChange。如果两者都提供，外部原子优先。

选择状态归属

对于表格本地交互，优先使用内部状态和功能 API。
initialState 仅用于起始/重置值；之后更改它不会重置当前状态。
当状态需要共享时，优先在 atoms 中使用稳定的外部原子。功能 API 会直接写入它，因此省略 on[State]Change。
对于简单的受控状态，使用通过 getter 暴露的 Alpine.reactive 值及其匹配回调。解析原始值和更新函数。

外部原子优先于外部状态，外部状态会同步到内部基础原子。不要依赖多个所有者。全局 v8 onStateChange 选项已移除；订阅 table.store 以观察完整状态。

初始化、更新与重置

优先使用功能方法，如 setSorting、nextPage、toggleVisibility 和 toggleSelected。直接写入 baseAtoms 是内部状态的罕见逃生舱；当外部原子拥有切片时，写入外部原子。

table.resetSorting()
table.resetPagination()
table.resetPagination(true)

功能重置使用 table.initialState，除非传入 true 请求功能默认值，并且可以更新外部所有者。核心 table.reset() 仅重置内部基础原子。使用功能特定类型如 PaginationState；使用 TableState<typeof features> 表示从已注册功能推断的完整状态。

常见错误

高：虚构 Subscribe 组件

错误：渲染不存在的 table.Subscribe 包装器。

正确：直接在 Alpine 绑定中读取相关表格 API。

Alpine 适配器使代理的表格读取具备响应性；它没有组件渲染边界。

来源：TanStack/table:docs/framework/alpine/guide/table-state.md

高：受控快照从不刷新

错误：设置 state: { pagination: local.pagination } 然后替换 local.pagination。

正确：为受控切片定义 getter，并将每个更新函数应用回 local.pagination。

适配器 effect 必须读取当前响应式值以重新应用选项。

来源：TanStack/table:packages/alpine-table/src/createTable.ts

中：状态与原子所有者冲突

错误：同时传入 state.pagination 和 atoms.pagination，期望双向同步。

正确：选择一种归属机制；当原子拥有切片时，写入外部原子。

派生的表格原子在受控或内部状态之前读取外部原子。