Tabellenstatus (Qwik) – Leitfaden | TanStack Table Qwik Doku

Tabellenstatus (Qwik) – Leitfaden

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 = useQwikTable({
  columns,
  data,
  //...
})

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

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

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

const table = useQwikTable({
  columns: columns.value,
  data: tableQuery.data,
  //...
  state: {
    columnFilters: columnFilters.value, //pass controlled state back to the table (overrides internal state)
    sorting: sorting.value,
    pagination: pagination.value,
  },
  onColumnFiltersChange: updater => {
    columnFilters.value = updater instanceof Function ? updater(columnFilters.value) : updater //hoist columnFilters state into our own state management
  },
  onSortingChange: updater => {
    sorting.value = updater instanceof Function ? updater(sorting.value) : updater
  },
  onPaginationChange: updater => {
    pagination.value = updater instanceof Function ? updater(pagination.value) : updater
  },
})
//...

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

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

const table = useQwikTable({
  columns: columns.value,
  data: tableQuery.data,
  //...
  state: {
    columnFilters: columnFilters.value, //pass controlled state back to the table (overrides internal state)
    sorting: sorting.value,
    pagination: pagination.value,
  },
  onColumnFiltersChange: updater => {
    columnFilters.value = updater instanceof Function ? updater(columnFilters.value) : updater //hoist columnFilters state into our own state management
  },
  onSortingChange: updater => {
    sorting.value = updater instanceof Function ? updater(sorting.value) : updater
  },
  onPaginationChange: updater => {
    pagination.value = updater instanceof Function ? updater(pagination.value) : updater
  },
})
//...

Vollständig gesteuerter Zustand

Alternativ können Sie den gesamten Tabellenstatus mit der Tabellenoption onStateChange steuern. Dies wird den gesamten Tabellenstatus in Ihr eigenes Zustandsverwaltungssystem "hoisten". Seien Sie bei diesem Ansatz vorsichtig, da die Übertragung einiger sich häufig ändernder Zustände nach oben in einer Komponentenstruktur, wie z. B. der columnSizingInfo-Status, 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 = useQwikTable({
  columns,
  data,
  //... Note: `state` values are NOT passed in yet
})


const sate = Qwik.useSignal({
  ...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: state.value, //our fully controlled state overrides the internal state
  onStateChange: updater => {
    state.value = updater instanceof Function ? updater(state.value) : updater //any state changes will be pushed up to our own state management
  },
}))

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


const sate = Qwik.useSignal({
  ...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: state.value, //our fully controlled state overrides the internal state
  onStateChange: updater => {
    state.value = updater instanceof Function ? updater(state.value) : updater //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 die Tabellenstatusänderungen in unsere eigene Zustandsverwaltung "hoisten". 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 = Qwik.useSignal([])
//...
const table = useQwikTable({
  columns,
  data,
  //...
  state: {
    sorting: sorting.value, //required because we are using `onSortingChange`
  },
  onSortingChange: updater => {
    sorting.value = updater instanceof Function ? updater(sorting) : updater //makes the `state.sorting` controlled
  }, 
})

const sorting = Qwik.useSignal([])
//...
const table = useQwikTable({
  columns,
  data,
  //...
  state: {
    sorting: sorting.value, //required because we are using `onSortingChange`
  },
  onSortingChange: updater => {
    sorting.value = updater instanceof Function ? updater(sorting) : updater //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.

Deshalb sehen Sie das Muster updater instanceof Function ? updater(state.value) : updater in den obigen Beispielen. Dieses Muster prüft, ob der Updater eine Funktion ist, und wenn ja, ruft es die Funktion mit dem vorherigen Zustandswert auf, um den neuen Zustandswert zu erhalten.

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 { useQwikTable, type SortingState } from '@tanstack/qwik-table'
//...
const sorting = Qwik.useSignal<SortingState[]>([
  {
    id: 'age', //you should get autocomplete for the `id` and `desc` properties
    desc: true,
  }
])

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

Tabellenstatus (Qwik) – Leitfaden