DataTable

Instalación

DataTable es un módulo independiente — no lleva dependencias de gráficos y puede usarse por sí solo. Importa la clase y apunta a un elemento contenedor y a una matriz de datos.

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

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

Inicio rápido

Pasa tus filas como datos y describe cada columna. Sin columnas suministradas, la cuadrícula las deduce de la primera fila.

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 },
});

Columnas

Cada columna es un objeto. Use accessorKey, header, cell, enableSorting y propiedades relacionadas — o los nombres propios de KatuCharts field, title y formatter, que se aceptan como equivalentes.

Renderizado de celda y encabezado

Muestra lo que quieras en una celda o encabezado. La función cell de una columna renderiza su contenido — devuelve texto, una cadena HTML o un nodo DOM — y una función header construye markup de encabezado personalizado, como un botón ordenable.

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 recibe valores de row, column y table que puedes usar para leer datos e impulsar la cuadrícula:

Ordenamiento

El ordenamiento está activado por defecto; haz clic en un encabezado para ciclar ascendente → descendente → sin ordenar. Desactívalo globalmente, habilita ordenamiento de múltiples columnas o establece un ordenamiento 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 }] },
});

Filtrado

La cuadrícula ofrece un cuadro de búsqueda global más una fila de filtro por columna. Ambos se pueden activar o desactivar independientemente, y cada columna selecciona (o deduce) uno de varios tipos de filtro.

Desactiva toda la fila de filtro con filtering.enabled = false, u oculta el filtro de una única columna con filterable: false (enableColumnFilter: false). Un botón Restablecer filtros aparece automáticamente mientras cualquier filtro esté activo.

Habilita el cuadro de búsqueda global en la barra de herramientas; coincide en todas las columnas visibles (o un subconjunto elegido).

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
  ],
});

Paginación

La paginación está activada por defecto. Configura el tamaño de página, los tamaños ofrecidos y qué controles se renderizan.

Selección de filas

Habilita selección de una o varias filas, con casillas opcionales y un seleccionar todo en el encabezado.

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

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

Gestión de columnas

Más allá del renderizado, las columnas se pueden ocultar, fijar, cambiar de tamaño y reordenar. El cambio de tamaño está activado por defecto; los otros son opcionales.

• Un menú Columnas de la barra de herramientas activa o desactiva cada columna (respeta enableHiding). Oculta el botón con columnVisibility.enabled = false.
• Fija columnas a la izquierda o derecha con pinned en la columna, o columnPinning.enabled = true más el método pinColumn().
• Arrastra el borde derecho de un encabezado para redimensionar. Desactiva con columnResizing.enabled = false.
• Habilita arrastrar para reordenar con columnReordering.enabled = true.

Temas y CSS

Toda la capa visual está impulsada por propiedades personalizadas de CSS --kdt-* en una sola clase, por lo que puedes cambiar el tema estableciendo una variable — sin !important necesario. Cada parte también lleva un nombre de clase estable que puedes dirigir directamente.

Establece cualquiera de estos en .katucharts-datatable (o un envoltorio) para cambiar el tema. La cuadrícula incluye predeterminados de luz sensatos y una paleta oscura incorporada.

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

Temas y CSS · classNames

Prefiere adjuntar sus propias clases. Pase un objeto classNames para enganchar cualquier parte — root, toolbar, table, header, row, cell, footer y 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 la altura de fila y el relleno. Un elemento 'Density' de la barra de herramientas permite a los usuarios cambiarlo en vivo.

Cambia toda la cuadrícula a oscuro con style.theme = 'dark' (o establece data-theme="dark" en la raíz).

Eventos

Suscríbete a través de la opción events (o el método .on(name, handler)) para reaccionar a la interacción del usuario.

Localización

Las cadenas de interfaz integradas —placeholders de búsqueda y filtro, paginación, menús de exportación y densidad, controles de columna— vienen en varios idiomas. Puedes elegir un idioma explícitamente, dejar que la tabla siga al navegador o anular cadenas individuales.

De forma predeterminada, la tabla detecta el idioma del navegador y recurre al inglés cuando no hay coincidencia. Define locale para fijar un idioma; una vez establecido, no cambia por sí solo.

// 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 incluidos de fábrica:

Anular cadenas individuales

Pasa lang para anular cualquier cadena del locale activo. Las anulaciones por clave siempre prevalecen sobre el paquete de locale, así que puedes fijar un locale y aun así personalizar alguna etiqueta.

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

Cambia de idioma en tiempo de ejecución con setLocale: la tabla se vuelve a renderizar y conserva las anulaciones de lang.

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

Agrega tu propio idioma con registerLocale antes de crear la tabla; las cadenas omitidas recurren al inglés.

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

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

Referencia de opciones

Opciones de nivel superior pasadas a new DataTable(container, options). Los bloques de características son objetos para que puedas habilitar y configurar cada uno en un lugar.

API programática

La instancia expone métodos para impulsar la cuadrícula desde tu propio código.