DataTable

DataTable zeigt Zeilen und Spalten wie eine Tabellenkalkulation und scrollt in beide Richtungen über beliebig viele davon. Nur die sichtbaren Zellen werden erzeugt, sodass eine Tabelle mit einer Million Zeilen und zehntausend Spalten genauso scrollt wie eine kleine. Zeilen, Spalten oder Zellen lassen sich per Zeiger und Tastatur auswählen. Spalten haben feste Breiten, ändern ihre Größe durch Ziehen an ihrem Rand, lassen sich durch Ziehen an ihrem Titel verschieben, bleiben links stehen, während die anderen scrollen, und sind sortierbar. Titel können unter Gruppenbeschriftungen stehen, und eine Zelle oder ein Titel kann von der App gezeichnet werden.

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 liefert Layout, Ausrichtung, Virtualisierung und Interaktion. Die App gibt den einzelnen Parts ihr Padding, ihre Farben, Rahmen und das Auswahl-Feedback über classes und styles. In Rust wird eine Tabelle mit nsh_base::data_table() erzeugt, in TSX mit <DataTable> aus 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);

Die Tabelle füllt die Box, die die App ihr gibt (flex-1, eine Höhe), und scrollt darin: vertikal durch die Zeilen und seitwärts durch die Spalten, mit Scrollbalken (scrollbar={false} blendet sie aus, bounces={false} unterbindet das Nachfedern an den Enden, wo eine Plattform es kennt).

#Zeilen und Spalten

data sind die Zeilen: Objekte, deren Felder die keys der Spalten benennen, oder Arrays, die die Spalten über die Position indizieren. Zahlen, Booleans und Strings werden als Text angezeigt. Rust übergibt die Zeilen Feld für Feld, jedes mit einem einzigen Typ: DataTableRows::new(2).texts("symbol", ["AAPL", "MSFT"]).numbers("change", [1.2, -0.4]). Eine Spalte ist ein DataTableColumn:

rowHeight ist die Höhe einer Körperzeile (Standard 32) und headerHeight die Höhe einer Titelzeile (Standard ist die Zeilenhöhe). rowHeader fügt links eine Spalte mit Zeilennummern hinzu, die Zeilen auswählt. stripe gibt den ungeraden Zeilen den Part rowOdd.

#Gruppenbeschriftungen

groups setzt Beschriftungen über die Spalten, die unterste Ebene zuerst. Jede Ebene ist eine Liste von { label, span }, deren Spans sich zur Anzahl der Spalten oder zu der der darunterliegenden Ebene addieren.

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

#Beliebig viele Zeilen

Die Tabelle fragt Zeilen nach Position an, und die App liefert sie. rowCount ist die Gesamtzahl der Zeilen, data die Zeilen, die die App vorhält, und dataStart die Position der ersten davon. Zeilen außerhalb von data bleiben leer, bis die App sie liefert. onVisibleRowsChange meldet die sichtbaren Zeilen, { range: { start, end } }, bei jedem Scrollschritt und ist der richtige Ort, um die Seite um sie herum abzurufen.

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"
/>

Für eine Liste, die an ihrem Ende wächst, setzen Sie hasMore: onLoadMore wird für jede Zeilenanzahl einmal ausgelöst, wenn die sichtbaren Zeilen bis auf loadMoreThreshold (Standard 20) an die letzte herankommen. Solange loading true ist, wartet es, und der Slot loadingView wird über den Zeilen angezeigt. Der Slot empty wird angezeigt, wenn es keine Zeilen gibt.

Ab einigen Millionen Punkten Inhalt umfassen die Scrollbalken einen skalierten Bereich, sodass eine Million Zeilen weiterhin bis zu jeder Zeile scrollt.

#Auswahl

Drei Schalter bestimmen, was ein Druck auswählt, wie in gpui-component:

Mit cellSelectable und ausgeblendetem Zeilenkopf (rowHeader={false}) wählt ein erneuter Druck auf die ausgewählte Zelle ihre Zeile aus. Ein Druck mit gehaltener Umschalttaste oder der Befehlstaste der Plattform wählt nur dann eine Zeile aus, solange selectOnModifierPress (Standard true) gilt. Eine App, die ihre eigene Mehrfachauswahl von Zeilen verwaltet, behandelt diese Drücke daher selbst: onRowPress meldet jeden Druck auf den Körper mit seiner Zeile, der Spalte unter dem Zeiger, den Klicks in einer Zeile und den gehaltenen Modifikatortasten. Eine Spalte, deren selectable false ist, wählt weder sich selbst noch ihre Zellen aus.

Zeilen werden in den Daten ab 0 gezählt, und eine Spalte ist ihr Index in columns, unabhängig davon, in welche Reihenfolge der Benutzer sie verschoben hat. onSelectionChange meldet, was der Benutzer ausgewählt hat (null für nichts). Die Prop selection setzt die Auswahl von der App aus; lassen Sie sie ungesetzt, verwaltet die Tabelle die Auswahl selbst. onDoublePress meldet eine Zeile, eine Zelle oder einen Titel, die zweimal gedrückt wurden, und onContextMenu einen sekundären oder langen Druck mit dem Punkt, an dem das Menu der App geöffnet werden soll. Beide benennen die Zelle unter dem Zeiger (ihre row und column), die Nummer einer Zeile (nur row) oder einen Titel (nur column). Bis zum nächsten Druck hat die Zelle, für die ein Menü angefordert wurde, den Part cellActive, oder ihre Zeile den Part rowActive, wo Zellen nicht ausgewählt werden.

Screenreader erhalten ein Grid (benannt durch accessibilityLabel) aus Spaltenköpfen und Zellen, wobei die ausgewählten als ausgewählt angesagt werden.

#Tastatur

Wer die Tabelle drückt oder sie mit Tab erreicht (macOS, Web), gibt ihr die Tastatur, bis ein anderer Druck erfolgt, der Fokus woandershin wechselt oder blur(); focus() gibt sie ihr von der App aus. Die Tabelle ist ein einziger Tab-Stopp: In ihr bewegt Tab die Auswahl, und Escape gibt die Tastatur zurück.

loopSelection (Standard true) lässt die Pfeiltasten über die Enden hinweg umlaufen.

#Sortierung

Eine sortable-Spalte hat am Ende ihres Titels einen Sortierbutton, einen kleinen Ghost-Button, der abgedunkelt ist, solange die Spalte unsortiert ist. Ein Druck darauf meldet die nächste Sortierung ({ key, direction }) im Zyklus unsortiert, aufsteigend, absteigend und wieder unsortiert, mit onSortChange({ sort }) (null zum Löschen). Die Tabelle ordnet die Zeilen nicht um: Die App sortiert ihre Daten oder fordert von ihrem Server Zeilen in der neuen Reihenfolge an und setzt sort, damit der Titel sie anzeigt. Weil die App die Reihenfolge besitzt, funktioniert Sortieren bei einer Million Zeilen, die die App nie vorhält, genauso.

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

#Spalten in der Größe ändern und verschieben

Ein Ziehen am hinteren Rand einer Spalte ändert ihre Größe innerhalb von minWidth und maxWidth, und onColumnResize({ key, width }) meldet jeden Schritt. Zweimaliges Drücken des Rands in Folge passt die Spalte an ihren breitesten Text und Titel an. Ein Ziehen an einem Titel verschiebt die Spalte, und eine Linie zeigt, wo sie abgelegt wird; onColumnMove meldet { key, from, to, order }, wobei order die keys aller Spalten in der angezeigten Reihenfolge sind. Fixierte Spalten bleiben unter den fixierten. resizableColumns und movableColumns schalten beides für die Tabelle ab, und resizable und movable einer Spalte haben Vorrang davor.

#Live-Daten

Eine Kurstabelle ändert sich viele Male pro Sekunde. Die App formatiert die sichtbaren Zeilen und einen Puffer darum herum (sie kennt sie aus onVisibleRowsChange) und übergibt diese als data aus dataStart, sodass ein Update nur kostet, was auf dem Bildschirm ist, unabhängig von der Anzahl der Zeilen. Anstiege und Rückgänge beziehen ihre Farben aus positiveClass und negativeClass der Spalte, nativ angewendet auf die Zellen, deren Wert über oder unter null liegt (oder deren Text mit + oder - beginnt).

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

Zeilen und Spalten sind Slots, die die Tabelle einmal erzeugt und behält: Beim Scrollen bekommen sie andere Zeilen und Spalten zur Anzeige, sodass ein Scrollvorgang, wie lang er auch sei, nur Texte und Positionen ändert.

#Zellen und Titel zeichnen

renderCell zeichnet die eigenen Zellen der App, wo eine Spalte nicht nur Text enthält (ein Badge, ein Button). Es wird nur für die sichtbaren Zellen aufgerufen, mit einem DataTableCell: row, column, key, text (was die Tabelle anzeigen würde) und selected. Die App schlägt ihre eigenen Daten über row nach. renderHeaderCell zeichnet einen Titel über seine ganze Zelle und erhält ein DataTableHeaderCell: column, key, title, sort (die Richtung oder keine) und 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 und fontSize (Standard 14) legen die Schrift der Zellen fest, in der die Tabelle auch Texte ausmisst, um Spalten anzupassen.

#Das Ref

ref liefert ein DataTableRef. Eine Methode, der eine Zeile, eine Spalte oder ein Spaltenschlüssel übergeben wird, den die Tabelle nicht hat, ändert nichts und protokolliert eine Warnung mit dem Namen der Methode und dem Wert; fitColumn wird bei einem unbekannten Schlüssel mit einem TypeError abgelehnt.

#Die Parts gestalten

class und style gestalten die Box der Tabelle. classes nimmt Tailwind-Klassen pro Part und styles Inline-Styles pro Part; Parts liefern die Struktur und Ausrichtung der Tabelle, ihre Klassen liefern das Erscheinungsbild, und styles haben Vorrang vor Klassen.

<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

#Events

#Verwandte Themen

• Editor und DiffView: die anderen datenintensiven Basiskomponenten.
• Menu: das Menü, das von onContextMenu aus geöffnet wird.
• nsh/base: die anderen Basiskomponenten.