TableStateful

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 _data={...} _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Familie" }, { "key": "type", "label": "Typ" }, { "key": "origin", "label": "Herkunft" } ] ] }} _label="Pflanzenliste" _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.

Playground

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

Selection

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

Funktionalitäten

Label und Tabellenbeschreibung

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

<KolTableStateful _data={...} _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Familie" }, { "key": "type", "label": "Typ" }, { "key": "origin", "label": "Herkunft" } ] ] }} _label="Pflanzenliste" _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 _data={...} _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Familie" }, { "key": "type", "label": "Typ" }, { "key": "origin", "label": "Herkunft" } ] ] }} _label="Pflanzenliste" _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 _data={...} _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Familie" }, { "key": "type", "label": "Typ" }, { "key": "origin", "label": "Herkunft" } ] ] }} _label="Pflanzenliste" _pagination={{ "_page": 1, "_pageSize": 2, "_pageSizeOptions": [ 2, 5, 10 ] }} />

Erklärung zur compareFn: Stencil gibt die zu vergleichenden Objekte nicht mit ihrem Ursprünglichen Type (hier PlantRecord) zurück. Deswegen muss für eine saubere Typisierung der Umweg über unknown gegangen werden:

compareFn: (a, b) => (a as unknown as PlantRecord).name.localeCompare((b as unknown as PlantRecord).name)

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 _data={...} _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Familie" }, { "key": "type", "label": "Typ" }, { "key": "origin", "label": "Herkunft" } ] ] }} _label="Pflanzenliste" _pagination={{ "_page": 1, "_pageSize": 2, "_pageSizeOptions": [ 2, 5, 10 ] }} />

Konfigurierbare 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:

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 _data={...} _dataFoot={[ { "family": "all beautiful" } ]} _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Familie" }, { "key": "type", "label": "Typ" }, { "key": "origin", "label": "Herkunft" } ] ] }} _label="Pflanzenliste" _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:

Selection

<KolTableStateful _data={...} _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Familie" }, { "key": "type", "label": "Typ" }, { "key": "origin", "label": "Herkunft" } ] ] }} _label="Pflanzenliste" _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
• disabledKeys: Deaktivierte 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 _data={...} _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Familie" }, { "key": "type", "label": "Typ" }, { "key": "origin", "label": "Herkunft" } ] ] }} _label="Pflanzenliste" _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 _data={...} _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Familie" }, { "key": "type", "label": "Typ" }, { "key": "origin", "label": "Herkunft" } ] ] }} _label="Pflanzenliste" _pagination={{ "_page": 1, "_pageSize": 2, "_pageSizeOptions": [ 2, 5, 10 ] }} />

Beschriftung über externe Elemente (aria-labelledby)

Mittels _ariaLabelledby kann die Tabelle barrierefrei über ein externes Element (z. B. einer vorangestellten Überschrift) beschriftet werden. Das Attribut _label sollte dennoch gesetzt werden, da es als Fallback dient, falls die externe Referenz nicht aufgelöst werden kann.

<KolTableStateful _ariaLabelledby="table-stateful-heading" _data={...} _headers={{ "horizontal": [ [ { "key": "name", "label": "Name" }, { "key": "family", "label": "Familie" }, { "key": "type", "label": "Typ" }, { "key": "origin", "label": "Herkunft" } ] ] }} _label="Pflanzenliste" _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
_ariaLabelledby	_aria-labelledby	References an external element by ID that serves as the accessible label for this table. Uses ElementInternals.ariaLabelledByElements to cross the Shadow DOM boundary. Supported by desktop screen readers (NVDA, JAWS with Chrome/Firefox). Not yet supported by mobile screen readers (TalkBack, VoiceOver iOS) — use _label instead.	string | 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
_loading	_loading	Wether the table shows a loading spinner (default: false).	boolean | undefined	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
_variant	_variant	Defines which variant should be used for presentation.	string | string[] | undefined	undefined

Methods

getSelection

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

Returns the selected rows.

Returns

Type: Promise<KoliBriTableDataType[] | null>

resetSort() => Promise<void>

Resets the sort state to the default values defined in the _headers prop.

Returns

Type: Promise<void>

---