Tabellenstatus (Vue) Anleitung

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.

const table = useVueTable({
  columns,
  data: dataRef, // Reactive data support
  //...
})

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

const table = useVueTable({
  columns,
  data: dataRef, // Reactive data support
  //...
})

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

Reaktive Daten verwenden

Neu in v8.20.0

Der useVueTable Hook unterstützt jetzt reaktive Daten. Das bedeutet, dass Sie einen Vue ref oder computed, der Ihre Daten enthält, an die data-Option übergeben können. Die Tabelle reagiert automatisch auf Änderungen der Daten.

const columns = [
  { accessor: 'id', Header: 'ID' },
  { accessor: 'name', Header: 'Name' }
]

const dataRef = ref([
  { id: 1, name: 'John' },
  { id: 2, name: 'Jane' }
])

const table = useVueTable({
  columns,
  data: dataRef, // Pass the reactive data ref
})

// Later, updating dataRef will automatically update the table
dataRef.value = [
  { id: 1, name: 'John' },
  { id: 2, name: 'Jane' },
  { id: 3, name: 'Doe' }
]

const columns = [
  { accessor: 'id', Header: 'ID' },
  { accessor: 'name', Header: 'Name' }
]

const dataRef = ref([
  { id: 1, name: 'John' },
  { id: 2, name: 'Jane' }
])

const table = useVueTable({
  columns,
  data: dataRef, // Pass the reactive data ref
})

// Later, updating dataRef will automatically update the table
dataRef.value = [
  { id: 1, name: 'John' },
  { id: 2, name: 'Jane' },
  { id: 3, name: 'Doe' }
]

⚠️ shallowRef wird aus Performance-Gründen im Hintergrund verwendet, was bedeutet, dass die Daten nicht tief reaktiv sind, sondern nur der .value. Um die Daten zu aktualisieren, müssen Sie die Daten direkt verändern.

const dataRef = ref([
  { id: 1, name: 'John' },
  { id: 2, name: 'Jane' }
])

// This will NOT update the table ❌
dataRef.value.push({ id: 4, name: 'John' })

// This will update the table ✅
dataRef.value = [
  ...dataRef.value,
  { id: 4, name: 'John' }
]

const dataRef = ref([
  { id: 1, name: 'John' },
  { id: 2, name: 'Jane' }
])

// This will NOT update the table ❌
dataRef.value.push({ id: 4, name: 'John' })

// This will update the table ✅
dataRef.value = [
  ...dataRef.value,
  { id: 4, name: 'John' }
]

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 = useVueTable({
  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 = useVueTable({
  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.

const columnFilters = ref([]) //no default filters
const sorting = ref([{
  id: 'age',
  desc: true, //sort by age in descending order by default
}])
const pagination = ref({ 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 = useVueTable({
  columns,
  data: tableQuery.data,
  //...
  state: {
    get columnFilters() {
      return columnFilters.value
    },
    get sorting() {
      return sorting.value
    },
    get pagination() {
      return pagination.value
    }
  },
  onColumnFiltersChange: updater => {
    columnFilters.value =
      updater instanceof Function
        ? updater(columnFilters.value)
        : updater
  },
  onSortingChange: updater => {
    sorting.value =
      updater instanceof Function
        ? updater(sorting.value)
        : updater
  },
  onPaginationChange: updater => {
    pagination.value =
      updater instanceof Function
        ? updater(pagination.value)
        : updater
  },
})
//...

const columnFilters = ref([]) //no default filters
const sorting = ref([{
  id: 'age',
  desc: true, //sort by age in descending order by default
}])
const pagination = ref({ 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 = useVueTable({
  columns,
  data: tableQuery.data,
  //...
  state: {
    get columnFilters() {
      return columnFilters.value
    },
    get sorting() {
      return sorting.value
    },
    get pagination() {
      return pagination.value
    }
  },
  onColumnFiltersChange: updater => {
    columnFilters.value =
      updater instanceof Function
        ? updater(columnFilters.value)
        : updater
  },
  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 onStateChange Tabellenoption steuern. Sie wird den gesamten Tabellenstatus in Ihr eigenes Zustandsverwaltungssystem auslagern. Seien Sie vorsichtig mit diesem Ansatz, da Sie feststellen könnten, dass das Hochheben einiger sich häufig ändernder Zustandsvariablen in einem React-Baum, wie der columnSizingInfo-Status`, schlechte Performance-Probleme verursachen könnte.

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

const state = ref({
  ...table.initialState,
  pagination: {
    pageIndex: 0,
    pageSize: 15
  }
})
const setState = updater => {
  state.value = updater instanceof Function ? updater(state.value) : updater
}

//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
  get state() {
    return state.value
  },
  onStateChange: setState //any state changes will be pushed up to our own state management
}))

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

const state = ref({
  ...table.initialState,
  pagination: {
    pageIndex: 0,
    pageSize: 15
  }
})
const setState = updater => {
  state.value = updater instanceof Function ? updater(state.value) : updater
}

//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
  get state() {
    return state.value
  },
  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 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 = ref([])
const setSorting = updater => {
  sorting.value = updater instanceof Function ? updater(sorting.value) : updater
}
//...
const table = useVueTable({
  columns,
  data,
  //...
  state: {
    get sorting() {
      return sorting //required because we are using `onSortingChange`
    },
  },
  onSortingChange: setSorting, //makes the `state.sorting` controlled
})

const sorting = ref([])
const setSorting = updater => {
  sorting.value = updater instanceof Function ? updater(sorting.value) : updater
}
//...
const table = useVueTable({
  columns,
  data,
  //...
  state: {
    get sorting() {
      return 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.

Deshalb haben wir die updater instanceof Function Prüfung in den setState Funktionen oben. Diese Prüfung ermöglicht es uns, sowohl rohe Werte als auch Callback-Funktionen in derselben Funktion zu verarbeiten.

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

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

Tabellenstatus (Vue) Anleitung