DataTable

DataTable affiche des lignes et des colonnes comme un tableur et défile dans les deux sens, quel que soit leur nombre. Seules les cellules visibles sont créées : un tableau d’un million de lignes et de dix mille colonnes défile aussi aisément qu’un petit. Les lignes, les colonnes ou les cellules se sélectionnent au pointeur et au clavier ; les colonnes ont des largeurs fixes, se redimensionnent en faisant glisser leur bord, se déplacent en faisant glisser leur titre, restent à gauche pendant que les autres défilent, et se trient. Les titres peuvent être placés sous des libellés de groupe, et une cellule ou un titre peut être dessiné par l’app.

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 fournit la mise en page, l’alignement, la virtualisation et l’interaction. L’app donne à ses parties leur espacement interne, leurs couleurs, leurs bordures et le retour visuel de la sélection via classes et styles. En Rust, on en crée un avec nsh_base::data_table() ; en TSX, avec <DataTable> depuis 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);

Le tableau remplit la boîte que l’app lui donne (flex-1, une hauteur) et défile à l’intérieur : verticalement à travers les lignes et horizontalement à travers les colonnes, avec des barres de défilement (scrollbar={false} les masque, bounces={false} supprime l’effet de rebond aux extrémités sur les plateformes qui en ont un).

#Lignes et colonnes

data désigne les lignes : des objets dont les champs sont nommés par les key des colonnes, ou des tableaux que les colonnes indexent par position. Les nombres, booléens et chaînes s’affichent comme du texte. En Rust, les lignes sont fournies champ par champ, chacun d’un seul type : DataTableRows::new(2).texts("symbol", ["AAPL", "MSFT"]).numbers("change", [1.2, -0.4]). Une colonne est un DataTableColumn :

rowHeight est la hauteur d’une ligne du corps (par défaut 32) et headerHeight la hauteur d’une ligne de titres (par défaut la hauteur des lignes). rowHeader ajoute à gauche une colonne de numéros de ligne, qui sélectionne les lignes. stripe donne aux lignes impaires la partie rowOdd.

#Libellés de groupe

groups place des libellés au-dessus des colonnes, en commençant par le niveau le plus bas. Chaque niveau est une liste de { label, span } dont les étendues totalisent le nombre de colonnes, ou celui du niveau inférieur.

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

#Un nombre quelconque de lignes

Le tableau demande les lignes par position, et l’app les fournit. rowCount est le nombre total de lignes, data les lignes que l’app détient, et dataStart la position de la première d’entre elles. Les lignes hors de data restent vides jusqu’à ce que l’app les fournisse. onVisibleRowsChange signale les lignes visibles, { range: { start, end } }, à chaque pas de défilement, et c’est l’endroit où récupérer la page qui les entoure.

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

Pour une liste qui s’allonge par la fin, définissez hasMore : onLoadMore se déclenche une fois pour chaque nombre de lignes lorsque les lignes visibles arrivent à moins de loadMoreThreshold (par défaut 20) de la dernière. Tant que loading est vrai, il attend, et le slot loadingView s’affiche par-dessus les lignes. Le slot empty s’affiche lorsqu’il n’y a aucune ligne.

Au-delà de quelques millions de points de contenu, les barres de défilement couvrent une plage mise à l’échelle, de sorte qu’un million de lignes permet encore d’atteindre chaque ligne.

#Sélection

Trois commutateurs déterminent ce qu’un appui sélectionne, comme dans gpui-component :

Avec cellSelectable et l’en-tête de ligne masqué (rowHeader={false}), appuyer de nouveau sur la cellule sélectionnée sélectionne sa ligne. Un appui avec Maj ou la touche de commande de la plateforme enfoncée ne sélectionne une ligne que si selectOnModifierPress (par défaut true) ; une app qui gère sa propre sélection multiligne traite donc elle-même ces appuis : onRowPress signale chaque appui sur le corps avec sa ligne, la colonne sous le pointeur, les clics dans une ligne et les touches de modification enfoncées. Une colonne dont selectable vaut false ne se sélectionne pas elle-même et ne sélectionne pas ses cellules.

Les lignes sont numérotées à partir de 0 dans les données, et une colonne est identifiée par son index dans columns, quel que soit l’ordre dans lequel l’utilisateur les a déplacées. onSelectionChange signale ce que l’utilisateur a sélectionné (null si rien). La prop selection définit la sélection depuis l’app ; si elle n’est pas définie, le tableau la conserve. onDoublePress signale une ligne, une cellule ou un titre sur lesquels on a appuyé deux fois, et onContextMenu un appui secondaire ou long, avec le point où ouvrir le Menu de l’app. Les deux désignent la cellule sous le pointeur (son row et son column), le numéro d’une ligne (row seulement) ou un titre (column seulement). Jusqu’au prochain appui, la cellule pour laquelle un menu a été demandé a la partie cellActive, ou sa ligne la partie rowActive lorsque les cellules ne se sélectionnent pas.

Les lecteurs d’écran obtiennent une grille (nommée par accessibilityLabel) d’en-têtes de colonnes et de cellules, les éléments sélectionnés étant annoncés comme sélectionnés.

#Clavier

Appuyer sur le tableau, ou l’atteindre avec Tab (macOS, le web), lui donne le clavier jusqu’à un autre appui, un changement de focus ou blur() ; focus() le lui donne depuis l’app. Le tableau constitue un seul arrêt de Tab : à l’intérieur, Tab déplace la sélection, et Échap rend le clavier.

loopSelection (par défaut true) fait que les flèches bouclent aux extrémités.

#Tri

Une colonne sortable a un bouton de tri à la fin de son titre, un petit bouton fantôme atténué tant que la colonne n’est pas triée. Appuyer dessus signale le tri suivant ({ key, direction }) dans le cycle : non trié, croissant, décroissant, puis de nouveau non trié, avec onSortChange({ sort }) (null pour effacer). Le tableau ne réordonne pas les lignes : l’app trie ses données, ou demande à son serveur les lignes dans le nouvel ordre, et définit sort pour que le titre l’indique. Comme l’app maîtrise l’ordre, le tri fonctionne de la même façon sur un million de lignes que l’app ne détient jamais.

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

#Redimensionner et déplacer les colonnes

Un glissement du bord de fin d’une colonne la redimensionne dans les limites de minWidth et maxWidth, et onColumnResize({ key, width }) signale chaque pas. Appuyer deux fois de suite sur le bord ajuste la colonne à son texte et son titre les plus larges. Un glissement d’un titre déplace la colonne, et une ligne indique où elle sera déposée ; onColumnMove signale { key, from, to, order }, order étant les key de toutes les colonnes dans l’ordre affiché. Les colonnes fixes restent parmi les colonnes fixes. resizableColumns et movableColumns désactivent les deux pour le tableau, et les resizable et movable d’une colonne l’emportent sur eux.

#Données en direct

Un tableau de cotations change plusieurs fois par seconde. L’app formate les lignes visibles et une marge autour (elle les connaît grâce à onVisibleRowsChange) et les transmet sous forme de data depuis dataStart ; une mise à jour ne coûte donc que ce qui est à l’écran, quel que soit le nombre de lignes. Les hausses et les baisses tirent leurs couleurs des positiveClass et negativeClass de la colonne, appliquées nativement aux cellules dont la valeur est supérieure ou inférieure à zéro (ou dont le texte commence par + ou -).

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

Les lignes et les colonnes sont des slots que le tableau crée une fois et conserve : le défilement leur attribue d’autres lignes et colonnes à afficher, de sorte qu’un défilement, aussi long soit-il, ne change que des textes et des positions.

#Dessiner les cellules et les titres

renderCell dessine les cellules propres à l’app lorsqu’une colonne n’est pas que du texte (un badge, un bouton). Il n’est appelé que pour les cellules visibles, avec un DataTableCell : row, column, key, text (ce que le tableau afficherait) et selected. L’app retrouve ses propres données par row. renderHeaderCell dessine un titre sur toute sa cellule, avec un DataTableHeaderCell : column, key, title, sort (la direction, ou aucune) et 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 et fontSize (par défaut 14) définissent la police des cellules, dans laquelle le tableau mesure aussi les textes pour ajuster les colonnes.

#La ref

ref fournit un DataTableRef. Une méthode à laquelle on donne une ligne, une colonne ou une clé de colonne que le tableau ne possède pas ne change rien et journalise un avertissement nommant la méthode et la valeur ; fitColumn est rejetée avec un TypeError pour une clé inconnue.

#Styliser les parties

class et style stylisent la boîte du tableau. classes accepte des classes Tailwind par partie et styles des styles en ligne par partie ; les parties fournissent la structure et l’alignement du tableau ; leurs classes fournissent l’apparence, et les styles l’emportent sur les classes.

<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

#Événements

#Voir aussi

• Editor et DiffView : les autres composants de base riches en données.
• Menu : le menu à ouvrir depuis onContextMenu.
• nsh/base : les autres composants de base.