TableStateful

Diese Dokumentation wird aktuell überarbeitet und befindet sich im Beta-Status. Inhalte können sich noch ändern.

Diese Komponente wird erneut auf Barrierefreiheit getestet. Der vollständige Test steht noch aus und kann erst nach einem abgeschlossenen Release erfolgen.

Synonyme: Data Table, Datentabelle, Datenrepräsentation, Details-Liste

Beschreibung: Die TableStateful-Komponente dient der strukturierten und übersichtlichen Darstellung von Datenmengen. Sie bestimmt automatisch alle datenbezogenen Werte (wie Sortierung oder Pagination) und aktualisiert die Tabellenansicht entsprechend. Dies macht sie ideal für die Präsentation größerer Datenmengen, bei denen interaktive Funktionen wie Spaltensortierung oder Seitennummerierung erforderlich sind.

Beispiel

Darstellung einer einfachen Datentabelle mit automatischen Funktionalitäten:

<KolTableStateful _label="Pflanzenliste" _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Familie" }, { "key": "type", "label": "Typ" }, { "key": "origin", "label": "Herkunft" } ] ] }} _data={PLANT_DATA} _pagination={{"_page":1,"_pageSize":2,"_pageSizeOptions":[2,5,10]}} />

Barrierefreiheit

Die TableStateful-Komponente implementiert automatisch eine vollständige Accessibility-Struktur:

• Automatische ARIA-Attribute: Die Komponente verwaltet automatisch role, scope und aria-* Attribute für optimale Unterstützung durch Screenreader.
• Spaltenüberschriften: Überschriften erhalten automatisch die Rolle colheader oder rowheader, je nach Kontext.
• Scope-Management: Der Scope wird automatisch auf col, colgroup, row oder rowgroup gesetzt, um die Tabellenstruktur semantisch korrekt zu beschreiben.
• Focusable Region: Die Tabelle hat einen Tabindex, um als fokussierbare Region erkannt zu werden (scrollbare Bereiche sollten fokussierbar sein).
• Label-Pflicht: Das Attribut _label definiert die semantische oder sichtbare Beschriftung der Tabelle und wird an Screenreader übermittelt.

Links und Referenzen

Verwendung

Best Practices / Empfehlungen

• Angemessene Datenmenge: Verwenden Sie TableStateful für größere Datenmengen. Für sehr große Datenmengen (> 1000 Zeilen) erwägen Sie die Verwendung von mit Backend-Pagination.
• Spaltenanzahl: Limit Sie die Anzahl der Spalten auf das Wesentliche – zu viele Spalten beeinträchtigen die Lesbarkeit.
• Aussagekräftige Header: Verwenden Sie prägnante, verständliche Spaltenüberschriften.
• Sortierung: Aktivieren Sie Sortierung nur für Spalten mit Bedeutung (z.B. nicht für Aktions-Spalten).
• Multi-Sort nutzen: Die _allowMultiSort Option ermöglicht Sortierung nach mehreren Spalten gleichzeitig – sinnvoll bei komplexen Datensätzen.
• Pagination anpassen: Wählen Sie _pageSize und _pageSizeOptions basierend auf dem Nutzungskontext.
• Render-Funktionen: Verwenden Sie Render-Funktionen für komplexe Zelldarstellungen (z.B. Links, Icons, benutzerdefinierte Formatierungen).
• Responsivität: Bei kleinen Bildschirmen erwägen Sie alternative Darstellungsformen oder reduzieren Sie die sichtbaren Spalten.

Anwendungsfälle

• Darstellung von Produktkatalogen, Benutzer- oder Transaktionslisten
• Verwaltungsoberflächen mit Sortier- und Filter-Anforderungen
• Datenabfragen mit Pagination für übersichtliche Navigation
• Kombinierte Darstellung strukturierter Daten (vertikal und horizontal)
• Berichte mit Zusammenfassungszeilen (Footer)

FAQ

Wie verwende ich Backend-Pagination? Für sehr große Datenmengen verwenden Sie mit manueller Pagination. Sie können die Tabelle seitenweise befüllen und externe Sortierung implementieren.

Kann ich komplexe Inhalte in Zellen rendern? Ja, über Render-Funktionen in den Header-Definitionen können Sie beliebige Inhalte darstellen – Strings, DOM-Manipulationen oder sogar React-Komponenten.

Unterstützt die Komponente Zeilenauswahl? Das Attribut _selection ermöglicht die Auswahl von Zeilen (einfach oder mehrfach). Die Auswahl wird über das selectionChange Event übermittelt.

Konstruktion / Technik

Playground

Testen Sie alle Funktionalitäten der TableStateful-Komponente interaktiv:

<KolTableStateful _label="Pflanzenliste" _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Familie" }, { "key": "type", "label": "Typ" }, { "key": "origin", "label": "Herkunft" } ] ] }} _data={PLANT_DATA} _pagination={{"_page":1,"_pageSize":2,"_pageSizeOptions":[2,5,10]}} />

Funktionalitäten (mit Code)

Label und Tabellenbeschreibung

Das Attribut _label definiert die semantische Beschriftung der Tabelle und wird für Accessibility verwendet:

<KolTableStateful _label="Pflanzenliste" _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Familie" }, { "key": "type", "label": "Typ" }, { "key": "origin", "label": "Herkunft" } ] ] }} _data={PLANT_DATA} _pagination={{"_page":1,"_pageSize":2,"_pageSizeOptions":[2,5,10]}} />

Spaltenüberschriften und Layout

Titel werden über das Attribut _headers definiert. Es werden horizontale und vertikale Header mit beliebiger Verschachtelung unterstützt:

<KolTableStateful _label="Pflanzenliste" _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Familie" }, { "key": "type", "label": "Typ" }, { "key": "origin", "label": "Herkunft" } ] ] }} _data={PLANT_DATA} _pagination={{"_page":1,"_pageSize":2,"_pageSizeOptions":[2,5,10]}} />

Header-Struktur:

• horizontal: Array von Spaltenüberschriften
• vertical: Array von Zeilenüberschriften
• Pro Header können Eigenschaften wie label, key, colsSpan, rowSpan, render und compareFn definiert werden

Sortierung

Die Komponente unterstützt automatische Sortierung pro Spalte über die compareFn Funktion in den Header-Definitionen:

<KolTableStateful _label="Pflanzenliste" _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Familie" }, { "key": "type", "label": "Typ" }, { "key": "origin", "label": "Herkunft" } ] ] }} _data={PLANT_DATA} _pagination={{"_page":1,"_pageSize":2,"_pageSizeOptions":[2,5,10]}} />

Sortierungs-Verhalten:

• Einzelsortierung (Standard): Es wird nur eine Spalte auf einmal sortiert. Beim Sortieren einer neuen Spalte wird die Sortierung der vorherigen aufgehoben.
• Multi-Sort mit _allowMultiSort: Der Benutzer kann mehrere Spalten gleichzeitig sortieren. Die Sortierrichtung wechselt zwischen aufsteigend, absteigend und keine Sortierung.

Hinweis zu mehrdimensionalen Headern: Bei horizontalen und vertikalen Headern gleichzeitig wird empfohlen, die Render-Funktion nur in den horizontalen Headern zu definieren.

Pagination

Die _pagination Eigenschaft aktiviert automatische Seitennummerierung und bietet verschiedene Konfigurationsoptionen:

<KolTableStateful _label="Pflanzenliste" _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Familie" }, { "key": "type", "label": "Typ" }, { "key": "origin", "label": "Herkunft" } ] ] }} _data={PLANT_DATA} _pagination={{"_page":1,"_pageSize":2,"_pageSizeOptions":[2,5,10]}} />

Konfigurierbare Optionen:

• _page: Aktuelle Seitennummer (Standard: 1)
• _pageSize: Zeilen pro Seite
• _pageSizeOptions: Verfügbare Optionen für Zeilen pro Seite
• _max: Maximale Anzahl angezeigte Seiten im Steuerelement
• Weitere Optionen: siehe

Positionierung: Mit _paginationPosition kann die Position der Pagination gesteuert werden (oben, unten, oder beides).

Daten und Zellendarstellung

Die _data Eigenschaft enthält die Tabellenzeilen. Zellinhalte können über Render-Funktionen individuell formatiert werden:

<KolTableStateful _label="Pflanzenliste" _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Familie" }, { "key": "type", "label": "Typ" }, { "key": "origin", "label": "Herkunft" } ] ] }} _data={PLANT_DATA} _pagination={{"_page":1,"_pageSize":2,"_pageSizeOptions":[2,5,10]}} />

Render-Funktionen – Implementierungsvarianten:

1. String-Rückgabewert:

{
 render: (_el, cell) => `Index: ${cell.label}`,
}

2. DOM-Manipulation mit textContent:

{
 render: (el, cell) => {
 el.textContent = `Index: ${cell.label}`;
 },
}

3. innerHTML (⚠️ Sanitization erforderlich!):

{
 render: (el, cell) => {
 el.innerHTML = `<strong>${cell.label}</strong>`;
 },
}

4. React-Komponenten (mit createReactRenderElement):

import { createReactRenderElement } from '@public-ui/react-v19';
{
 render: (el) => {
 getRoot(createReactRenderElement(el)).render(
 <div>
 <KolInputText _label="Input" />
 <KolButton _label="Save" />
 </div>,
 );
 },
}

Tabellen-Footer

Das Attribut _dataFoot ermöglicht Zusammenfassungszeilen oder zusätzliche Informationen am Ende der Tabelle:

<KolTableStateful _label="Pflanzenliste" _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Familie" }, { "key": "type", "label": "Typ" }, { "key": "origin", "label": "Herkunft" } ] ] }} _data={PLANT_DATA} _pagination={{"_page":1,"_pageSize":2,"_pageSizeOptions":[2,5,10]}} />

Zeilenauswahl

Das Attribut _selection aktiviert die Zeilenauswahl (einfach oder mehrfach). Die Auswahländerungen werden über das selectionChange Event übermittelt:

<KolTableStateful _label="Pflanzenliste" _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Familie" }, { "key": "type", "label": "Typ" }, { "key": "origin", "label": "Herkunft" } ] ] }} _data={PLANT_DATA} _pagination={{"_page":1,"_pageSize":2,"_pageSizeOptions":[2,5,10]}} />

Konfigurierbare Optionen:

• multiple: Einfachauswahl (default) oder mehrfache Auswahl
• label: Funktion zur Generierung von Labels für jede Zeile
• selectedKeys: Aktuell ausgewählte Zeilenidentifizierer
• keyPropertyName: Property-Name zur Identifikation von Zeilen (z.B. id)

Einstellungsmenü

Mit _hasSettingsMenu wird ein Menü aktiviert, über das Benutzer Tabelleneinstellungen anpassen können (z.B. sichtbare Spalten):

<KolTableStateful _label="Pflanzenliste" _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Familie" }, { "key": "type", "label": "Typ" }, { "key": "origin", "label": "Herkunft" } ] ] }} _data={PLANT_DATA} _pagination={{"_page":1,"_pageSize":2,"_pageSizeOptions":[2,5,10]}} />

Fixierte Spalten

Das Attribut _fixedCols definiert Spalten, die beim horizontalen Scrollen sichtbar bleiben – Angabe als [start, end]:

<KolTableStateful _label="Pflanzenliste" _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Familie" }, { "key": "type", "label": "Typ" }, { "key": "origin", "label": "Herkunft" } ] ] }} _data={PLANT_DATA} _pagination={{"_page":1,"_pageSize":2,"_pageSizeOptions":[2,5,10]}} />

Events

Zur Behandlung von Events bzw. Callbacks siehe .

Event	Auslöser	Value
selectionChange	Die Auswahl von Tabellenzeilen hat sich geändert	Array von ausgewählten Zeilen (oder einzelne Zeile bei Einfachauswahl)
settingsChange	Tabelleneinstellungen wurden durch den Benutzer geändert	Objekt vom Typ TableSettings

API

Overview

The Table component is primarily used for the clear presentation of data sets. It is designed to automatically determine all data-dependent values and render the table accordingly. This includes optional features such as column sorting and pagination.

Properties

Property	Attribute	Description	Type	Default
_allowMultiSort	_allow-multi-sort	Defines whether to allow multi sort.	boolean | undefined	undefined
_data (required)	_data	Defines the primary table data.	KoliBriTableDataType[] | string	undefined
_dataFoot	_data-foot	Defines the data for the table footer.	KoliBriTableDataType[] | string | undefined	undefined
_fixedCols	--	Defines the fixed number of columns from start and end of the table	[number, number] | undefined	undefined
_hasSettingsMenu	_has-settings-menu	Enables the settings menu if true (default: false).	boolean | undefined	undefined
_headers (required)	_headers	Defines the horizontal and vertical table headers.	string | { horizontal?: KoliBriTableHeaderCellWithLogic[][] | undefined; vertical?: KoliBriTableHeaderCellWithLogic[][] | undefined; }	undefined
_label (required)	_label	Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.).	string	undefined
_on	--	Defines the callback functions for table events.	undefined | { onSelectionChange?: EventValueOrEventCallback<Event, StatefulSelectionChangeEventPayload> | undefined; }	undefined
_pagination	_pagination	Defines whether to show the data distributed over multiple pages.	boolean | string | undefined | { _page: number; } & { _on?: KoliBriPaginationButtonCallbacks | undefined; _page?: number | undefined; _max?: number | undefined; _boundaryCount?: number | undefined; _hasButtons?: boolean | Stringified<PaginationHasButton> | undefined; _pageSize?: number | undefined; _pageSizeOptions?: Stringified<number[]> | undefined; _siblingCount?: number | undefined; _customClass?: string | undefined; _label?: string | undefined; _tooltipAlign?: AlignPropType | undefined; }	undefined
_paginationPosition	_pagination-position	Controls the position of the pagination.	"both" | "bottom" | "top" | undefined	'bottom'
_selection	_selection	Defines how rows can be selected and the current selection.	string | undefined | ({ disabledKeys?: KoliBriTableSelectionKeys | undefined; keyPropertyName?: string | undefined; label: (row: KoliBriTableDataType) => string; multiple?: boolean | undefined; selectedKeys?: KoliBriTableSelectionKeys | undefined; })	undefined

Methods

getSelection

getSelection() => Promise<KoliBriTableDataType[] | null>

Returns the selected rows.

Returns

Type: Promise<KoliBriTableDataType[] | null>

---