Définir les colonnes et afficher les lignes

Chaque colonne de TanStack Table est décrite par un objet ColumnDef. Les deux champs les plus importants sont accessorKey (le nom de la propriété dans votre objet de données) et l’en-tête (la chaîne qui étiquette la colonne ou la fonction de rendu).

L’approche accessorKey convient parfaitement aux données plates ; les valeurs complexes ou calculées nécessitent accessorFn.

Lorsque vos données possèdent une propriété directe comme « nom » ou « adresse e-mail », utilisez accessorKey. Lorsque vous devez calculer une valeur, par exemple en combinant firstName et lastName, utilisez accessorFn.

Les deux sont entièrement typés lorsque vous fournissez le type générique des lignes à ColumnDef.

Le champ de cellule d’un ColumnDef accepte une fonction qui reçoit le contexte de la cellule et renvoie du JSX. C’est ainsi que vous affichez des badges, des boutons, des images ou toute autre interface personnalisée dans une cellule.

Pour les valeurs textuelles simples, cell.renderValue() suffit. Pour tout contenu plus riche, déstructurez les informations de cell.getContext().

Définissez vos colonnes en dehors du composant pour éviter de les recréer à chaque rendu. Transmettez le tableau à useReactTable avec vos données et getCoreRowModel.

TypeScript déduira les types de colonnes lorsque vous annotez ColumnDef avec votre type de données, ce qui vous donnera la complétion automatique pour les valeurs d’accessorKey.

getCoreRowModel est une fonction de fabrique importée depuis @tanstack/react-table. Transmettez sa valeur de retour à useReactTable pour indiquer à l’instance comment construire la liste de base des lignes à partir de votre tableau de données.

D’autres modèles de lignes (triées, filtrées ou paginées) se superposent ensuite en transmettant des fabriques de modèles supplémentaires.

Appelez table.getHeaderGroups() et parcourez le résultat pour afficher votre thead. Chaque groupe d’en-têtes possède un tableau d’en-têtes ; chaque en-tête possède une définition de colonne et un identifiant.

Utilisez flexRender(header.column.columnDef.header, header.getContext()) pour afficher le contenu de l’en-tête, qu’il s’agisse d’une chaîne ou d’une fonction renvoyant du JSX.

Appelez table.getRowModel() et parcourez les lignes pour afficher un élément tr pour chacune d’elles. À l’intérieur, appelez row.getVisibleCells() et parcourez les cellules pour afficher un élément td par cellule.

Utilisez flexRender(cell.column.columnDef.cell, cell.getContext()) pour afficher le contenu des cellules, en respectant tout rendu personnalisé défini dans la colonne.

flexRender est une fonction utilitaire qui accepte un composant React, une fonction renvoyant du JSX ou une valeur simple, puis les affiche de manière cohérente. Elle permet aux définitions de colonnes d’utiliser aussi bien de simples chaînes que des fonctions de rendu complètes pour les en-têtes et les cellules.

Cette interface unifiée signifie que vous n’avez pas besoin de vérifier le type de la définition avant de l’afficher.

cell.renderValue() renvoie la valeur brute de l’accesseur, mise en forme sous forme de chaîne. Pour un contrôle accru, cell.getContext() fournit l’intégralité du contexte de rendu, notamment la ligne, la colonne, l’instance de tableau et la valeur brute.

Les rendus personnalisés de cellules utilisent ce contexte pour accéder aux autres données de la ligne au-delà de la seule valeur de l’accesseur.

Chaque ColumnDef accepte un champ de métadonnées dans lequel vous pouvez associer des informations arbitraires comme isSticky: true ou un alignement à droite. Accédez-y dans votre rendu via column.columnDef et ses métadonnées.

Pour épingler des colonnes à gauche ou à droite, TanStack Table fournit l’état d’épinglage des colonnes et des méthodes utilitaires sur l’objet colonne.

Définissez un tableau de ColumnDef avec accessorKey, l’en-tête et éventuellement une cellule personnalisée. Appelez useReactTable avec les données, les colonnes et getCoreRowModel. Parcourez getHeaderGroups pour le thead et getRowModel() pour le tbody, en utilisant flexRender pour afficher chaque en-tête et chaque cellule.

Cette configuration minimale vous fournit un tableau entièrement fonctionnel et dont la mise en forme est entièrement personnalisée.

Quand devez-vous utiliser accessorFn plutôt qu’accessorKey dans une définition de colonne TanStack Table ?

Définissez les colonnes avec ColumnDef, en utilisant accessorKey pour les champs directs ou accessorFn pour les valeurs calculées. Transmettez les colonnes et getCoreRowModel à useReactTable, puis affichez les en-têtes avec getHeaderGroups et les lignes du corps avec getRowModel().

L’utilitaire flexRender gère uniformément les définitions d’en-têtes et de cellules fondées sur des chaînes ou sur des fonctions.