Tabelleninstanz-Anleitung

Tabellen-API

TanStack Table ist eine Headless-UI-Bibliothek. Wenn wir von der Tabelle oder "Tabelleninstanz" sprechen, meinen wir kein tatsächliches <table>-Element. Stattdessen beziehen wir uns auf das Kernobjekt der Tabelle, das den Zustand und die APIs der Tabelle enthält. Die Tabelleninstanz wird durch Aufrufen der createTable-Funktion Ihres Adapters erstellt (z. B. useReactTable, createSolidTable, createSvelteTable, useQwikTable, useVueTable).

Zum Erstellen einer Tabelleninstanz sind 2 Optionen erforderlich: columns und data. Es gibt Dutzende weiterer Tabellenoptionen zur Konfiguration von Funktionen und Verhalten, aber diese 2 sind erforderlich.

data ist ein Array von Objekten, die in die Zeilen Ihrer Tabelle umgewandelt werden. Jedes Objekt im Array stellt eine Datenzeile dar (unter normalen Umständen). Wenn Sie TypeScript verwenden, definieren wir normalerweise einen Typ für die Form unserer Daten. Dieser Typ wird als generischer Typ für alle anderen Tabellen-, Spalten-, Zeilen- und Zellinstanzen verwendet. Dieser Typ wird üblicherweise als TData bezeichnet.

Wenn wir zum Beispiel eine Tabelle haben, die eine Liste von Benutzern in einem Array wie diesem anzeigt

[
  {
    "firstName": "Tanner",
    "lastName": "Linsley",
    "age": 33,
    "visits": 100,
    "progress": 50,
    "status": "Married"
  },
  {
    "firstName": "Kevin",
    "lastName": "Vandy",
    "age": 27,
    "visits": 200,
    "progress": 100,
    "status": "Single"
  }
]

[
  {
    "firstName": "Tanner",
    "lastName": "Linsley",
    "age": 33,
    "visits": 100,
    "progress": 50,
    "status": "Married"
  },
  {
    "firstName": "Kevin",
    "lastName": "Vandy",
    "age": 27,
    "visits": 200,
    "progress": 100,
    "status": "Single"
  }
]

Dann können wir einen Benutzertyp (TData) wie diesen definieren

//TData
type User = {
  firstName: string
  lastName: string
  age: number
  visits: number
  progress: number
  status: string
}

//TData
type User = {
  firstName: string
  lastName: string
  age: number
  visits: number
  progress: number
  status: string
}

Wir können dann unser data-Array mit diesem Typ definieren, und TanStack Table kann dann später für uns viele Typen in unseren Spalten, Zeilen, Zellen usw. intelligent ableiten.

//note: data needs a "stable" reference in order to prevent infinite re-renders
const data: User[] = []
//or
const [data, setData] = React.useState<User[]>([])
//or
const data = ref<User[]>([])
//etc...

//note: data needs a "stable" reference in order to prevent infinite re-renders
const data: User[] = []
//or
const [data, setData] = React.useState<User[]>([])
//or
const data = ref<User[]>([])
//etc...

Hinweis: data benötigt eine "stabile" Referenz (besonders in React), um unendliche Neuberechnungen zu verhindern. Deshalb empfehlen wir die Verwendung von React.useState oder React.useMemo, oder das Definieren Ihrer Daten außerhalb derselben React-Komponente, die die Tabelleninstanz erstellt, oder die Verwendung einer Bibliothek wie TanStack Query zur Verwaltung Ihres Datenzustands.

Spaltendefinitionen werden im nächsten Abschnitt ausführlich im Leitfaden für Spaltendefinitionen behandelt. Wir weisen hier jedoch darauf hin, dass Sie beim Definieren des Typs Ihrer Spalten denselben TData-Typ verwenden sollten, den Sie für Ihre Daten verwendet haben.

const columns: ColumnDef<User>[] = [] //Pass User type as the generic TData type
//or
const columnHelper = createColumnHelper<User>() //Pass User type as the generic TData type

const columns: ColumnDef<User>[] = [] //Pass User type as the generic TData type
//or
const columnHelper = createColumnHelper<User>() //Pass User type as the generic TData type

In den Spaltendefinitionen legen wir fest, wie jede Spalte Zeilendaten mit einem accessorKey oder accessorFn abrufen und/oder transformieren soll. Weitere Informationen finden Sie im Leitfaden für Spaltendefinitionen.

Mit unseren definierten columns und data können wir nun unsere grundlegende Tabelleninstanz erstellen.

//vanilla js
const table = createTable({ columns, data })

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

//solid
const table = createSolidTable({ columns, data })

//svelte
const table = createSvelteTable({ columns, data })

//vue
const table = useVueTable({ columns, data })

//vanilla js
const table = createTable({ columns, data })

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

//solid
const table = createSolidTable({ columns, data })

//svelte
const table = createSvelteTable({ columns, data })

//vue
const table = useVueTable({ columns, data })

Was befindet sich also in der Tabelleninstanz? Werfen wir einen Blick darauf, welche Interaktionen wir mit der Tabelleninstanz haben können.

Die Tabelleninstanz enthält den gesamten Zustand der Tabelle, auf den über die API table.getState() zugegriffen werden kann. Jede Tabellenfunktion registriert verschiedene Zustände im Zustand der Tabelle. So registriert beispielsweise die Zeilenauswahlfunktion den rowSelection-Status, die Paginierungsfunktion den pagination-Status usw.

Jede Funktion hat auch entsprechende Status-Setter-APIs und Status-Resetter-APIs auf der Tabelleninstanz. So hat die Zeilenauswahlfunktion beispielsweise eine setRowSelection-API und eine resetRowSelection.

table.getState().rowSelection //read the row selection state
table.setRowSelection((old) => ({...old})) //set the row selection state
table.resetRowSelection() //reset the row selection state

table.getState().rowSelection //read the row selection state
table.setRowSelection((old) => ({...old})) //set the row selection state
table.resetRowSelection() //reset the row selection state

Es gibt Dutzende von Tabellen-APIs, die von jeder Funktion erstellt werden, um Ihnen zu helfen, den Tabellenstatus auf verschiedene Weise zu lesen oder zu ändern.

API-Referenzdokumente für die Kern-Tabelleninstanz und alle anderen Funktions-APIs finden Sie in den API-Dokumenten.

Die API-Dokumentation für die Kern-Tabelleninstanz finden Sie hier: Tabellen-API

Es gibt einen speziellen Satz von Tabelleninstanz-APIs zum Auslesen von Zeilen aus der Tabelleninstanz, die als Zeilenmodelle bezeichnet werden. TanStack Table verfügt über fortschrittliche Funktionen, bei denen die generierten Zeilen erheblich von dem Array der ursprünglich übergebenen data abweichen können. Um mehr über die verschiedenen Zeilenmodelle zu erfahren, die Sie als Tabellenoption übergeben können, lesen Sie den Leitfaden für Zeilenmodelle.