DataGrid: Selection

Zeilen auswählen, einzeln oder mehrfach: Maus- und Tastaturbedienung, stabile Zeilenschlüssel und die JavaScript-Schnittstelle für den aufrufenden Code.

Das DataGrid kennt zwei Arten von Auswahl: eine aktive Zeile, der eine Vorschau folgt, und mehrere angehakte Zeilen, die ein Massenbefehl trifft. Beide sind mit Maus und Tastatur bedienbar, die Mehrfachauswahl auch ohne JavaScript.

Zurück: Demo-Übersicht

Status: [Live]. Referenzen: Fluent UI DetailsList (SelectionMode.multiple), Azure-DevOps-Backlog-Bulk-Edit (Auswahl-Toolbar), DevExpress-Grid-Checkbox-Selection, VS-Code-Listen (Ctrl/Shift-Modell).

Vertieft den selection/rowKey-Teil des dataGrid()-Basiskontrakts: Einzel- und Mehrfachauswahl von Zeilen, Maus-/Tastaturbedienung, JS-API für Konsumenten.

• dataGrid()-Grundkontrakt bereits verstanden.
• Bei multi: jede Zeile braucht einen Spalten-Wert, der sie eindeutig identifiziert (für rowKey).

Aktive Zeile und Auswahl sind zwei Dinge. Die aktive Zeile ist die, um die es gerade geht – sie treibt eine Vorschau in der Detailspalte. Die Auswahl sind die angehakten Zeilen – sie tragen den Massenbefehl. Im Modus multi bestehen beide nebeneinander: drei Zeilen angehakt, eine vierte in der Detailspalte offen. Fluent UI DetailsList trennt dieselben zwei Begriffe.

Die aktive Zeile trägt aria-current=„true“, eine ausgewählte aria-selected=„true“. Pfeiltasten bewegen die aktive Zeile, Leertaste/Klick ändert die Auswahl.

Auswahlzustand ist ansichts-lokal: Filter-, Sortier- oder Seitenwechsel verwirft die Auswahl (bewusst – keine unsichtbar mitlaufende Auswahl über Ansichten hinweg).

echo $widgets->dataGrid($columns, $rows, [
    'selection' => 'single',
]);

Falsch: rowKey auf eine Spalte zeigen lassen, deren Wert nicht eindeutig ist (z. B. status). Mehrere Zeilen posten dann denselben selection[]-Wert – der Server kann sie serverseitig nicht unterscheiden.

echo $widgets->dataGrid($columns, $rows, [
    'selection' => 'multi',
    'rowKey'    => 'id',
]);

Klick/Pfeiltasten markieren die aktive Zeile (aria-selected, --wk-admin-row-selected-bg); Strg+C kopiert sie (data-wk-copy der Zeile gewinnt, sonst der Tab-verbundene Zelltext – s. Data Export).

• Checkbox-Spalte: erste Spalte mit echten <input type="checkbox" name="selection[]" value="<rowKey>">-Zellen plus Kopf-Checkbox („alle sichtbaren Zeilen an-/abwählen“, indeterminate bei Teilauswahl). Die Checkboxen liegen in einem umschließenden <form> – die Auswahl funktioniert dadurch vollständig ohne JavaScript (Formular-POST von selection[]).
• Aktive Zeile: Klick oder Pfeiltaste setzt sie, ohne etwas anzuhaken. Sie trägt aria-current=„true“ und eine Markierung am Zeilenanfang; eine Detailspalte folgt ihr (s. active in der Selection-API). Die Haken bleiben davon unberührt.
• Maus: Klick auf die Checkbox togglet; Strg+Klick auf die Zeile togglet ebenfalls; Shift+Klick wählt den Bereich von der zuletzt aktiven bis zur geklickten Zeile.
• Tastatur: Pfeiltasten bewegen die aktive Zeile, Leertaste togglet sie, Shift+Pfeil erweitert den Bereich, Strg+A wählt alle sichtbaren Zeilen, Strg+C kopiert alle gewählten Zeilen (zeilenweise, je Zeile gewinnt deren data-wk-copy-Attribut – s. Data Export). Der Container trägt aria-multiselectable=„true“, Zeilen aria-selected.

• wkDataGrid.getSelection(gridEl) → Array der rowKey-Werte der aktuell gewählten Zeilen.
• Bei jeder Änderung feuert das Grid ein bubbelndes CustomEvent wk-selectionchange mit detail = { keys: string[], count: number, active: string|null }.
• keys/count nennen die angehakten Zeilen, active die aktive. Wer eine Vorschau führt, liest active; wer einen Massenbefehl führt, liest keys. In single ist beides dieselbe Zeile.

document.querySelector('.wk-datagrid').addEventListener('wk-selectionchange', (ev) => {
    console.log(ev.detail.count, 'Zeilen ausgewählt:', ev.detail.keys);
    console.log('Vorschau zeigt:', ev.detail.active);
});

echo $widgets->dataGrid($columns, $rows, [
    'selection' => 'multi',
    'rowKey'    => 'id',
]);

Vorschau und Massenbefehl nebeneinander, mit den Feldnamen einer bestehenden Gegenstelle:

echo $widgets->dataGrid($columns, $rows, [
    'selection'     => 'multi',
    'rowKey'        => 'id',
    'selectionName' => 'sel',
    'selectionForm' => 'wkq-bf',
]);

• Die Auswahl gilt je Ansicht: Filter-, Sortier- oder Seitenwechsel verwirft sie (bewusst, s. Abschnitt 3).
• Kein „Auswahl über mehrere Seiten hinweg merken“ – jede neue Ansicht startet mit leerer Auswahl.
• Die aktive Zeile überlebt einen Seitenwechsel ebenfalls nicht. Ein Bildschirm, der sie behalten muss, trägt sie in der Adresse mit und setzt sie beim Zeichnen (data-wk-current="1" an der Zeile).

• Vollständiger Überblick: Accessibility (konsolidiert, nicht hier dupliziert).
• Ohne JavaScript bleibt multi vollständig nutzbar (Formular-POST); single erfordert für die Klick-Markierung JavaScript, native Tab-Navigation bleibt aber immer erhalten.
• Ohne JavaScript gibt es keine aktive Zeile. Ein Bildschirm, der eine Vorschau anbietet, hält dafür einen Verweis je Zeile bereit – er setzt den Schlüssel in die Adresse, und der Server zeichnet die Vorschau.

Symptom: Checkbox-Spalte fehlt trotz selection => 'multi'.

Ursache: rowKey fehlt in $opts – das Widget degradiert still auf none.

Lösung: $opts['rowKey'] auf einen eindeutigen Spalten-Key setzen.

Symptom: Die Detailspalte bleibt beim zweiten Haken stehen.

Ursache: Der Zuhörer liest keys und verlangt genau einen Eintrag.

Lösung: active lesen. Es nennt die Zeile, um die es geht – unabhängig davon, wie viele angehakt sind.

• Demo-Übersicht – alle Kategorien
• DataGrid: Data Editing (Massenaktionen) – Auswahl-Toolbar, Bulk-Operationen auf der Selection
• FluentUI: Vertical Grid (Property Grid) – Demo-Übersicht – Eigenschaften-Inspector, der auf wk-selectionchange reagieren kann
• DataGrid: Accessibility – ARIA-/Tastatur-Gesamtüberblick