Definindo colunas e renderizando linhas

Cada coluna do TanStack Table é descrita por um objeto ColumnDef. Os dois campos mais importantes são accessorKey (o nome da propriedade no seu objeto de dados) e header (o texto do rótulo da coluna ou uma função de renderização).

A abordagem com accessorKey é ideal para dados planos; valores complexos ou calculados precisam de accessorFn.

Quando seus dados têm uma propriedade direta como name ou email, use accessorKey: 'name'. Quando precisar calcular um valor (por exemplo, combinando firstName e lastName), use accessorFn: row => row.firstName + ' ' + row.lastName.

Ambos são totalmente tipados quando você fornece o tipo genérico dos dados da linha a ColumnDef.

O campo cell em um ColumnDef aceita uma função que recebe o contexto da célula e retorna JSX. É assim que você renderiza distintivos, botões, imagens ou qualquer interface personalizada dentro de uma célula.

Para valores de texto simples, cell.renderValue() é suficiente. Para qualquer conteúdo mais elaborado, extraia as informações de cell.getContext().

Defina suas colunas fora do componente para evitar recriá-las a cada renderização. Passe a matriz para useReactTable junto com seus dados e getCoreRowModel.

TypeScript inferirá os tipos das colunas quando você anotar ColumnDef com seu tipo de dados, oferecendo preenchimento automático para os valores de accessorKey.

getCoreRowModel é uma função de fábrica importada de @tanstack/react-table. Você passa o valor retornado por ela para useReactTable, informando à instância como criar a lista básica de linhas a partir da sua matriz de dados.

Modelos de linhas adicionais (ordenados, filtrados e paginados) são sobrepostos a esse modelo passando outras funções de fábrica.

Chame table.getHeaderGroups() e percorra o resultado para renderizar o cabeçalho da tabela. Cada grupo de cabeçalho tem uma lista de cabeçalhos; cada cabeçalho tem uma definição de coluna e um identificador.

Use flexRender(header.column.columnDef.header, header.getContext()) para renderizar o conteúdo do cabeçalho, seja ele uma cadeia de texto ou uma função que retorna JSX.

Chame table.getRowModel().rows e percorra cada linha para renderizar um elemento de linha. Dentro dele, chame row.getVisibleCells() e transforme cada célula em um elemento de célula.

Use flexRender(cell.column.columnDef.cell, cell.getContext()) para renderizar o conteúdo da célula, respeitando qualquer função personalizada de renderização definida na coluna.

flexRender é um auxiliar que aceita um componente React, uma função que retorna JSX ou um valor simples e os renderiza de maneira consistente. Ele permite que as definições de coluna usem tanto cadeias de texto simples quanto funções completas de renderização para cabeçalhos e células.

Essa interface unificada significa que você não precisa verificar o tipo da definição antes de renderizá-la.

cell.renderValue() retorna o valor bruto fornecido pelo acessador, formatado como texto. Para ter mais controle, cell.getContext() fornece o contexto completo de renderização, incluindo a linha, a coluna, a instância da tabela e o valor bruto.

Funções personalizadas de renderização de células usam o contexto para acessar dados relacionados da linha além do valor fornecido por um único acessador.

Cada ColumnDef aceita um campo meta, no qual você pode anexar metadados arbitrários, como isSticky: true ou alignment: 'right'. Acesse esses dados no seu renderizador por meio de column.columnDef.meta.

Para fixar colunas à esquerda ou à direita, TanStack Table fornece o estado de fixação de colunas e métodos auxiliares no objeto da coluna.

Defina uma matriz ColumnDef com accessorKey, header e cell opcional. Chame useReactTable com data, columns e getCoreRowModel. Percorra getHeaderGroups para o cabeçalho da tabela e getRowModel().rows para o corpo, usando flexRender para renderizar cada cabeçalho e célula.

Essa configuração mínima oferece uma tabela totalmente funcional e com estilização totalmente personalizada.

Quando você deve usar accessorFn em vez de accessorKey na definição de uma coluna do TanStack Table?

Defina as colunas usando ColumnDef com accessorKey para campos diretos ou accessorFn para valores calculados. Passe columns e getCoreRowModel para useReactTable e renderize com getHeaderGroups para os cabeçalhos e getRowModel().rows para as linhas do corpo.

O utilitário flexRender trata de maneira uniforme as definições de cabeçalho e célula baseadas tanto em cadeias de texto quanto em funções.