DataTable

DataTable muestra filas y columnas como una hoja de cálculo y se desplaza en ambas direcciones sobre cualquier número de ellas. Solo se crean las celdas visibles, así que una tabla de un millón de filas y diez mil columnas se desplaza igual que una pequeña. Se pueden seleccionar filas, columnas o celdas, con el puntero y con el teclado. Las columnas tienen anchos fijos, se redimensionan arrastrando su borde, se mueven arrastrando su título, permanecen a la izquierda mientras las demás se desplazan y se ordenan. Los títulos pueden ir bajo etiquetas de grupo, y la app puede dibujar una celda o un título.

import { mount, signal, Text, View } from "nsh";
import { DataTable, type DataTableColumn, type DataTableSort } from "nsh/base";
import { dataTableClasses, dataTableFitPadding, Log, Segmented, Split, ui, wide } from "./palette";

const NAMES = ["Ada", "Alan", "Grace", "Linus", "Margaret", "Dennis", "Barbara", "Ken"];
const CITIES = ["Oslo", "Lima", "Kyoto", "Cairo", "Perth", "Quito", "Turin", "Hanoi"];

type Person = { id: number; name: string; city: string; score: number };

const people: Person[] = Array.from({ length: 2000 }, (_, i) => ({
  id: i + 1,
  name: `${NAMES[i % NAMES.length]} ${i + 1}`,
  city: CITIES[(i * 7) % CITIES.length],
  score: (i * 37) % 1000,
}));

const columns: DataTableColumn[] = [
  { key: "id", title: "ID", width: 70, align: "end", fixed: true, sortable: true },
  { key: "name", title: "Name", width: 150, sortable: true },
  { key: "city", title: "City", width: 120, sortable: true },
  { key: "score", title: "Score", width: 90, align: "end", sortable: true },
];

// Sorting is the app's: the table reports the next sort (`onSortChange`),
// the app orders its rows and sets `sort`.
function App() {
  const mode = signal<"row" | "cell">("row");
  const sort = signal<DataTableSort | undefined>(undefined);
  const rows = signal<Person[]>(people);
  const events = signal<string[]>([]);
  const log = (line: string) => events.set([line, ...events()].slice(0, 4));

  const sortBy = (next: DataTableSort | undefined) => {
    sort.set(next);
    if (!next) return rows.set(people);
    const key = next.key as keyof Person;
    const sign = next.direction === "descending" ? -1 : 1;
    rows.set([...people].sort((a, b) => (a[key] < b[key] ? -sign : a[key] > b[key] ? sign : 0)));
  };

  return (
    <View style={{ flex: 1, backgroundColor: ui().page, padding: 20, paddingTop: 24, gap: 14 }}>
      <Text style={{ fontSize: 22, fontWeight: "700", color: ui().text }}>data table</Text>
      <Text style={{ color: ui().muted }}>Press a title to sort, drag its edge to resize or the title to move it</Text>

      <Split
        grow
        width={680}
        inspector={
          <>
            <Segmented label="selection" options={["row", "cell"] as const} value={mode()} onChange={(v) => mode.set(v)} />
            <Log title="events" lines={events()} minHeight={96} />
          </>
        }
      >
        <View style={{ height: wide() ? 360 : 320 }}>
          <DataTable
            columns={columns.map((column) => ({ ...column, fitPadding: dataTableFitPadding }))}
            classes={dataTableClasses}
            data={rows()}
            rowHeader={false}
            stripe
            cellSelectable={mode() === "cell"}
            sort={sort()}
            onSortChange={({ sort: next }) => {
              sortBy(next ?? undefined);
              log(`onSortChange: ${next ? `${next.key} ${next.direction}` : "none"}`);
            }}
            onSelectionChange={({ selection }) => log(`onSelectionChange: ${selection ? JSON.stringify(selection) : "none"}`)}
            onColumnResize={({ key, width }) => log(`onColumnResize: ${key} ${Math.round(width)}`)}
            style={{ flex: 1 }}
          />
        </View>
      </Split>
    </View>
  );
}

mount(App);

DataTable aporta el diseño, la alineación, la virtualización y la interacción. La app da a sus partes el relleno, los colores, los bordes y la respuesta visual de la selección mediante classes y styles. Rust crea una con nsh_base::data_table(), y TSX con <DataTable> desde nsh/base.

use nsh_base::{DataTableColumn, data_table};
use nsh_core::prelude::*;

fn column(key: &str, title: &str) -> DataTableColumn {
    let mut column = DataTableColumn::default();
    column.key = key.into();
    column.title = Some(title.into());
    column
}

fn table() -> impl IntoElement {
    data_table()
        .columns(vec![column("name", "Name"), column("city", "City")])
        .flex_1()
}

import { mount } from "nsh";
import { DataTable, type DataTableColumn } from "nsh/base";

const columns: DataTableColumn[] = [
  { key: "name", title: "Name", width: 160, sortable: true },
  { key: "city", title: "City", width: 120 },
  { key: "score", title: "Score", width: 90, align: "end" },
];

const rows = [
  { name: "Ada", city: "Oslo", score: 91 },
  { name: "Grace", city: "Lima", score: 87 },
  { name: "Linus", city: "Kyoto", score: 78 },
];

function App() {
  return <DataTable columns={columns} data={rows} class="flex-1" />;
}

mount(App);

La tabla ocupa el espacio que la app le da (flex-1, una altura) y se desplaza dentro de él: en vertical por las filas y en horizontal por las columnas, con barras de desplazamiento (scrollbar={false} las oculta, bounces={false} elimina el rebote en los extremos en las plataformas que lo tienen).

#Filas y columnas

data son las filas: objetos cuyos campos nombran los key de las columnas, o arrays que las columnas indexan por posición. Los números, los booleanos y las cadenas se muestran como texto. Rust entrega las filas campo a campo, cada uno de un solo tipo: DataTableRows::new(2).texts("symbol", ["AAPL", "MSFT"]).numbers("change", [1.2, -0.4]). Una columna es un DataTableColumn:

rowHeight es la altura de una fila del cuerpo (por defecto, 32) y headerHeight la altura de una fila de títulos (por defecto, la altura de fila). rowHeader añade a la izquierda una columna de números de fila, que selecciona filas. stripe aplica a las filas impares la parte rowOdd.

#Etiquetas de grupo

groups coloca etiquetas encima de las columnas, empezando por el nivel más bajo. Cada nivel es una lista de { label, span } cuyos tramos suman el número de columnas, o el del nivel inferior.

<DataTable
  columns={columns}
  data={rows}
  groups={[
    [{ label: "Person", span: 2 }, { label: "Result", span: 1 }],
  ]}
  class="flex-1"
/>

#Cualquier número de filas

La tabla pide las filas por posición y la app las sirve. rowCount es el número total de filas, data las filas que la app tiene y dataStart la posición de la primera de ellas. Las filas fuera de data están vacías hasta que la app las proporciona. onVisibleRowsChange informa de las filas visibles, { range: { start, end } }, en cada paso de desplazamiento, y es el lugar donde obtener la página que las rodea.

const ROWS = 1_000_000;
const page = signal({ start: 0, rows: load(0) });

<DataTable
  columns={columns}
  data={page().rows}
  dataStart={page().start}
  rowCount={ROWS}
  onVisibleRowsChange={({ range: { start, end } }) => {
    // Keep the rows in view inside the page held.
    const held = page();
    if (start < held.start || end > held.start + held.rows.length) {
      const first = Math.max(0, start - 200);
      page.set({ start: first, rows: load(first) });
    }
  }}
  class="flex-1"
/>

Para una lista que crece por el final, establezca hasMore: onLoadMore se dispara una vez por cada número de filas cuando las filas visibles llegan a estar a loadMoreThreshold (por defecto, 20) de la última. Mientras loading sea true, espera, y el slot loadingView se muestra sobre las filas. El slot empty se muestra cuando no hay filas.

A partir de unos pocos millones de puntos de contenido, las barras de desplazamiento abarcan un rango escalado, de modo que un millón de filas sigue permitiendo desplazarse hasta cada fila.

#Selección

Tres interruptores deciden qué selecciona una pulsación, como en gpui-component:

Con cellSelectable y la cabecera de fila oculta (rowHeader={false}), volver a pulsar la celda seleccionada selecciona su fila. Una pulsación con Shift o con la tecla de comando de la plataforma pulsada solo selecciona una fila mientras selectOnModifierPress (por defecto, true), de modo que una app que mantiene su propia selección de varias filas gestiona esas pulsaciones por sí misma: onRowPress informa de cada pulsación en el cuerpo con su fila, la columna bajo el puntero, los clics en una fila y las teclas modificadoras pulsadas. Una columna cuyo selectable es false no se selecciona ni selecciona sus celdas.

Las filas se cuentan desde 0 en los datos, y una columna es su índice dentro de columns, sea cual sea el orden al que el usuario la haya movido. onSelectionChange informa de lo que el usuario seleccionó (null si no hay nada). La prop selection establece la selección desde la app; si no se define, la tabla la mantiene. onDoublePress informa de una fila, una celda o un título pulsados dos veces, y onContextMenu de una pulsación secundaria o larga con el punto en el que abrir el Menu de la app. Ambos nombran la celda bajo el puntero (su row y su column), el número de una fila (solo row) o un título (solo column). Hasta la siguiente pulsación, la celda para la que se pidió un menú tiene la parte cellActive, o su fila la parte rowActive cuando las celdas no se seleccionan.

Los lectores de pantalla reciben una cuadrícula (con el nombre de accessibilityLabel) de cabeceras de columna y celdas, y se anuncian como seleccionadas las que lo estén.

#Teclado

Pulsar la tabla, o llegar a ella con Tab (macOS, la web), le da el teclado hasta otra pulsación, hasta que el foco pase a otro sitio o hasta blur(); focus() se lo da desde la app. La tabla es una sola parada de Tab: dentro de ella, Tab mueve la selección y Escape devuelve el teclado.

loopSelection (por defecto, true) hace que las teclas de flecha den la vuelta en los extremos.

#Ordenación

Una columna sortable tiene un botón de ordenación al final de su título, un pequeño botón ghost atenuado mientras la columna no está ordenada. Al pulsarlo informa de la siguiente ordenación ({ key, direction }) en el ciclo de sin ordenar, ascendente, descendente y de nuevo sin ordenar, con onSortChange({ sort }) (null para quitarla). La tabla no reordena las filas: la app ordena sus datos, o pide a su servidor las filas en el nuevo orden, y establece sort para que el título lo muestre. Como el orden es de la app, la ordenación funciona igual sobre un millón de filas que la app nunca tiene.

<DataTable
  columns={columns}
  data={rows()}
  sort={sort()}
  onSortChange={({ sort: next }) => {
    sort.set(next ?? undefined);
    rows.set(sorted(people, next));
  }}
  class="flex-1"
/>

#Redimensionar y mover columnas

Arrastrar el borde final de una columna la redimensiona dentro de sus minWidth y maxWidth, y onColumnResize({ key, width }) informa de cada paso. Pulsar el borde dos veces seguidas ajusta la columna a su texto y título más anchos. Arrastrar un título mueve la columna, y una línea indica dónde se soltará; onColumnMove informa de { key, from, to, order }, siendo order los key de todas las columnas en el orden mostrado. Las columnas fijas permanecen entre las fijas. resizableColumns y movableColumns desactivan ambas cosas para toda la tabla, y los resizable y movable de una columna prevalecen sobre ellos.

#Datos en vivo

Una tabla de cotizaciones cambia muchas veces por segundo. La app da formato a las filas visibles y a un margen a su alrededor (las conoce por onVisibleRowsChange) y las entrega como data desde dataStart, de modo que una actualización cuesta lo que hay en pantalla, sea cual sea el número de filas. Las subidas y las bajadas toman sus colores de los positiveClass y negativeClass de la columna, aplicados de forma nativa a las celdas cuyo valor está por encima o por debajo de cero (o cuyo texto empieza por + o -).

const tone = { positiveClass: "text-green-600", negativeClass: "text-red-600" };
const columns: DataTableColumn[] = [
  { key: "symbol", title: "Symbol", fixed: true },
  { key: "price", title: "Price", align: "end", sortable: true },
  { key: "change", title: "Chg%", align: "end", ...tone },
];

Las filas y las columnas son slots que la tabla crea una vez y conserva: al desplazarse se les asignan otras filas y columnas que mostrar, de modo que un desplazamiento, por largo que sea, solo cambia textos y posiciones.

#Dibujar celdas y títulos

renderCell dibuja las celdas propias de la app cuando una columna no es solo texto (una insignia, un botón). Se llama solo para las celdas visibles, con un DataTableCell: row, column, key, text (lo que mostraría la tabla) y selected. La app busca sus propios datos por row. renderHeaderCell dibuja un título en toda su celda, recibiendo un DataTableHeaderCell: column, key, title, sort (la dirección, o ninguna) y selected.

<DataTable
  columns={columns}
  data={rows()}
  renderCell={(cell) =>
    cell.key === "status" ? (
      <View class={cell.text === "open" ? "rounded bg-green-500/20 px-2" : "rounded bg-muted px-2"}>
        <Text class="text-xs">{cell.text}</Text>
      </View>
    ) : (
      <Text class="px-2 text-sm">{cell.text}</Text>
    )
  }
  class="flex-1"
/>

fontFamily y fontSize (por defecto, 14) establecen la fuente de las celdas, en la que la tabla también mide los textos para ajustar las columnas.

#La ref

ref da un DataTableRef. Un método al que se le pasa una fila, una columna o una clave de columna que la tabla no tiene no cambia nada y registra una advertencia con el nombre del método y el valor; fitColumn se rechaza con un TypeError ante una clave desconocida.

#Estilo de las partes

class y style dan estilo al contenedor de la tabla. classes admite clases de Tailwind por parte y styles estilos en línea por parte; las partes aportan la estructura y la alineación de la tabla, sus clases aportan la apariencia, y styles prevalecen sobre las clases.

<DataTable
  columns={columns}
  data={rows()}
  stripe
  class="flex-1 rounded-lg border border-border"
  classes={{
    header: "bg-secondary",
    headerCell: "pl-2 pr-1",
    headerContent: "gap-1",
    cell: "px-2",
    resizeHandle: "bg-border group-hover:bg-primary",
    sortAscending: "text-muted-foreground opacity-60 selected:text-foreground selected:opacity-100",
    sortDescending: "text-muted-foreground opacity-60 selected:text-foreground selected:opacity-100",
    rowSelected: "bg-primary/10",
    rowHover: "bg-muted/50",
    fixedEdge: "bg-border",
  }}
/>

#Props

#Eventos

#Relacionado

• Editor y DiffView: los otros componentes base con muchos datos.
• Menu: el menú que se abre desde onContextMenu.
• nsh/base: los demás componentes base.