Leitfaden zum Filtern von Spalten

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

• filters (enthält Faceting)
• editable-data
• expanding
• Gruppierung
• pagination
• row-selection

Spaltenfilter-API

Filterung gibt es in 2 Varianten: Spaltenfilterung und globale Filterung.

Dieser Leitfaden konzentriert sich auf die Spaltenfilterung, bei der ein Filter auf den Zugangsdatenwert einer einzelnen Spalte angewendet wird.

TanStack Table unterstützt sowohl clientseitige als auch manuelle serverseitige Filterung. Dieser Leitfaden beschreibt, wie Sie beides implementieren und anpassen können, und hilft Ihnen bei der Entscheidung, welches für Ihren Anwendungsfall am besten geeignet ist.

Wenn Sie einen großen Datensatz haben, möchten Sie möglicherweise nicht alle diese Daten in den Browser des Clients laden, um sie zu filtern. In diesem Fall möchten Sie höchstwahrscheinlich serverseitige Filterung, Sortierung, Paginierung usw. implementieren.

Wie jedoch auch im Leitfaden zur Paginierung erläutert, unterschätzen viele Entwickler, wie viele Zeilen clientseitig ohne Leistungseinbußen geladen werden können. Die Beispiele für TanStack Table werden oft getestet, um bis zu 100.000 Zeilen oder mehr mit guter Leistung für clientseitige Filterung, Sortierung, Paginierung und Gruppierung zu verarbeiten. Dies bedeutet nicht unbedingt, dass Ihre App so viele Zeilen verarbeiten kann, aber wenn Ihre Tabelle nur wenige tausend Zeilen haben wird, können Sie möglicherweise die von TanStack Table bereitgestellten clientseitigen Filter-, Sortier-, Paginierungs- und Gruppierungsfunktionen nutzen.

TanStack Table kann Tausende von clientseitigen Zeilen mit guter Leistung verarbeiten. Schließen Sie clientseitige Filterung, Paginierung, Sortierung usw. nicht ohne vorherige Überlegung aus.

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 jederzeit mit clientseitiger Filterung und Paginierung beginnen und in Zukunft zu serverseitigen Strategien wechseln, wenn Ihre Daten wachsen.

Wenn Sie entschieden haben, dass Sie serverseitige Filterung anstelle der integrierten clientseitigen Filterung implementieren müssen, erfahren Sie hier, wie Sie das tun.

Keine getFilteredRowModel Tabellenoption ist für die manuelle serverseitige Filterung erforderlich. Stattdessen sollten die data, die Sie an die Tabelle übergeben, bereits gefiltert sein. Wenn Sie jedoch eine getFilteredRowModel Tabellenoption übergeben haben, können Sie die Tabelle anweisen, diese zu überspringen, indem Sie die Option manualFiltering auf true setzen.

const table = useReactTable({
  data,
  columns,
  getCoreRowModel: getCoreRowModel(),
  // getFilteredRowModel: getFilteredRowModel(), // not needed for manual server-side filtering
  manualFiltering: true,
})

const table = useReactTable({
  data,
  columns,
  getCoreRowModel: getCoreRowModel(),
  // getFilteredRowModel: getFilteredRowModel(), // not needed for manual server-side filtering
  manualFiltering: true,
})

Hinweis: Bei manueller Filterung haben viele der Optionen, die im Rest dieses Leitfadens besprochen werden, keine Auswirkungen. Wenn manualFiltering auf true gesetzt ist, wendet die Tabelleninstanz keine Filterlogik auf die übergebenen Zeilen an. Stattdessen wird davon ausgegangen, dass die Zeilen bereits gefiltert sind und die data, die Sie ihr übergeben, unverändert verwendet wird.

Wenn Sie die integrierten clientseitigen Filterfunktionen verwenden, müssen Sie zuerst eine getFilteredRowModel Funktion an die Tabellenoptionen übergeben. Diese Funktion wird jedes Mal aufgerufen, wenn die Tabelle die Daten filtern muss. Sie können entweder die Standardfunktion getFilteredRowModel von TanStack Table importieren oder Ihre eigene erstellen.

import { useReactTable, getFilteredRowModel } from '@tanstack/react-table'
//...
const table = useReactTable({
  data,
  columns,
  getCoreRowModel: getCoreRowModel(),
  getFilteredRowModel: getFilteredRowModel(), // needed for client-side filtering
})

import { useReactTable, getFilteredRowModel } from '@tanstack/react-table'
//...
const table = useReactTable({
  data,
  columns,
  getCoreRowModel: getCoreRowModel(),
  getFilteredRowModel: getFilteredRowModel(), // needed for client-side filtering
})

Unabhängig davon, ob Sie clientseitige oder serverseitige Filterung verwenden, können Sie die integrierte Verwaltung des Spaltenfilterstatus von TanStack Table nutzen. Es gibt viele Tabellen- und Spalten-APIs, um den Filterstatus zu ändern und damit zu interagieren sowie den Spaltenfilterstatus abzurufen.

Der Spaltenfilterstatus wird als Array von Objekten mit der folgenden Struktur definiert

interface ColumnFilter {
  id: string
  value: unknown
}
type ColumnFiltersState = ColumnFilter[]

interface ColumnFilter {
  id: string
  value: unknown
}
type ColumnFiltersState = ColumnFilter[]

Da der Spaltenfilterstatus ein Array von Objekten ist, können Sie mehrere Spaltenfilter gleichzeitig anwenden.

Sie können auf den Spaltenfilterstatus von der Tabelleninstanz aus zugreifen, genau wie auf jeden anderen Tabellenstatus, indem Sie die table.getState() API verwenden.

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

console.log(table.getState().columnFilters) // access the column filters state from the table instance

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

console.log(table.getState().columnFilters) // access the column filters state from the table instance

Wenn Sie jedoch vor der Initialisierung der Tabelle auf den Spaltenfilterstatus zugreifen müssen, können Sie den Spaltenfilterstatus wie unten gezeigt "steuern".

Wenn Sie einfachen Zugriff auf den Spaltenfilterstatus benötigen, können Sie den Spaltenfilterstatus mit den Tabellenoptionen state.columnFilters und onColumnFiltersChange steuern/verwalten.

const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]) // can set initial column filter state here
//...
const table = useReactTable({
  columns,
  data,
  //...
  state: {
    columnFilters,
  },
  onColumnFiltersChange: setColumnFilters,
})

const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]) // can set initial column filter state here
//...
const table = useReactTable({
  columns,
  data,
  //...
  state: {
    columnFilters,
  },
  onColumnFiltersChange: setColumnFilters,
})

Wenn Sie den Spaltenfilterstatus nicht in Ihrer eigenen Zustandsverwaltung oder Ihrem eigenen Gültigkeitsbereich steuern müssen, aber dennoch einen initialen Spaltenfilterstatus festlegen möchten, können Sie stattdessen die Option initialState Tabellenoption anstelle von state verwenden.

const table = useReactTable({
  columns,
  data,
  //...
  initialState: {
    columnFilters: [
      {
        id: 'name',
        value: 'John', // filter the name column by 'John' by default
      },
    ],
  },
})

const table = useReactTable({
  columns,
  data,
  //...
  initialState: {
    columnFilters: [
      {
        id: 'name',
        value: 'John', // filter the name column by 'John' by default
      },
    ],
  },
})

HINWEIS: Verwenden Sie nicht gleichzeitig initialState.columnFilters und state.columnFilters, da der initialisierte Status in state.columnFilters den initialState.columnFilters überschreibt.

Jede Spalte kann ihre eigene eindeutige Filterlogik haben. Wählen Sie aus beliebigen Filterfunktionen, die von TanStack Table bereitgestellt werden, oder erstellen Sie Ihre eigene.

Standardmäßig gibt es 10 integrierte Filterfunktionen zur Auswahl

• includesString - String-Inklusion ohne Berücksichtigung der Groß- und Kleinschreibung
• includesStringSensitive - String-Inklusion unter Berücksichtigung der Groß- und Kleinschreibung
• equalsString - String-Gleichheit ohne Berücksichtigung der Groß- und Kleinschreibung
• equalsStringSensitive - String-Gleichheit unter Berücksichtigung der Groß- und Kleinschreibung
• arrIncludes - Element-Inklusion in einem Array
• arrIncludesAll - Alle Elemente in einem Array enthalten
• arrIncludesSome - Einige Elemente in einem Array enthalten
• equals - Objekt-/referenzielle Gleichheit Object.is/===
• weakEquals - Schwache Objekt-/referenzielle Gleichheit ==
• inNumberRange - Nummernspanneneinschluss

Sie können auch Ihre eigenen benutzerdefinierten Filterfunktionen definieren, entweder als Spaltenoption filterFn oder als globale Filterfunktion mit der Tabellenoption filterFns.

Hinweis: Diese Filterfunktionen werden nur während der clientseitigen Filterung ausgeführt.

Bei der Definition einer benutzerdefinierten Filterfunktion entweder in der Spaltenoption filterFn oder in der Tabellenoption filterFns sollte diese die folgende Signatur haben

const myCustomFilterFn: FilterFn = (row: Row, columnId: string, filterValue: any, addMeta: (meta: any) => void) => boolean

const myCustomFilterFn: FilterFn = (row: Row, columnId: string, filterValue: any, addMeta: (meta: any) => void) => boolean

Jede Filterfunktion erhält

• Die zu filternde Zeile
• Die columnId, um den Wert der Zeile abzurufen
• Der Filterwert

und sollte true zurückgeben, wenn die Zeile in die gefilterten Zeilen aufgenommen werden soll, und false, wenn sie entfernt werden soll.

const columns = [
  {
    header: () => 'Name',
    accessorKey: 'name',
    filterFn: 'includesString', // use built-in filter function
  },
  {
    header: () => 'Age',
    accessorKey: 'age',
    filterFn: 'inNumberRange',
  },
  {
    header: () => 'Birthday',
    accessorKey: 'birthday',
    filterFn: 'myCustomFilterFn', // use custom global filter function
  },
  {
    header: () => 'Profile',
    accessorKey: 'profile',
    // use custom filter function directly
    filterFn: (row, columnId, filterValue) => {
      return // true or false based on your custom logic
    },
  }
]
//...
const table = useReactTable({
  columns,
  data,
  getCoreRowModel: getCoreRowModel(),
  getFilteredRowModel: getFilteredRowModel(),
  filterFns: { //add a custom sorting function
    myCustomFilterFn: (row, columnId, filterValue) => { //defined inline here
      return // true or false based on your custom logic
    },
    startsWith: startsWithFilterFn, // defined elsewhere
  },
})

const columns = [
  {
    header: () => 'Name',
    accessorKey: 'name',
    filterFn: 'includesString', // use built-in filter function
  },
  {
    header: () => 'Age',
    accessorKey: 'age',
    filterFn: 'inNumberRange',
  },
  {
    header: () => 'Birthday',
    accessorKey: 'birthday',
    filterFn: 'myCustomFilterFn', // use custom global filter function
  },
  {
    header: () => 'Profile',
    accessorKey: 'profile',
    // use custom filter function directly
    filterFn: (row, columnId, filterValue) => {
      return // true or false based on your custom logic
    },
  }
]
//...
const table = useReactTable({
  columns,
  data,
  getCoreRowModel: getCoreRowModel(),
  getFilteredRowModel: getFilteredRowModel(),
  filterFns: { //add a custom sorting function
    myCustomFilterFn: (row, columnId, filterValue) => { //defined inline here
      return // true or false based on your custom logic
    },
    startsWith: startsWithFilterFn, // defined elsewhere
  },
})

Sie können einige zusätzliche Eigenschaften an Filterfunktionen anhängen, um deren Verhalten anzupassen

• filterFn.resolveFilterValue - Diese optionale "hängende" Methode für jede gegebene filterFn ermöglicht es der Filterfunktion, den Filterwert zu transformieren/bereinigen/formatieren, bevor er an die Filterfunktion übergeben wird.

• filterFn.autoRemove - Diese optionale "hängende" Methode für jede gegebene filterFn erhält einen Filterwert und soll true zurückgeben, wenn der Filterwert aus dem Filterstatus entfernt werden soll. Z. B. möchten einige boolesche Filter möglicherweise den Filterwert aus dem Tabellenstatus entfernen, wenn der Filterwert auf false gesetzt ist.

const startsWithFilterFn = <TData extends MRT_RowData>(
  row: Row<TData>,
  columnId: string,
  filterValue: number | string, //resolveFilterValue will transform this to a string
) =>
  row
    .getValue<number | string>(columnId)
    .toString()
    .toLowerCase()
    .trim()
    .startsWith(filterValue); // toString, toLowerCase, and trim the filter value in `resolveFilterValue`

// remove the filter value from filter state if it is falsy (empty string in this case)
startsWithFilterFn.autoRemove = (val: any) => !val; 

// transform/sanitize/format the filter value before it is passed to the filter function
startsWithFilterFn.resolveFilterValue = (val: any) => val.toString().toLowerCase().trim(); 

const startsWithFilterFn = <TData extends MRT_RowData>(
  row: Row<TData>,
  columnId: string,
  filterValue: number | string, //resolveFilterValue will transform this to a string
) =>
  row
    .getValue<number | string>(columnId)
    .toString()
    .toLowerCase()
    .trim()
    .startsWith(filterValue); // toString, toLowerCase, and trim the filter value in `resolveFilterValue`

// remove the filter value from filter state if it is falsy (empty string in this case)
startsWithFilterFn.autoRemove = (val: any) => !val; 

// transform/sanitize/format the filter value before it is passed to the filter function
startsWithFilterFn.resolveFilterValue = (val: any) => val.toString().toLowerCase().trim(); 

Es gibt viele Tabellen- und Spaltenoptionen, die Sie verwenden können, um das Verhalten der Spaltenfilterung weiter anzupassen.

Standardmäßig ist die Spaltenfilterung für alle Spalten aktiviert. Sie können die Spaltenfilterung für alle Spalten oder für bestimmte Spalten deaktivieren, indem Sie die Tabellenoption enableColumnFilters oder die Spaltenoption enableColumnFilter verwenden. Sie können sowohl die Spalten- als auch die globale Filterung deaktivieren, indem Sie die Tabellenoption enableFilters auf false setzen.

Das Deaktivieren der Spaltenfilterung für eine Spalte bewirkt, dass die API column.getCanFilter für diese Spalte false zurückgibt.

const columns = [
  {
    header: () => 'Id',
    accessorKey: 'id',
    enableColumnFilter: false, // disable column filtering for this column
  },
  //...
]
//...
const table = useReactTable({
  columns,
  data,
  enableColumnFilters: false, // disable column filtering for all columns
})

const columns = [
  {
    header: () => 'Id',
    accessorKey: 'id',
    enableColumnFilter: false, // disable column filtering for this column
  },
  //...
]
//...
const table = useReactTable({
  columns,
  data,
  enableColumnFilters: false, // disable column filtering for all columns
})

Es gibt einige zusätzliche Tabellenoptionen, um das Verhalten der Spaltenfilterung bei Verwendung von Funktionen wie Erweitern, Gruppieren und Aggregation anzupassen.

Standardmäßig wird die Filterung von übergeordneten Zeilen nach unten durchgeführt. Wenn eine übergeordnete Zeile herausgefiltert wird, werden auch alle ihre untergeordneten Unterzeilen herausgefiltert. Je nach Anwendungsfall kann dies das gewünschte Verhalten sein, wenn Sie nur durch die obersten Zeilen und nicht durch die Unterzeilen suchen möchten. Dies ist auch die performanteste Option.

Wenn Sie jedoch zulassen möchten, dass Unterzeilen gefiltert und durchsucht werden, unabhängig davon, ob die übergeordnete Zeile herausgefiltert wird, können Sie die Tabellenoption filterFromLeafRows auf true setzen. Das Setzen dieser Option auf true bewirkt, dass die Filterung von Blattzeilen nach oben durchgeführt wird, was bedeutet, dass übergeordnete Zeilen enthalten sind, solange eine ihrer untergeordneten oder nachfolgenden Zeilen ebenfalls enthalten ist.

const table = useReactTable({
  columns,
  data,
  getCoreRowModel: getCoreRowModel(),
  getFilteredRowModel: getFilteredRowModel(),
  getExpandedRowModel: getExpandedRowModel(),
  filterFromLeafRows: true, // filter and search through sub-rows
})

const table = useReactTable({
  columns,
  data,
  getCoreRowModel: getCoreRowModel(),
  getFilteredRowModel: getFilteredRowModel(),
  getExpandedRowModel: getExpandedRowModel(),
  filterFromLeafRows: true, // filter and search through sub-rows
})

Standardmäßig wird für alle Zeilen in einem Baum gefiltert, unabhängig davon, ob es sich um übergeordnete Zeilen der obersten Ebene oder um untergeordnete Blattzeilen einer übergeordneten Zeile handelt. Wenn Sie die Tabellenoption maxLeafRowFilterDepth auf 0 setzen, wird die Filterung nur auf übergeordnete Zeilen der obersten Ebene angewendet, während alle Unterzeilen ungefiltert bleiben. Wenn Sie diese Option auf 1 setzen, wird die Filterung nur auf untergeordnete Blattzeilen in einer Tiefe von 1 angewendet, und so weiter.

Verwenden Sie maxLeafRowFilterDepth: 0, wenn Sie die Unterzeilen einer übergeordneten Zeile vor dem Herausfiltern schützen möchten, während die übergeordnete Zeile den Filter besteht.

const table = useReactTable({
  columns,
  data,
  getCoreRowModel: getCoreRowModel(),
  getFilteredRowModel: getFilteredRowModel(),
  getExpandedRowModel: getExpandedRowModel(),
  maxLeafRowFilterDepth: 0, // only filter root level parent rows out
})

const table = useReactTable({
  columns,
  data,
  getCoreRowModel: getCoreRowModel(),
  getFilteredRowModel: getFilteredRowModel(),
  getExpandedRowModel: getExpandedRowModel(),
  maxLeafRowFilterDepth: 0, // only filter root level parent rows out
})

Es gibt viele Spalten- und Tabellen-APIs, die Sie verwenden können, um mit dem Spaltenfilterstatus zu interagieren und Ihre UI-Komponenten anzubinden. Hier ist eine Liste der verfügbaren APIs und ihrer häufigsten Anwendungsfälle

• table.setColumnFilters - Überschreibt den gesamten Spaltenfilterstatus mit einem neuen Status

• table.resetColumnFilters - Nützlich für eine Schaltfläche "Alle löschen/Filter zurücksetzen"

• column.getFilterValue - Nützlich, um den Standardwert des initialen Filterwerts für ein Eingabefeld abzurufen oder sogar den Filterwert direkt einem Filterfeld zuzuweisen

• column.setFilterValue - Nützlich zum Verbinden von Filterfeldern mit ihren onChange- oder onBlur-Handlern

• column.getCanFilter - Nützlich zum Deaktivieren/Aktivieren von Filterfeldern

• column.getIsFiltered - Nützlich zur Anzeige einer visuellen Anzeige, dass eine Spalte gerade gefiltert wird

• column.getFilterIndex - Nützlich zur Anzeige der Reihenfolge, in der der aktuelle Filter angewendet wird

• column.getAutoFilterFn -

• column.getFilterFn - Nützlich zur Anzeige, welcher Filtermodus oder welche Funktion gerade verwendet wird