Pagination Guide

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

• pagination
• pagination-controlled (React Query)
• editable-data
• expanding
• filters
• fully-controlled
• row-selection

Pagination API

TanStack Table bietet hervorragende Unterstützung für client-seitige und server-seitige Pagination. Diese Anleitung führt Sie durch die verschiedenen Möglichkeiten, Pagination in Ihrer Tabelle zu implementieren.

Die Verwendung von client-seitiger Pagination bedeutet, dass die von Ihnen abgerufenen Daten ALLE Zeilen für die Tabelle enthalten, und die Tabelleninstanz übernimmt die Pagination-Logik im Frontend.

Client-seitige Pagination ist normalerweise der einfachste Weg, Pagination mit TanStack Table zu implementieren, aber sie ist möglicherweise nicht praktikabel für sehr große Datensätze.

Viele unterschätzen jedoch, wie viele Daten client-seitig verarbeitet werden können. Wenn Ihre Tabelle nur ein paar Tausend Zeilen oder weniger haben wird, kann client-seitige Pagination immer noch eine praktikable Option sein. TanStack Table ist darauf ausgelegt, bis zu Zehntausende von Zeilen mit guter Leistung für Pagination, Filterung, Sortierung und Gruppierung zu skalieren. Das offizielle Pagination-Beispiel lädt 100.000 Zeilen und leistet immer noch gute Arbeit, wenn auch mit nur einer Handvoll Spalten.

Jeder Anwendungsfall ist anders und hängt von der Komplexität der Tabelle ab, wie viele Spalten Sie haben, wie groß jede Datenmenge ist usw. Die Hauptengpässe, auf die Sie achten sollten, sind:

1. Kann Ihr Server alle Daten in angemessener Zeit (und zu angemessenen Kosten) abfragen?
2. Wie groß ist die gesamte Abfragegröße? (Dies skaliert möglicherweise nicht so schlecht, wie Sie denken, wenn Sie nicht viele Spalten haben.)
3. Verbraucht der Browser des Clients zu viel Speicher, wenn alle Daten auf einmal geladen werden?

Wenn Sie sich nicht sicher sind, können Sie immer mit client-seitiger Pagination beginnen und später zu server-seitiger Pagination wechseln, wenn Ihre Datenmenge wächst.

Alternativ können Sie, anstatt die Daten zu paginieren, alle Zeilen eines großen Datensatzes auf derselben Seite rendern, aber nur die Ressourcen des Browsers verwenden, um die Zeilen zu rendern, die im Ansichtsfenster sichtbar sind. Diese Strategie wird oft als "Virtualisierung" oder "Windowing" bezeichnet. TanStack bietet eine Virtualisierungsbibliothek namens TanStack Virtual, die gut mit TanStack Table zusammenarbeiten kann. Die UI/UX von Virtualisierung und Pagination haben beide ihre eigenen Vor- und Nachteile, also sehen Sie, welche für Ihren Anwendungsfall am besten geeignet ist.

Wenn Sie die integrierte client-seitige Pagination in TanStack Table nutzen möchten, müssen Sie zuerst das Pagination Row Model übergeben.

import { useReactTable, getCoreRowModel, getPaginationRowModel } from '@tanstack/react-table';
//...
const table = useReactTable({
  columns,
  data,
  getCoreRowModel: getCoreRowModel(),
  getPaginationRowModel: getPaginationRowModel(), //load client-side pagination code
});

import { useReactTable, getCoreRowModel, getPaginationRowModel } from '@tanstack/react-table';
//...
const table = useReactTable({
  columns,
  data,
  getCoreRowModel: getCoreRowModel(),
  getPaginationRowModel: getPaginationRowModel(), //load client-side pagination code
});

Wenn Sie sich entscheiden, dass Sie server-seitige Pagination verwenden müssen, ist hier, wie Sie sie implementieren können.

Für server-seitige Pagination ist kein Pagination Row Model erforderlich, aber wenn Sie es für andere Tabellen bereitgestellt haben, die es in einer gemeinsamen Komponente benötigen, können Sie die client-seitige Pagination deaktivieren, indem Sie die Option manualPagination auf true setzen. Das Setzen der Option manualPagination auf true weist die Tabelleninstanz an, das table.getPrePaginationRowModel Row Model im Hintergrund zu verwenden, und es veranlasst die Tabelleninstanz anzunehmen, dass die von Ihnen übergebenen Daten bereits paginiert sind.

Die Tabelleninstanz wird nicht wissen können, wie viele Zeilen/Seiten insgesamt auf Ihrem Backend vorhanden sind, es sei denn, Sie teilen es ihr mit. Stellen Sie entweder die Tabellenoption rowCount oder pageCount bereit, um die Tabelleninstanz über die Gesamtzahl der Seiten zu informieren. Wenn Sie eine rowCount angeben, berechnet die Tabelleninstanz die pageCount intern aus rowCount und pageSize. Andernfalls können Sie die pageCount direkt angeben, wenn Sie sie bereits haben. Wenn Sie die Seitenanzahl nicht kennen, können Sie einfach -1 für die pageCount übergeben, aber die Funktionen des Row Models getCanNextPage und getCanPreviousPage geben in diesem Fall immer true zurück.

import { useReactTable, getCoreRowModel, getPaginationRowModel } from '@tanstack/react-table';
//...
const table = useReactTable({
  columns,
  data,
  getCoreRowModel: getCoreRowModel(),
  // getPaginationRowModel: getPaginationRowModel(), //not needed for server-side pagination
  manualPagination: true, //turn off client-side pagination
  rowCount: dataQuery.data?.rowCount, //pass in the total row count so the table knows how many pages there are (pageCount calculated internally if not provided)
  // pageCount: dataQuery.data?.pageCount, //alternatively directly pass in pageCount instead of rowCount
});

import { useReactTable, getCoreRowModel, getPaginationRowModel } from '@tanstack/react-table';
//...
const table = useReactTable({
  columns,
  data,
  getCoreRowModel: getCoreRowModel(),
  // getPaginationRowModel: getPaginationRowModel(), //not needed for server-side pagination
  manualPagination: true, //turn off client-side pagination
  rowCount: dataQuery.data?.rowCount, //pass in the total row count so the table knows how many pages there are (pageCount calculated internally if not provided)
  // pageCount: dataQuery.data?.pageCount, //alternatively directly pass in pageCount instead of rowCount
});

Hinweis: Das Setzen der Option manualPagination auf true veranlasst die Tabelleninstanz anzunehmen, dass die von Ihnen übergebenen Daten bereits paginiert sind.

Unabhängig davon, ob Sie client-seitige oder manuelle server-seitige Pagination verwenden, können Sie den integrierten pagination State und die APIs nutzen.

Der pagination State ist ein Objekt, das die folgenden Eigenschaften enthält:

• pageIndex: Der aktuelle Seitenindex (nullbasiert).
• pageSize: Die aktuelle Seitengröße.

Sie können den pagination State wie jeden anderen State in der Tabelleninstanz verwalten.

import { useReactTable, getCoreRowModel, getPaginationRowModel } from '@tanstack/react-table';
//...
const [pagination, setPagination] = useState({
  pageIndex: 0, //initial page index
  pageSize: 10, //default page size
});

const table = useReactTable({
  columns,
  data,
  getCoreRowModel: getCoreRowModel(),
  getPaginationRowModel: getPaginationRowModel(),
  onPaginationChange: setPagination, //update the pagination state when internal APIs mutate the pagination state
  state: {
    //...
    pagination,
  },
});

import { useReactTable, getCoreRowModel, getPaginationRowModel } from '@tanstack/react-table';
//...
const [pagination, setPagination] = useState({
  pageIndex: 0, //initial page index
  pageSize: 10, //default page size
});

const table = useReactTable({
  columns,
  data,
  getCoreRowModel: getCoreRowModel(),
  getPaginationRowModel: getPaginationRowModel(),
  onPaginationChange: setPagination, //update the pagination state when internal APIs mutate the pagination state
  state: {
    //...
    pagination,
  },
});

Alternativ, wenn Sie den pagination State nicht in Ihrem eigenen Scope verwalten müssen, aber unterschiedliche Anfangswerte für pageIndex und pageSize setzen müssen, können Sie die Option initialState verwenden.

const table = useReactTable({
  columns,
  data,
  getCoreRowModel: getCoreRowModel(),
  getPaginationRowModel: getPaginationRowModel(),
  initialState: {
    pagination: {
      pageIndex: 2, //custom initial page index
      pageSize: 25, //custom default page size
    },
  },
});

const table = useReactTable({
  columns,
  data,
  getCoreRowModel: getCoreRowModel(),
  getPaginationRowModel: getPaginationRowModel(),
  initialState: {
    pagination: {
      pageIndex: 2, //custom initial page index
      pageSize: 25, //custom default page size
    },
  },
});

Hinweis: Übergeben Sie den pagination State NICHT sowohl an die Optionen state als auch initialState. state überschreibt initialState. Verwenden Sie nur eine der beiden.

Neben den Optionen manualPagination, pageCount und rowCount, die für die manuelle server-seitige Pagination nützlich sind (und oben besprochen wurden), gibt es eine weitere Tabellenoption, die es wert ist, verstanden zu werden.

Standardmäßig wird der pageIndex auf 0 zurückgesetzt, wenn sich seitengerechte Zustandsänderungen ereignen, wie z. B. wenn die Daten aktualisiert werden, sich Filter ändern, Gruppierungen sich ändern usw. Dieses Verhalten wird automatisch deaktiviert, wenn manualPagination true ist, kann aber überschrieben werden, indem explizit ein boolescher Wert der Tabellenoption autoResetPageIndex zugewiesen wird.

const table = useReactTable({
  columns,
  data,
  getCoreRowModel: getCoreRowModel(),
  getPaginationRowModel: getPaginationRowModel(),
  autoResetPageIndex: false, //turn off auto reset of pageIndex
});

const table = useReactTable({
  columns,
  data,
  getCoreRowModel: getCoreRowModel(),
  getPaginationRowModel: getPaginationRowModel(),
  autoResetPageIndex: false, //turn off auto reset of pageIndex
});

Beachten Sie jedoch, dass Sie, wenn Sie autoResetPageIndex deaktivieren, möglicherweise einige Logik hinzufügen müssen, um den pageIndex selbst zurückzusetzen, um leere Seiten zu vermeiden.

Es gibt mehrere Pagination Table Instance APIs, die nützlich sind, um Ihre Pagination UI-Komponenten anzubinden.

• getCanPreviousPage: Nützlich zum Deaktivieren der Schaltfläche "vorherige Seite", wenn Sie sich auf der ersten Seite befinden.
• getCanNextPage: Nützlich zum Deaktivieren der Schaltfläche "nächste Seite", wenn keine weiteren Seiten vorhanden sind.
• previousPage: Nützlich zum Wechseln zur vorherigen Seite. (Schaltflächen-Klick-Handler)
• nextPage: Nützlich zum Wechseln zur nächsten Seite. (Schaltflächen-Klick-Handler)
• firstPage: Nützlich zum Wechseln zur ersten Seite. (Schaltflächen-Klick-Handler)
• lastPage: Nützlich zum Wechseln zur letzten Seite. (Schaltflächen-Klick-Handler)
• setPageIndex: Nützlich für ein "Seite wechseln"-Eingabefeld.
• resetPageIndex: Nützlich zum Zurücksetzen des Tabellen-States auf den ursprünglichen Seitenindex.
• setPageSize: Nützlich für ein Eingabefeld/Dropdown für die Seitengröße.
• resetPageSize: Nützlich zum Zurücksetzen des Tabellen-States auf die ursprüngliche Seitengröße.
• setPagination: Nützlich zum gleichzeitigen Setzen des gesamten Pagination States.
• resetPagination: Nützlich zum Zurücksetzen des Tabellen-States auf den ursprünglichen Pagination State.

Hinweis: Einige dieser APIs sind neu in v8.13.0.

<Button
  onClick={() => table.firstPage()}
  disabled={!table.getCanPreviousPage()}
>
  {'<<'}
</Button>
<Button
  onClick={() => table.previousPage()}
  disabled={!table.getCanPreviousPage()}
>
  {'<'}
</Button>
<Button
  onClick={() => table.nextPage()}
  disabled={!table.getCanNextPage()}
>
  {'>'}
</Button>
<Button
  onClick={() => table.lastPage()}
  disabled={!table.getCanNextPage()}
>
  {'>>'}
</Button>
<select
  value={table.getState().pagination.pageSize}
  onChange={e => {
    table.setPageSize(Number(e.target.value))
  }}
>
  {[10, 20, 30, 40, 50].map(pageSize => (
    <option key={pageSize} value={pageSize}>
      {pageSize}
    </option>
  ))}
</select>

<Button
  onClick={() => table.firstPage()}
  disabled={!table.getCanPreviousPage()}
>
  {'<<'}
</Button>
<Button
  onClick={() => table.previousPage()}
  disabled={!table.getCanPreviousPage()}
>
  {'<'}
</Button>
<Button
  onClick={() => table.nextPage()}
  disabled={!table.getCanNextPage()}
>
  {'>'}
</Button>
<Button
  onClick={() => table.lastPage()}
  disabled={!table.getCanNextPage()}
>
  {'>>'}
</Button>
<select
  value={table.getState().pagination.pageSize}
  onChange={e => {
    table.setPageSize(Number(e.target.value))
  }}
>
  {[10, 20, 30, 40, 50].map(pageSize => (
    <option key={pageSize} value={pageSize}>
      {pageSize}
    </option>
  ))}
</select>

• getPageCount: Nützlich, um die Gesamtzahl der Seiten anzuzeigen.
• getRowCount: Nützlich, um die Gesamtzahl der Zeilen anzuzeigen.