Tabellenstatus (React) Leitfaden

Beispiele

Möchten Sie direkt zur Implementierung springen? Sehen Sie sich diese Beispiele an

TanStack Table verfügt über ein einfaches internes Zustandsverwaltungssystem, um den Zustand der Tabelle zu speichern und zu verwalten. Es ermöglicht Ihnen auch, jeden benötigten Zustand selektiv herauszuziehen, um ihn in Ihrer eigenen Zustandsverwaltung zu verwalten. Diese Anleitung führt Sie durch die verschiedenen Möglichkeiten, wie Sie mit dem Zustand der Tabelle interagieren und ihn verwalten können.

Zugriff auf den Tabellenstatus

Sie müssen nichts Besonderes einrichten, damit der Tabellenstatus funktioniert. Wenn Sie nichts in die Optionen state, initialState oder einen der on[State]Change Tabellenoptionen übergeben, verwaltet die Tabelle ihren eigenen Zustand intern. Sie können auf jeden Teil dieses internen Zustands zugreifen, indem Sie die table.getState() API der Tabelleninstanz verwenden.

jsx

const table = useReactTable({
  columns,
  data,
  //...
})

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

const table = useReactTable({
  columns,
  data,
  //...
})

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

Benutzerdefinierter Anfangszustand

Wenn alles, was Sie für bestimmte Zustände tun müssen, darin besteht, ihre anfänglichen Standardwerte anzupassen, müssen Sie den Zustand immer noch nicht selbst verwalten. Sie können einfach Werte in der Option initialState der Tabelleninstanz festlegen.

jsx

const table = useReactTable({
  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 = useReactTable({
  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
      }
    ]
  },
  //...
})

Hinweis: Geben Sie jeden bestimmten Zustand nur entweder in initialState oder state an, aber nicht in beiden. Wenn Sie einen bestimmten Zustandswert sowohl an initialState als auch an state übergeben, überschreibt der initialisierte Zustand in state jeden entsprechenden Wert in initialState.

Gesteuerter Zustand

Wenn Sie einfachen Zugriff auf den Tabellenstatus in anderen Bereichen Ihrer Anwendung benötigen, macht es TanStack Table einfach, jeden oder den gesamten Tabellenstatus in Ihrem eigenen Zustandsverwaltungssystem zu steuern und zu verwalten. Dies können Sie tun, indem Sie Ihren eigenen Zustand und Ihre eigenen Zustandsverwaltungsfunktionen an die Tabellenoptionen state und on[State]Change übergeben.

Individuell gesteuerter Zustand

Sie können nur den Zustand steuern, auf den Sie einfachen Zugriff benötigen. Sie müssen NICHT den gesamten Tabellenstatus steuern, wenn Sie dies nicht tun müssen. Es wird empfohlen, nur den Zustand zu steuern, den Sie von Fall zu Fall benötigen.

Um einen bestimmten Zustand zu steuern, müssen Sie sowohl den entsprechenden state-Wert als auch die Funktion on[State]Change an die Tabelleninstanz übergeben.

Nehmen wir Filterung, Sortierung und Paginierung als Beispiel in einem "manuellen" serverseitigen Datenabrufszenario. Sie können den Filter-, Sortier- und Paginierungsstatus in Ihrer eigenen Zustandsverwaltung speichern, aber andere Zustände wie Spaltenreihenfolge, Spalten-Sichtbarkeit usw. weglassen, wenn Ihre API diese Werte nicht benötigt.

jsx

const [columnFilters, setColumnFilters] = React.useState([]) //no default filters
const [sorting, setSorting] = React.useState([{
  id: 'age',
  desc: true, //sort by age in descending order by default
}]) 
const [pagination, setPagination] = React.useState({ pageIndex: 0, pageSize: 15 })

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

const table = useReactTable({
  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 [columnFilters, setColumnFilters] = React.useState([]) //no default filters
const [sorting, setSorting] = React.useState([{
  id: 'age',
  desc: true, //sort by age in descending order by default
}]) 
const [pagination, setPagination] = React.useState({ pageIndex: 0, pageSize: 15 })

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

const table = useReactTable({
  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,
})
//...

Vollständig gesteuerter Zustand

Alternativ können Sie den gesamten Tabellenstatus über die onStateChange Tabellenoption steuern. Dies verschiebt den gesamten Tabellenstatus in Ihr eigenes Zustandsverwaltungssystem. Seien Sie vorsichtig mit diesem Ansatz, da die Übertragung einiger sich häufig ändernder Zustandsgrößen wie des columnSizingInfo Zustands hoch in einen React-Baum zu Leistungsproblemen führen kann.

Ein paar weitere Tricks könnten notwendig sein, damit dies funktioniert. Wenn Sie die onStateChange Tabellenoption verwenden, müssen die Anfangswerte des state mit allen relevanten Zustandsgrößen für alle Funktionen gefüllt werden, die Sie verwenden möchten. Sie können entweder alle Anfangszustandsgrößen manuell eingeben oder die table.setOptions API auf besondere Weise verwenden, wie unten gezeigt.

jsx

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


const [state, setState] = React.useState({
  ...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.
  }
})

//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 table = useReactTable({
  columns,
  data,
  //... Note: `state` values are NOT passed in yet
})


const [state, setState] = React.useState({
  ...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.
  }
})

//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
}))

Callbacks für Zustandsänderungen

Bisher haben wir gesehen, wie die Tabellenoptionen on[State]Change und onStateChange dazu dienen, die Tabellenstatusänderungen in unsere eigene Zustandsverwaltung zu "verschieben". Es gibt jedoch ein paar Dinge, die Sie bei der Verwendung dieser Optionen beachten sollten.

1. Callbacks für Zustandsänderungen MÜSSEN ihren entsprechenden Zustands-Wert in der Option state haben.

Die Angabe eines on[State]Change-Callbacks teilt der Tabelleninstanz mit, dass dies ein gesteuerter Zustand sein wird. Wenn Sie den entsprechenden state-Wert nicht angeben, wird dieser Zustand mit seinem Anfangswert "eingefroren".

jsx

const [sorting, setSorting] = React.useState([])
//...
const table = useReactTable({
  columns,
  data,
  //...
  state: {
    sorting, //required because we are using `onSortingChange`
  },
  onSortingChange: setSorting, //makes the `state.sorting` controlled
})

const [sorting, setSorting] = React.useState([])
//...
const table = useReactTable({
  columns,
  data,
  //...
  state: {
    sorting, //required because we are using `onSortingChange`
  },
  onSortingChange: setSorting, //makes the `state.sorting` controlled
})

2. Aktualisierer können entweder Rohwerte oder Callback-Funktionen sein.

Die Callbacks on[State]Change und onStateChange funktionieren genau wie die setState-Funktionen in React. Die Updater-Werte können entweder ein neuer Zustandswert oder eine Callback-Funktion sein, die den vorherigen Zustandswert übernimmt und den neuen Zustandswert zurückgibt.

Welche Auswirkungen hat das? Das bedeutet, dass Sie, wenn Sie zusätzliche Logik in einem der on[State]Change-Callbacks hinzufügen möchten, dies tun können, aber Sie müssen prüfen, ob der neue eingehende Updater-Wert eine Funktion oder ein Wert ist.

jsx

const [sorting, setSorting] = React.useState([])
const [pagination, setPagination] = React.useState({ pageIndex: 0, pageSize: 10 })

const table = useReactTable({
  columns,
  data,
  //...
  state: {
    pagination,
    sorting,
  }
  //syntax 1
  onPaginationChange: (updater) => {
    setPagination(old => {
      const newPaginationValue = updater instanceof Function ? updater(old) : updater
      //do something with the new pagination value
      //...
      return newPaginationValue
    })
  },
  //syntax 2
  onSortingChange: (updater) => {
    const newSortingValue = updater instanceof Function ? updater(sorting) : updater
    //do something with the new sorting value
    //...
    setSorting(updater) //normal state update
  }
})

const [sorting, setSorting] = React.useState([])
const [pagination, setPagination] = React.useState({ pageIndex: 0, pageSize: 10 })

const table = useReactTable({
  columns,
  data,
  //...
  state: {
    pagination,
    sorting,
  }
  //syntax 1
  onPaginationChange: (updater) => {
    setPagination(old => {
      const newPaginationValue = updater instanceof Function ? updater(old) : updater
      //do something with the new pagination value
      //...
      return newPaginationValue
    })
  },
  //syntax 2
  onSortingChange: (updater) => {
    const newSortingValue = updater instanceof Function ? updater(sorting) : updater
    //do something with the new sorting value
    //...
    setSorting(updater) //normal state update
  }
})

Zustandstypen

Alle komplexen Zustände in TanStack Table haben ihre eigenen TypeScript-Typen, die Sie importieren und verwenden können. Dies kann hilfreich sein, um sicherzustellen, dass Sie die richtigen Datenstrukturen und Eigenschaften für die von Ihnen gesteuerten Zustandswerte verwenden.

tsx

import { useReactTable, type SortingState } from '@tanstack/react-table'
//...
const [sorting, setSorting] = React.useState<SortingState[]>([
  {
    id: 'age', //you should get autocomplete for the `id` and `desc` properties
    desc: true,
  }
])

import { useReactTable, type SortingState } from '@tanstack/react-table'
//...
const [sorting, setSorting] = React.useState<SortingState[]>([
  {
    id: 'age', //you should get autocomplete for the `id` and `desc` properties
    desc: true,
  }
])

Tabellenstatus (React) Leitfaden

Beispiele