Table State (Svelte) 指南

TanStack Table 有一个简单的底层内部状态管理系统，用于存储和管理表格的状态。它还允许您选择性地提取您需要在自己的状态管理中管理的任何状态。本指南将引导您了解可以与表格状态进行交互和管理的不同方式。

访问表格状态

您无需进行任何特殊设置即可使表格状态正常工作。如果您未向 state、initialState 或任何 on[State]Change 表格选项传递任何内容，表格将自行管理其内部状态。您可以使用 table.getState() 表格实例 API 来访问此内部状态的任何部分。

jsx

const options = writable({
  columns,
  data,
  //...
})

const table = createSvelteTable(options)

console.log(table.getState()) //access the entire internal state
console.log(table.getState().rowSelection) //access just the row selection state

const options = writable({
  columns,
  data,
  //...
})

const table = createSvelteTable(options)

console.log(table.getState()) //access the entire internal state
console.log(table.getState().rowSelection) //access just the row selection state

自定义初始状态

如果对于某些状态，您只需要自定义其初始默认值，您仍然无需自己管理任何状态。您只需在表格实例的 initialState 选项中设置值即可。

jsx

const options = writable({
  columns,
  data,
  initialState: {
    columnOrder: ['age', 'firstName', 'lastName'], //customize the initial column order
    columnVisibility: {
      id: false //hide the id column by default
    },
    expanded: true, //expand all rows by default
    sorting: [
      {
        id: 'age',
        desc: true //sort by age in descending order by default
      }
    ]
  },
  //...
})

const table = createSvelteTable(options)

const options = writable({
  columns,
  data,
  initialState: {
    columnOrder: ['age', 'firstName', 'lastName'], //customize the initial column order
    columnVisibility: {
      id: false //hide the id column by default
    },
    expanded: true, //expand all rows by default
    sorting: [
      {
        id: 'age',
        desc: true //sort by age in descending order by default
      }
    ]
  },
  //...
})

const table = createSvelteTable(options)

注意：每个特定状态只能在 initialState 或 state 中指定，但不能同时指定两者。如果您将特定状态值传递给 initialState 和 state，则 state 中的已初始化状态将覆盖 initialState 中任何相应的值。

受控状态

如果您需要在应用程序的其他区域轻松访问表格状态，TanStack Table 可以轻松地在您自己的状态管理系统中控制和管理任何或所有表格状态。您可以通过将自己的状态和状态管理函数传递给 state 和 on[State]Change 表格选项来实现这一点。

独立受控状态

您可以只控制您需要轻松访问的状态。如果您不需要，则不必控制所有表格状态。建议仅根据具体情况控制所需的状态。

为了控制特定状态，您需要将相应的 state 值和 on[State]Change 函数都传递给表格实例。

让我们以“手动”服务器端数据获取场景中的过滤、排序和分页为例。您可以将过滤、排序和分页状态存储在自己的状态管理中，但如果您的 API 不关心这些值（例如列顺序、列可见性等），则可以省略其他状态。

let sorting = [
  {
    id: 'age',
    desc: true, //sort by age in descending order by default
  },
]
const setSorting = updater => {
  if (updater instanceof Function) {
    sorting = updater(sorting)
  } else {
    sorting = updater
  }
  options.update(old => ({
    ...old,
    state: {
      ...old.state,
      sorting,
    },
  }))
}

let columnFilters = [] //no default filters
const setColumnFilters = updater => {
  if (updater instanceof Function) {
    columnFilters = updater(columnFilters)
  } else {
    columnFilters = updater
  }
  options.update(old => ({
    ...old,
    state: {
      ...old.state,
      columnFilters,
    },
  }))
}

let pagination = { pageIndex: 0, pageSize: 15 } //default pagination
const setPagination = updater => {
  if (updater instanceof Function) {
    pagination = updater(pagination)
  } else {
    pagination = updater
  }
  options.update(old => ({
    ...old,
    state: {
      ...old.state,
      pagination,
    },
  }))
}

//Use our controlled state values to fetch data
const tableQuery = createQuery({
  queryKey: ['users', columnFilters, sorting, pagination],
  queryFn: () => fetchUsers(columnFilters, sorting, pagination),
  //...
})

const options = writable({
  columns,
  data: tableQuery.data,
  //...
  state: {
    columnFilters, //pass controlled state back to the table (overrides internal state)
    sorting,
    pagination
  },
  onColumnFiltersChange: setColumnFilters, //hoist columnFilters state into our own state management
  onSortingChange: setSorting,
  onPaginationChange: setPagination,
})

const table = createSvelteTable(options)
//...

let sorting = [
  {
    id: 'age',
    desc: true, //sort by age in descending order by default
  },
]
const setSorting = updater => {
  if (updater instanceof Function) {
    sorting = updater(sorting)
  } else {
    sorting = updater
  }
  options.update(old => ({
    ...old,
    state: {
      ...old.state,
      sorting,
    },
  }))
}

let columnFilters = [] //no default filters
const setColumnFilters = updater => {
  if (updater instanceof Function) {
    columnFilters = updater(columnFilters)
  } else {
    columnFilters = updater
  }
  options.update(old => ({
    ...old,
    state: {
      ...old.state,
      columnFilters,
    },
  }))
}

let pagination = { pageIndex: 0, pageSize: 15 } //default pagination
const setPagination = updater => {
  if (updater instanceof Function) {
    pagination = updater(pagination)
  } else {
    pagination = updater
  }
  options.update(old => ({
    ...old,
    state: {
      ...old.state,
      pagination,
    },
  }))
}

//Use our controlled state values to fetch data
const tableQuery = createQuery({
  queryKey: ['users', columnFilters, sorting, pagination],
  queryFn: () => fetchUsers(columnFilters, sorting, pagination),
  //...
})

const options = writable({
  columns,
  data: tableQuery.data,
  //...
  state: {
    columnFilters, //pass controlled state back to the table (overrides internal state)
    sorting,
    pagination
  },
  onColumnFiltersChange: setColumnFilters, //hoist columnFilters state into our own state management
  onSortingChange: setSorting,
  onPaginationChange: setPagination,
})

const table = createSvelteTable(options)
//...

完全受控状态

或者，您可以使用 onStateChange 表格选项来控制整个表格状态。它会将整个表格状态“提升”到您自己的状态管理系统中。请谨慎使用此方法，因为您可能会发现将一些频繁变化的状态值（例如 columnSizingInfo 状态）提升到 Svelte 树的顶层会导致性能问题。

可能需要一些额外的技巧才能使其正常工作。如果您使用 onStateChange 表格选项，则 state 的初始值必须包含您要使用的所有功能的与所有相关状态值。您可以手动键入所有初始状态值，或者以特殊方式使用 table.setOptions API，如下所示。

jsx

//create a table instance with default state values
const options = writable({
  columns,
  data,
  //... Note: `state` values are NOT passed in yet
})
const table = createSvelteTable(options)

let state = {
  ...table.initialState, //populate the initial state with all of the default state values from the table instance
  pagination: {
    pageIndex: 0,
    pageSize: 15 //optionally customize the initial pagination state.
  }
}
const setState = updater => {
  if (updater instanceof Function) {
    state = updater(state)
  } else {
    state = updater
  }
  options.update(old => ({
    ...old,
    state,
  }))
}

//Use the table.setOptions API to merge our fully controlled state onto the table instance
table.setOptions(prev => ({
  ...prev, //preserve any other options that we have set up above
  state, //our fully controlled state overrides the internal state
  onStateChange: setState //any state changes will be pushed up to our own state management
}))

//create a table instance with default state values
const options = writable({
  columns,
  data,
  //... Note: `state` values are NOT passed in yet
})
const table = createSvelteTable(options)

let state = {
  ...table.initialState, //populate the initial state with all of the default state values from the table instance
  pagination: {
    pageIndex: 0,
    pageSize: 15 //optionally customize the initial pagination state.
  }
}
const setState = updater => {
  if (updater instanceof Function) {
    state = updater(state)
  } else {
    state = updater
  }
  options.update(old => ({
    ...old,
    state,
  }))
}

//Use the table.setOptions API to merge our fully controlled state onto the table instance
table.setOptions(prev => ({
  ...prev, //preserve any other options that we have set up above
  state, //our fully controlled state overrides the internal state
  onStateChange: setState //any state changes will be pushed up to our own state management
}))

状态变更回调

到目前为止，我们已经看到了 on[State]Change 和 onStateChange 表格选项如何工作，将表格状态更改“提升”到我们自己的状态管理中。然而，在使用这些选项时，有几点您应该注意。

1. 状态变更回调必须在其 state 选项中包含相应的状态值。

指定 on[State]Change 回调函数会告知表格实例这是一个受控状态。如果您未指定相应的 state 值，该状态将“冻结”在其初始值。

let sorting = []
const setSorting = updater => {
  if (updater instanceof Function) {
    sorting = updater(sorting)
  } else {
    sorting = updater
  }
  options.update(old => ({
    ...old,
    state: {
      ...old.state,
      sorting,
    },
  }))
}
//...
const options = writable({
  columns,
  data,
  //...
  state: {
    sorting, //required because we are using `onSortingChange`
  },
  onSortingChange: setSorting, //makes the `state.sorting` controlled
})
const table = createSvelteTable(options)

let sorting = []
const setSorting = updater => {
  if (updater instanceof Function) {
    sorting = updater(sorting)
  } else {
    sorting = updater
  }
  options.update(old => ({
    ...old,
    state: {
      ...old.state,
      sorting,
    },
  }))
}
//...
const options = writable({
  columns,
  data,
  //...
  state: {
    sorting, //required because we are using `onSortingChange`
  },
  onSortingChange: setSorting, //makes the `state.sorting` controlled
})
const table = createSvelteTable(options)

2. 更新器可以是原始值，也可以是回调函数。

on[State]Change 和 onStateChange 回调函数的工作方式与 React 中的 setState 函数完全相同。更新值可以是新的状态值，也可以是一个函数，该函数接收前一个状态值并返回新的状态值。

这有什么影响？这意味着如果您想在任何 on[State]Change 回调函数中添加一些额外的逻辑，您可以这样做，但您需要检查新的传入更新值是函数还是值。

这就是为什么您会在上面的示例的 setState 函数中看到 if (updater instanceof Function) 检查。

状态类型

TanStack Table 中的所有复杂状态都有自己的 TypeScript 类型，您可以导入并使用它们。这对于确保您正在为要控制的状态值使用正确的数据结构和属性非常有用。

import { createSvelteTable, type SortingState, type Updater } from '@tanstack/svelte-table'
//...
let sorting: SortingState[] = [
  {
    id: 'age', //you should get autocomplete for the `id` and `desc` properties
    desc: true,
  }
]
const setSorting = (updater: Updater<SortingState>)  => {
  if (updater instanceof Function) {
    sorting = updater(sorting)
  } else {
    sorting = updater
  }
  options.update(old => ({
    ...old,
    state: {
      ...old.state,
      sorting,
    },
  }))
}

import { createSvelteTable, type SortingState, type Updater } from '@tanstack/svelte-table'
//...
let sorting: SortingState[] = [
  {
    id: 'age', //you should get autocomplete for the `id` and `desc` properties
    desc: true,
  }
]
const setSorting = (updater: Updater<SortingState>)  => {
  if (updater instanceof Function) {
    sorting = updater(sorting)
  } else {
    sorting = updater
  }
  options.update(old => ({
    ...old,
    state: {
      ...old.state,
      sorting,
    },
  }))
}

Table State (Svelte) 指南