DataGrid: Data Paging and Scrolling

Zurück: Demo-Übersicht

Status: [Live] — natives Scrollen, serverseitiges Paging (paging-Opt) und darauf aufsetzendes Infinite Loading für Grids, die über die Viewport-Höhe hinausreichen; bewusst kein virtuelles Scrollen (Architekturentscheidung, Abschnitt 3). Referenz: DevExpress ASPxGridView „Paging and Scrolling„ / Virtual-Scroll-Modus.

Keine zusätzlichen — der dataGrid()-Basiskontrakt genügt; natives Scrollen ist ohne weitere Konfiguration aktiv.

Bewusste Grenze: kein virtuelles Scrollen in der ersten Ausbaustufe. Begründung: virtuelles Scrollen (nur die sichtbaren Zeilen im DOM halten, Rest per Scroll-Offset nachrendern) erfordert eine JS-Rendering-Engine mit eigenem Zustand — das widerspricht dem Grundsatz „kein Nachbau einer JS-Grid-Engine“ (layout → Layout-Mechanik). Für sehr große Ergebnismengen ist serverseitige Reduktion (Filter, Paging) der vorgesehene Weg, nicht Client-Virtualisierung.

// Ohne Paging-Feature liegt die Verantwortung für eine sinnvolle Zeilenzahl
// beim Aufrufer -- z.B. über eine SQL-LIMIT-Klausel vor dataGrid().
$rows = $db->queryAll('SELECT id, name, status FROM aufgaben ORDER BY id LIMIT 500');
echo $widgets->dataGrid($columns, $rows, [
    'empty' => 'Keine Aufgaben gefunden.',
]);

Falsch: ein Ergebnis mit mehreren Zehntausend Zeilen ungefiltert an dataGrid() übergeben. Ohne virtuelles Scrollen rendert das Widget jede Zeile als echtes <tr> — das DOM wird groß und die Seite spürbar langsam; das ist kein Bug des Widgets, sondern die dokumentierte Grenze dieser Ausbaustufe.

Der Grid-Body (.wk-datagrid__body) trägt overflow: auto — alle $rows werden vollständig ins DOM gerendert, der Browser übernimmt das Scrollen (Rezept-Zutat 3 in Adaptivity → CSS-Rezept). Das ist die einzige unterstützte Darstellungsart — es gibt keinen $opts-Schlüssel für Virtualisierung; Paging ist seit dem Vollausbau über $opts['paging'] verfügbar (nächster Abschnitt).

Für serverseitig paginierte Ergebnismengen (Virtualisierung bleibt ausgeschlossen, s. Abschnitt 3 — nur klassisches Seiten-Paging):

• 'paging' => ['page' => int, 'pageSize' => int, 'total' => int, 'pageUrl' => callable] rendert eine Paginierungsleiste unter dem Grid-Body (.wk-datagrid__paging): Erste/Zurück/„Seite X von Y (N Einträge)„/Weiter/Letzte als normale Links mit aria-label; inaktive Enden rendern als ausgegraute Spans.
• Analog zu sortUrl/filterAction: pageUrl(int $page): string liefert die URL je Seite — der No-JS-Weg ist das Feature; der Aufrufer paginiert $rows selbst (SQL LIMIT/OFFSET).
• pageSize ist optional; ohne Angabe gilt die projektweite Standardseitengröße helper_plugin_wkfluentui_widgets::PAGE_SIZE = 12 Zeilen. Jede Liste im Produkt beginnt bei derselben Seitengröße — wer hier eine andere Zahl setzt, weicht bewusst ab und sollte den Grund im Aufrufer nennen.
• pageUrl liefert eine ROHE URL (Trenner &, nicht &). Das Widget maskiert selbst, an jeder Stelle, an der es die URL einbettet. Wird die bereits maskierte Form übergeben, entsteht & im Markup; der Browser dekodiert das zu einem literalen &, und jeder Parameter nach dem ersten heißt dann amp;do, amp;page, … — die Seite 2 landet still in der Admin-Übersicht. Betroffen waren am 2026-07-30 vier Aufrufer gleichzeitig (wkidentity Benutzer, wkblog Beiträge/Kommentare, wksqliteds Browse), weil die url()-Hilfsmethoden dieser Module standardmäßig maskieren. Das Widget normalisiert seit dieser Runde zusätzlich (str_replace('&', '&', …)), weil wl() Parameterwerte prozentkodiert und ein literales & in einer erzeugten URL deshalb immer der Trenner ist, niemals Daten.

Regel (Nutzeranforderung 2026-07-29): überschreitet ein Grid die Viewport-Höhe, wechselt es automatisch in den Infinite-Loading-Modus. Umsetzung: paging veröffentlicht neben dem Pager zusätzlich die URL der Folgeseite und die eigenen Summen als Datenattribute auf .wk-datagrid__more; scripts/gridinfinite.js entscheidet zur Laufzeit, ob aktiviert wird — die entscheidende Tatsache (reicht dieses Grid über den sichtbaren Bereich hinaus?) existiert erst nach dem Layout.

Kein virtuelles Scrollen (Abschnitt 3 gilt unverändert): jede geladene Zeile bleibt eine echte Zeile im DOM. Auswahl, Strg+A, Sortierung, die Zählung im Massenaktions-Balken und der CSV-Export behalten damit ihre einfache Bedeutung „alles Geladene“; Zeilen werden nie recycelt oder entfernt. Ohne JavaScript ändert sich nichts — der Pager ist die Navigation.

Kombination mit Sorting/Filtering (verbindliche Aufrufer-Regel): bei serverseitigem Paging müssen sortUrl-Callables und filterHidden die aktuelle Seite in der erzeugten URL bzw. den Hidden-Feldern mitführen — sonst springt ein Sortier- oder Filterwechsel implizit auf Seite 1, ohne dass das für den Nutzer sichtbar ist.

$page = max(1, (int)($_GET['p'] ?? 1));
$rows = $db->queryAll('SELECT id, name FROM aufgaben ORDER BY id LIMIT 50 OFFSET ' . (($page - 1) * 50));
echo $widgets->dataGrid($columns, $rows, [
    'paging' => [
        'page'    => $page,
        'pageSize' => 50,
        'total'   => $gesamt,
        'pageUrl' => static fn (int $p) => wl($ID, ['p' => $p]),
    ],
]);

• Kein virtuelles Scrollen (bewusste, dauerhafte Grenze, s. Abschnitt 3) — Infinite Loading ist keine Virtualisierung, sondern Anfügen echter Zeilen.
• Infinite Loading hängt an paging. Ein Grid ohne paging rendert alle übergebenen Zeilen und scrollt nativ; es gibt dort nichts nachzuladen (so arbeitet z.B. das Ergebnis-Grid der SQL-Workbench, das seine Zeilen in einem Zug erhält).
• IntersectionObserver und fetch sind Voraussetzung; fehlt eines, bleibt der Pager sichtbar und alles funktioniert wie vorher.
• Die praktische Obergrenze für „noch flüssig“ hängt vom Browser/Gerät ab und ist hier bewusst nicht als feste Zahl behauptet (unbelegte Performance-Aussage).

• Natives Scrollen ist vollständig tastaturbedienbar (Bild-hoch/-runter, Pfeiltasten bei Fokus im Grid-Body) ohne zusätzlichen Code.
• Keine Browserkompatibilitäts-Anforderungen über CSS-overflow-Grundunterstützung hinaus.

Symptom: Grid wird bei großen Ergebnismengen spürbar langsam.

Ursache: alle Zeilen werden vollständig ins DOM gerendert — das ist die dokumentierte Grenze dieser Ausbaustufe, kein Bug.

Lösung: Ergebnismenge vor dem Aufruf reduzieren (SQL-LIMIT/ WHERE) oder serverseitiges Paging über $opts['paging'] aktivieren (Abschnitt 6).

• Demo-Übersicht — alle Kategorien
• DataGrid: Adaptivity — CSS-Rezept, das das Scroll-Verhalten trägt
• DataGrid: Filtering — serverseitige Datenreduktion (Filter)
• area:layout → Layout-Mechanik — Grundsatz „kein Nachbau einer JS-Grid-Engine„