DataTable

Instalação

O DataTable é um módulo independente — não traz dependências de gráficos e pode ser usado sozinho. Importe a classe e aponte-a para um elemento container e um array de dados.

import { DataTable } from 'katucharts.js/datatable';

const table = new DataTable('#grid', { data: rows });

Início rápido

Passe suas linhas como data e descreva cada coluna. Sem colunas fornecidas, a grade as infere da primeira linha.

const rows = [
  { id: 'm5gr84i9', amount: 316, status: 'success',    email: '[email protected]' },
  { id: '3u1reuv4', amount: 242, status: 'success',    email: '[email protected]' },
  { id: 'derv1ws0', amount: 837, status: 'processing', email: '[email protected]' },
];

new DataTable('#grid', {
  data: rows,
  columns: [
    { accessorKey: 'status', header: 'Status' },
    { accessorKey: 'email',  header: 'Email' },
    { accessorKey: 'amount', header: 'Amount', type: 'number' },
  ],
  pagination: { pageSize: 10 },
  filtering: { enabled: true },
});

Colunas

Cada coluna é um objeto. Use accessorKey, header, cell, enableSorting e propriedades relacionadas — ou os nomes próprios do KatuCharts field, title e formatter, que são aceitos como equivalentes.

Renderização de célula e cabeçalho

Exiba o que quiser em uma célula ou cabeçalho. A função cell de uma coluna renderiza seu conteúdo — retorne texto, uma string HTML ou um nó DOM — e uma função header constrói marcação de cabeçalho customizada, como um botão ordenável.

const usd = (n) => new Intl.NumberFormat('en-US',
  { style: 'currency', currency: 'USD' }).format(n);

columns: [
  // function header with a sort button
  {
    accessorKey: 'email',
    header: ({ column }) => {
      const b = document.createElement('button');
      b.textContent = 'Email';
      b.onclick = () => column.toggleSorting();
      return b;
    },
  },
  // cell returning markup
  {
    accessorKey: 'amount',
    header: () => '<div style="text-align:right">Amount</div>',
    cell: ({ row }) =>
      `<div style="text-align:right">${usd(row.getValue('amount'))}</div>`,
  },
  // an action / checkbox column has no accessorKey — give it an id
  { id: 'actions', cell: ({ row }) => renderMenu(row.original) },
]

Cada callback recebe valores de row, column e table que você pode usar para ler dados e controlar a grade:

Ordenação

A ordenação está ativada por padrão; clique em um cabeçalho para ciclar ascendente → descendente → não ordenado. Desative-a globalmente, ative ordenação multi-coluna, ou defina uma ordenação inicial.

new DataTable('#grid', {
  data: rows,
  sorting: {
    enabled: true,
    multiSort: true,
    defaultSort: [{ column: 'amount', direction: 'desc' }],
  },
});

// or set an initial state
new DataTable('#grid', {
  data: rows,
  initialState: { sorting: [{ id: 'amount', desc: true }] },
});

Filtragem

A grade oferece uma caixa de busca global mais uma linha de filtro por coluna. Ambas podem ser ativadas ou desativadas independentemente, e cada coluna escolhe (ou infere) um de vários tipos de filtro.

Desative toda a linha de filtro com filtering.enabled = false, ou oculte o filtro de uma única coluna com filterable: false (enableColumnFilter: false). Um botão Limpar filtros aparece automaticamente enquanto qualquer filtro estiver ativo.

Ative a caixa de busca global na barra de ferramentas; ela corresponde a todas as colunas visíveis (ou um subconjunto escolhido).

new DataTable('#grid', {
  data: rows,
  search: { enabled: true, placeholder: 'Search…' },
  filtering: { enabled: true },          // per-column filter row
  columns: [
    { accessorKey: 'email', header: 'Email' },                        // text filter
    { accessorKey: 'status', header: 'Status', filterType: 'faceted' },
    { accessorKey: 'amount', header: 'Amount', type: 'number',
      filterType: 'numberrange' },
    { accessorKey: 'id', header: 'ID', filterable: false },           // no filter
  ],
});

Paginação

A paginação está ativada por padrão. Configure o tamanho da página, os tamanhos oferecidos e quais controles renderizam.

Seleção de linhas

Ative seleção de linha única ou multi, com checkboxes opcionais e um select-all no cabeçalho.

const table = new DataTable('#grid', {
  data: rows,
  selection: { mode: 'multi', checkbox: true },
});

table.on('selection:change', ({ selected }) => {
  // do something with the selected rows
});

Gerenciamento de colunas

Além de renderizar, colunas podem ser ocultadas, fixadas, redimensionadas e reordenadas. Redimensionamento está ativado por padrão; os outros são opt-in.

• Um menu da barra de ferramentas Colunas alterna cada coluna on ou off (respeita enableHiding). Oculte o botão com columnVisibility.enabled = false.
• Fixe colunas à esquerda ou à direita com pinned na coluna, ou columnPinning.enabled = true mais o método pinColumn().
• Arraste a borda direita de um cabeçalho para redimensionar. Desative com columnResizing.enabled = false.
• Ative arrastar para reordenar com columnReordering.enabled = true.

Tematização e CSS

Toda a camada visual é orientada por propriedades customizadas CSS --kdt-* em uma única classe, então você pode re-tematizar definindo uma variável — nenhum !important necessário. Cada parte também traz um nome de classe estável que você pode direcionar diretamente.

Defina qualquer uma destas em .katucharts-datatable (ou um wrapper) para re-tematizar. A grade traz padrões claros sensatos e uma paleta escura embutida.

/* Re-theme by setting variables on a wrapper — no !important */
.my-grid .katucharts-datatable {
  --kdt-primary: #b43417;
  --kdt-radius: ;
  --kdt-accent: #fbeae5;
}

Tematização e CSS · classNames

Prefere anexar suas próprias classes? Passe um objeto classNames para conectar qualquer parte — root, toolbar, table, header, row, cell, footer e pagination.

new DataTable('#grid', {
  data: rows,
  classNames: { root: 'my-grid', row: 'my-row', cell: 'my-cell' },
  style: { theme: 'dark', density: 'compact', radius: 12 },
});

density: 'compact' | 'normal' | 'comfortable' ajusta altura de linha e padding. Um item 'Density' na barra de ferramentas deixa usuários alternar ao vivo.

Inverta toda a grade para escuro com style.theme = 'dark' (ou defina data-theme="dark" na raiz).

Eventos

Subscreva através da opção events (ou o método .on(name, handler)) para reagir à interação do usuário.

Localização

As strings de interface integradas — placeholders de busca e filtro, paginação, menus de exportação e densidade, controles de coluna — vêm em vários idiomas. Você pode escolher um idioma explicitamente, deixar a tabela seguir o navegador ou sobrescrever strings individuais.

Por padrão, a tabela detecta o idioma do navegador e usa o inglês quando não há correspondência. Defina locale para fixar um idioma; uma vez definido, ele não muda sozinho.

// Auto-detect from the browser language (default)
new DataTable('#grid', { data: rows });

// Pin a locale — stays fixed regardless of the browser
new DataTable('#grid', { data: rows, locale: 'pt-BR' });

Locales incluídos por padrão:

Sobrescrevendo strings individuais

Passe lang para sobrescrever qualquer string do locale ativo. Sobrescritas por chave sempre vencem o pacote de locale, então você pode fixar um locale e ainda personalizar um rótulo ou outro.

new DataTable('#grid', {
  data: rows,
  locale: 'pt-BR',
  lang: { search: 'Procurar produtos…' },   // wins over the locale pack
});

Troque de idioma em tempo de execução com setLocale — a tabela é redesenhada e mantém as sobrescritas de lang.

const table = new DataTable('#grid', { data: rows });
table.setLocale('es');   // switch language and redraw

Adicione seu próprio idioma com registerLocale antes de criar a tabela; strings omitidas recaem no inglês.

import { DataTable, registerLocale } from 'katucharts.js/datatable';

registerLocale('fr', { search: 'Rechercher…', noData: 'Aucune donnée' });
new DataTable('#grid', { data: rows, locale: 'fr' });

Referência de opções

Opções de nível superior passadas para new DataTable(container, options). Blocos de recursos são objetos para que você possa ativar e configurar cada um no mesmo lugar.

API programática

A instância expõe métodos para controlar a grade a partir do seu próprio código.