Progress

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: Fortschrittsanzeige, Fortschrittsbalken

Beschreibung: Die Progress-Komponente visualisiert den Fortschritt oder die Vollendung eines Prozesses oder einer Aufgabe. Sie ermöglicht es Nutzern, den aktuellen Status im Hin­blick auf ein definiertes Ziel zu verstehen.

Beispiel

Darstellung der Komponente mit horizontalem Fortschrittsbalken und Beschriftung.

<KolProgress _label="Fortschritt" _max={100} _value={65} _variant="bar" />

Barrierefreiheit

Die Progress-Komponente wurde mit Fokus auf Barrierefreiheit entwickelt:

• Semantische Struktur: Die Komponente verwendet das ARIA-Attribut role="progressbar" zur korrekten Kennzeichnung gegenüber assistiven Technologien.
• Beschriftung: Das Attribut _label wird als aria-label oder label-ähnlich dargestellt und informiert Nutzer assistiver Technologien über den Zweck des Fortschrittsbalkens.
• Werte: Die aktuellen und maximalen Werte werden über aria-valuenow und aria-valuemax kommuniziert.
• Transparenz: Der Fortschritt wird immer prozentual berechnet und visuell dargestellt, um Transparenz zu gewährleisten.

Links und Referenzen

Verwendung

Best Practices / Empfehlungen

• Aussagekräftige Beschriftungen: Verwenden Sie bei _label klare Beschreibungen, die vermitteln, welche Aufgabe oder welcher Prozess gerade lädt (z.B. „Datei wird hochgeladen" statt genau „Upload").
• Realistische Wertespannen: Wählen Sie _max basierend auf der tatsächlichen Aufgabe. For example, für eine Aufgabe mit 12 Schritten können Sie _max="12" nutzen, statt auf 100 zu normalisieren.
• Visuelle Klarheit: Nutzen Sie _variant="bar" für horizontale Kontexte und _variant="cycle" für kompakte Darstellungen.
• Unit-Informationen klar machen: Wenn _unit gesetzt ist, wird dieses intern verarbeitet, aber kommunizieren Sie klar, was die Einheit bedeutet (z.B. über _label).
• Werte begrenzen: Werte außerhalb des Bereichs [0, max] werden automatisch begrenzt. Validieren Sie Eingabewerte bereits vor Übergabe an die Komponente.
• Variantenauswahl: Nutzen Sie _variant="bar" für längere Prozesse und _variant="cycle" für schnelle oder räumlich begrenzte Vorgänge.

Anwendungsfälle

• Datei-Uploads/Downloads: Anzeige des Fortschritts beim Upload oder Download von Dateien.
• Form-Completion: Visualisierung von Schritten in mehrstufigen Formularen oder Checklisten.
• Prozessfortschritt: Anzeige von Ladebalken bei längerlaufenden Prozessen im Hintergrund.
• Ressourcennutzung: Darstellung von Auslastung (z.B. Stromspeicher, Speicherplatz, CPU).
• Aufgabenvervollständigung: Tracking von abgeschlossenen Aufgaben in einer Liste oder eines Gesamtziels.

FAQ

Kann ich Zwischenwerte anzeigen, die über _max hinausgehen?
Ja, der Wert wird automatisch auf _max begrenzt dargestellt. Dies ist intentional, um die Integrität der Visualisierung zu bewahren.

Wird _unit irgendwo angezeigt?
Nein, _unit wird nicht visuell dargestellt, aber kann über _label vermittelt werden.

Kann ich Dezimalzahlen als -_value oder _max verwenden?
Ja, die Progress-Komponente verarbeitet auch Dezimalzahlen, beispielsweise _value="5.5" bei _max="10".

Konstruktion / Technik

Playground

<KolProgress _label="Fortschritt" _max={100} _value={20} />

Funktionalitäten (mit Code)

Horizontaler Fortschrittsbalken

Der horizontale Balken ist die Standard-Variante und eignet sich für die Darstellung in größeren Kontexten.

<KolProgress _label="Progress" _max={100} _value={45} _variant="bar" />

Zirkulärer Fortschrittsbalken

Die zirkuläre Variante ist kompakt und eignet sich für kleine Bereiche oder als Indikator für schnelle Prozesse.

<KolProgress _label="Cycle" _max={100} _value={65} _variant="cycle" />

Beschriftung und Unit

Mit _label können Sie den Fortschritt beschreiben, _unit kann intern zur Berechnung verwendet werden.

<KolProgress _label="Download-Speed" _max={500} _unit="MB" _value={250} />

Aufgabenverfolgung

Anwendungsbeispiel: Verfolgung von abgeschlossenen Aufgaben aus einer Liste.

<KolProgress _label="Aufgaben erledigt" _max={12} _value={8} />

API

Overview

The Progress component visualizes the completion status of a task or process. It supports both determinate (percentage-based) and indeterminate variants.

Properties

Property	Attribute	Description	Type	Default
_label	_label	Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.).	string | undefined	undefined
_max (required)	_max	Defines the maximum value of the element.	number	undefined
_unit	_unit	Defines the unit of the step values (not shown).	string | undefined	undefined
_value (required)	_value	Defines the value of the element.	number	undefined
_variant	_variant	Defines which variant should be used for presentation.	"bar" | "cycle" | undefined	undefined

---