Note: Es gibt veraltete Versionen dieser Komponente. Wechseln Sie zu einer Version, die älter als 10.0.x ist, um die entsprechende Dokumentation anzuzeigen.
Mithilfe von Kontrollkästchen können Benutzer Elemente in einer Liste auswählen. Sie tauchen häufig in Formularen auf, in denen Benutzerinformationen erfasst werden müssen. Bei Verwendung von Kontrollkästchen können Benutzer ein oder mehrere Elemente in einer Gruppe auswählen.
Eine ausführliche Orientierungshilfe zur Verwendung dieser Komponente finden Sie im folgenden Entscheidungsbaum für UI-Komponenten.
Eine Kontrollkästchengruppe ist eine Liste von Kontrollkästchenelementen unter einer Gruppenbezeichnung. Benutzer können unter der Gruppenbezeichnung alle relevanten Elemente auswählen. Dieses Format ist nützlich, wenn es mehrere gültige Optionen für eine einzelne Instanz gibt.
In Jutro werden auch Kontrollkästchen mit einem einzigen Element unterstützt. Beachten Sie, dass Kontrollkästchen verwendet werden können, um eine Option zu aktivieren oder zu deaktivieren (z. B. beim Aktivieren oder Deaktivieren einer Einstellung).
Kontrollkästchengruppe (links) und einzelnes Kontrollkästchen (rechts).
Das Kontrollkästchen besteht aus den folgenden Elementen:
Beschriftung der Kontrollkästchengruppe: Erläutert den Zweck der Kontrollkästchengruppe.
Hilfetext (optional): Gibt zusätzlichen Kontext für die Kontrollkästchengruppe an.
Kontrollkästcheneingabe: Gibt den entsprechenden Zustand an. Ist standardmäßig deaktiviert.
Kontrollkästchenbeschriftung: Beschreibt die Information, die aktiviert oder deaktiviert wird.
QuickInfo-Symbol (optional): Dient zur Verdeutlichung des Kontexts für ein bestimmtes Kontrollkästchen. Wenn Sie mit dem Mauszeiger darauf zeigen, wird die QuickInfo angezeigt.
Eine Kontrollkästchengruppe kann je nach Seitenstruktur vertikal oder horizontal angeordnet werden. Standardmäßig sind Kontrollkästchen vertikal angeordnet, um das Lesen zu erleichtern.
Wie bei allen Eingabekomponenten kann die Beschriftung der Kontrollkästchengruppe oben (Standard) oder links neben der Eingabe selbst angezeigt werden.
Kontrollkästchengruppen müssen eine Beschriftung aufweisen, die beschreibt, wofür die Liste der Optionen steht. Eine Kontrollkästchengruppe ohne Beschriftung ist uneindeutig und nicht barrierefrei.
Verwenden Sie die Gruppenbeschriftung, um die Kategorie der Gruppe anzugeben oder zu beschreiben, welche Aktionen im Folgenden auszuführen sind.
Fügen Sie eine Beschriftung hinzu, die eindeutig beschreibt, wofür die Liste der Optionen steht.
Gehen Sie nicht davon aus, dass die Optionen ohne Beschriftung selbsterklärend sind.
Klare und einheitliche Beschriftungen für Kontrollkästchen verwenden
Versuchen Sie, alle Beschriftungen in einer Kontrollkästchengruppe so parallel wie möglich zu gestalten. Sie sollten das gleiche Format und ungefähr die gleiche Länge haben.
Verwenden Sie klare, prägnante und eindeutige Beschriftungen. Beschriftungen sollten Optionen beschreiben, die für durchschnittliche Benutzer leicht verständlich sind.
Verwenden Sie für Kontrollkästchenbeschriftungen positive und aktive Formulierungen. Machen Sie deutlich, was passiert, wenn der Benutzer ein bestimmtes Kontrollkästchen aktiviert, und was passiert, wenn er es nicht aktiviert.
Vermeiden Sie Verneinungen, wie z. B. „Senden Sie mir keine E-Mail-Benachrichtigungen“. Dies würde bedeuten, dass der Benutzer das Kontrollkästchen aktivieren muss, damit nichts passiert.
Verwenden Sie die erste Person, wenn Sie den Benutzer um seine Zustimmung bitten. Beispiel: „Ich stimme den Nutzungsbedingungen zu“.
Verwenden Sie parallele Formulierungen und versuchen Sie, die Länge bei allen Beschriftungen in etwa gleich zu halten.
Verwenden Sie keine sehr unterschiedlichen Formulierungen. Dies kann Benutzer bremsen oder sogar verwirren.
Formulieren Sie Kontrollkästchenbeschriftungen prägnant
Beschränken Sie Kontrollkästchenbeschriftungen auf eine einzige Zeile. Wir empfehlen, für Kontrollkästchenbeschriftungen ein bis drei Wörter zu verwenden.
Kürzen Sie Kontrollkästchenbeschriftungen nicht mit Auslassungspunkten (...) ab. Wenn die Beschriftung zu lang für den verfügbaren horizontalen Platz ist, sollten Sie eine andere Formulierung wählen. Lange Kontrollkästchenbeschriftungen können auch in eine zweite Zeile umbrochen werden. Dies ist besser als kürzen.
Halten Sie den Text der Kontrollkästchenbeschriftung kurz und prägnant. Gegebenenfalls kann er in eine zweite Zeile umbrochen werden.
Kürzen Sie die Kontrollkästchenbeschriftung nicht mit Auslassungspunkten ab.
Kontrollkästchengruppen und Kontrollkästchen können Fehlermeldungen enthalten, um anzuzeigen, dass eine Auswahl erforderlich ist, um fortzufahren, oder dass die getroffene Auswahl ungültig ist.
Verwenden Sie für Fehlertext die übliche Groß- und Kleinschreibung. Schreiben Sie 1 bis 2 kurze, vollständige Sätze, die mit einem Punkt enden.
Verwenden Sie Fehlermeldungstexte, um den Benutzer anzuleiten und ihm eine Lösung aufzuzeigen.
Schreiben Sie keine zweideutigen Fehlermeldungen und lassen Sie die Benutzer nicht im Unklaren darüber, wie ein Problem zu lösen ist.
Markieren Sie erforderliche Felder mit einem Sternchen (*). Das Sternchen steht vor der Feldbeschriftung. Benutzer können so leicht herausfinden, welche Felder erforderlich sind, indem sie nur das Zeichen ganz links in der Beschriftung prüfen.
Zusätzlich zur Markierung erforderlicher Felder mit einem Sternchen wird empfohlen, klare Anweisungen am oberen Rand des Formulars einzufügen, z. B. „Alle mit einem Sternchen gekennzeichneten Felder sind Pflichtfelder“, um sicherzustellen, dass die Benutzer die Bedeutung des Sternchens verstehen.
Verwenden Sie ein Sternchen, um anzuzeigen, dass ein Feld ein Pflichtfeld ist.
Verwenden Sie kein Sternchen, um optionale Elemente zu kennzeichnen.
Die Komponente „Kontrollkästchen“ hat 2 Hauptzustände: nicht markiert und markiert. Bei Kontrollkästchen ist standardmäßig keine der Optionen ausgewählt.
Zusätzlich zum nicht markierten und markierten Zustand verfügen Kontrollkästchen auch über interaktive Zustände für aktiviert, deaktiviert, schwebend, fokussiert, aktiv und Fehler.
Visualisierung
Zustand
Beschreibung
Aktiviert
Teilt dem Benutzer mit, dass das Element für die Interaktion aktiviert ist (Standard).
Deaktiviert
Teilt dem Benutzer mit, dass das Element derzeit nicht interaktiv ist.
Schwebend
Zeigt an, dass der Benutzer den Mauszeiger auf dem Element positioniert hat (nur Desktop).
Fokussiert
Zeigt an, dass der Benutzer das Element hervorgehoben hat, in der Regel über eine Eingabemethode wie Tastatur oder Sprachbefehl.
Aktiv
Gibt an, dass der Benutzer auf das Element klickt oder tippt.
Fehler
Gibt an, dass der Benutzer nicht alle Pflichtfelder bearbeitet hat (oder ein anderer formularbezogener Fehler).
Benutzer können eine Option auswählen, indem sie entweder auf das Kontrollkästchen selbst oder auf die entsprechende Beschriftung klicken. Untersuchungen zeigen, dass schneller auf ein größeres Ziel geklickt werden kann.
Wenn das Kontrollkästchen den Fokus hat, ändert sich durch Drücken der Leertaste der Zustand des Kontrollkästchens. Dies entspricht den vom World Wide Web Consortium (W3C) festgelegten Standards.
Für die Kontrollkästchengruppe: Die Kontrollkästchengruppe implementiert <input type='checkbox'>. Der barrierefreie Name der Gruppe wird von der Gruppenbeschriftung abgeleitet. Dies kann über das Beschriftungsfeld in Storybook ge ändert werden. Eine „for/id“-Verknüpfung wird implementiert, um jedes einzelne Kontrollkästchen mit seiner Beschriftung zu verknüpfen, während der Status „markiert/unmarkiert“ des Elements über das Attribut aria-checked kommuniziert wird.
Für das einzelne Kontrollkästchen: Das Element „Kontrollkästchen“ wird programmgesteuert mit seiner Beschriftung verknüpft. Das bedeutet, dass Benutzer mit der TAB-Taste durch Elemente navigieren können und ihre jeweiligen Beschriftungen von Screenreadern angesagt werden. Der Status „markiert/unmarkiert“ wird über das Attribut aria-checked kommuniziert.
Das Kontrastverhältnis von Textelementen zu ihrem Hintergrund liegt über 4,5:1.
Nicht-textuelle Inhalte, die eine Bedeutung vermitteln sollen (z. B. Symbole und Fokusanzeigen), weisen ein Kontrastverhältnis von mindestens 3:1 zu den angrenzenden Farben auf.
Das jeweilige Element kann sowohl über eine Tastatur als auch über eine Maus bedient werden.
Der Zugriff auf die Inhalte erfolgt über Screenreader wie JAWS oder VoiceOver.
Die Konformität mit den Richtlinien für Barrierefreiheit hängt letztendlich davon ab, wie diese Komponente implementiert und angepasst wird. Vom Autor des Inhalts vorgenommene Änderungen können sich auf die Barrierefreiheit auswirken. Details zu unserem Modell der geteilten Verantwortung finden Sie in unserer Erklärung zur Barrierefreiheit von Jutro.
Die Beschriftung der Kontrollkästchen muss klar und prägnant sein.
Benutzer müssen informiert werden, wenn die Aktivierung eines Kontrollkästchens eine Änderung des Kontexts zur Folge hat.
Note: Es gibt veraltete Versionen dieser Komponente. Wechseln Sie zu einer Version, die älter als 10.0.x ist, um die entsprechende Dokumentation anzuzeigen.
Vergewissern Sie sich, dass Sie die API-Oberfläche der Design System-Komponenten und die damit verbundenen Auswirkungen und Kompromisse verstehen. Erfahren Sie mehr in unserer Einführung zur Komponenten-API.
State of the checkbox. If set to true, the checkbox is checked. Takes precedence over initialChecked. If this prop is passed, the component works in controlled mode and its value will change only if this prop changes.
If set to true, the component is rendered in disabled state. Note that when checkbox group is disabled all checkboxes inside group are disabled as well.
Möglichkeit zum Übergeben von nativen HTML-Attributen
Ref mit imperativen Handlern
Eine native event-Eigenschaft
Übergeben von HTML-Eigenschaften an die Komponente
Sie können HTML-Eingabeattribute verwenden, mit Ausnahme derjenigen, die von Jutro überschrieben werden. Diese Attribute werden dem HTML-Element input zugewiesen.
<CheckboxGrouplabel="This is a group"> <Checkbox label="This is the first one" id="firstOption" /> <Checkbox label="This is the second one" id="secondOption" /> <Checkbox label="This is the third one" id="thirdOption" /> </CheckboxGroup>
Durch die Übergabe der id-Eigenschaft wird diese Teil des HTML input-Elements, das im HTML-DOM erstellt wird.
Die Jutro-Eingaben haben imperative Handler als Mechanismus implementiert, um Zugang zu einigen gängigen nativen Funktionen zu bieten, die für Sie nützlich sein könnten. Die folgenden Funktionen sind verfügbar:
Fokus setzen ermöglicht es, den Fokus des Benutzers auf eine bestimmte Komponente zu setzen.
Fokus aufheben ermöglicht es, den Fokus von der Komponente zu entfernen.
Zur Komponente scrollen ermöglicht es, den Benutzer zu einem bestimmten Bereich der Seite zu führen.
Diese Funktionen werden über die ref-Eigenschaft bereitgestellt, die sie wie folgt verfügbar macht:
Anstelle der Eigenschaft value verwendet die Komponente Checkbox die Eigenschaft checked, um Informationen dazu zu speichern, ob das Kontrollkästchen aktiviert oder deaktiviert ist.
Vorrang der Eigenschaften disabled, displayOnly und readOnly
Wenn zwei oder mehr der Eigenschaften disabled, displayOnly, und readOnly gleichzeitig auf true gesetzt werden, gilt die folgende Vorrangregel:
Obwohl einige Jutro-Komponenten ergänzende Funktionen oder eine Hilfsfunktion zur Erleichterung des Validierungsprozesses bereitstellen, liegt es in Ihrer Verantwortung als Entwickler, die Validierung von Benutzereingaben (mit oder ohne Verwendung der ergänzenden Hilfsfunktionen) durchzuführen und zu entscheiden, welche Fehlermeldungen angezeigt werden sollen.
Das Verhalten von Jutro-Komponenten hängt von der Implementierung durch den Entwickler ab.
Wann werden Fehlermeldungen angezeigt?
Fehlermeldungen werden nur angezeigt, wenn Sie sie über die Eigenschaft stateMessages an die Komponente übergeben. Diese Eigenschaft empfängt ein Objekt mit dem folgenden Inhalt:
Die Komponente zeigt alle bereitgestellten Fehlermeldungen in der gleichen Reihenfolge wie im Array an.
Wann erfolgt die Validierung?
Dies ist Ihre Entscheidung als Entwickler. Da die Komponenten nicht festlegen, wann die Validierung durchgeführt wird oder wann der Fehler angezeigt werden muss, müssen Sie die Logik für die Behandlung entsprechend den Projektanforderungen implementieren, z. B. während der Benutzer den Inhalt bearbeitet, wenn die Komponente den Fokus verliert und bei der Formularübermittlung.
Note: Es gibt veraltete Versionen dieser Komponente. Wechseln Sie zu einer Version, die älter als 10.0.x ist, um die entsprechende Dokumentation anzuzeigen.
Die Checkbox-Komponente kann allein, außerhalb des CheckboxGroup-Kontexts verwendet werden.
<Checkboxlabel="This is a single checkbox"/>
Einfache Kontrollkästchen in einer Kontrollkästchengruppe
Die CheckboxGroup-Komponente dient als Container für eine Gruppe von Checkbox-Elementen. Die Beschriftung kann wahlweise ein- oder ausgeblendet werden, ist aber für die Barrierefreiheit der Komponente zwingend erforderlich.
<CheckboxGrouplabel="This is a group"> <Checkboxlabel="option 1"/> <Checkboxlabel="option 2"/> </CheckboxGroup>
Sie können die Beschriftung für CheckboxGroup ausblenden, indem Sie die Eigenschaft hideLabel auf true festlegen. Dies hat keine Auswirkungen auf das übrige Verhalten des CheckboxGroup-Elements.
<CheckboxGroup label="This is only for aria-label" hideLabel={true}> <Checkboxlabel="option 1"/> <Checkboxlabel="option 2"/> </CheckboxGroup>
Mit beiden Komponenten können Entwickler Fehlermeldungen anzeigen. Bei Festlegung auf der CheckboxGroup-Ebene werden Fehler unter allen Optionen angezeigt. Wenn sie jedoch auf der Checkbox-Ebene innerhalb einer CheckboxGroup-Komponente festgelegt ist, wird die Meldung ignoriert und hat keine Auswirkungen.
exportfunctionCheckboxMessages(){ const[validationMessages, setValidationMessages]=useState({}); const[groupValidationMessages, setGroupValidationMessages]=useState({}); const onChange =useCallback((e, newChecked)=>{ setValidationMessages({}); setGroupValidationMessages({}); if(newChecked){ setValidationMessages({error:['This is ignored']}); setGroupValidationMessages({error:['Only second checkbox can be marked']}); } },[]); return( <CheckboxGroup label="Do not select the forbidden option" stateMessages={groupValidationMessages} > <Checkbox label="Forbidden option" onChange={onChange} stateMessages={validationMessages} /> <Checkboxlabel="You can select this one"/> </CheckboxGroup> ); } }
Obwohl dies nicht als Bestandteil der Komponente Checkbox implementiert ist, ist das native Verhalten eines HTML-Eingabeelements verfügbar. In diesem Fall kann der unbestimmte Zustand programmgesteuert über JavaScript festgelegt werden. Ein Kontrollkästchen im unbestimmten Zustand wird mit einer horizontalen Linie anstelle mit einem Häkchen angezeigt. Im folgenden Beispiel wird der Stil geändert, um die Option sichtbar zu machen.
exportfunctionSetIndeterminateState(){ const onChange =useCallback((e, newCheck)=>{ (document.getElementById('checkbox2')asHTMLInputElement).indeterminate= newCheck; },[]); const style ={ opacity:100}; return( <CheckboxGrouplabel="Group of checkboxes"> <Checkbox label="Set the next checkbox as 'indeterminate'" onChange={onChange} /> <Checkbox label="This is another checkbox" id="checkbox2" checked={false} style={style} /> </CheckboxGroup> ); }
Sie können Kontextinformationen zu den Komponenten CheckboxGroup und Checkbox hinzufügen, indem Sie deren benutzerdefinierte Eigenschaften verwenden.
Die Eigenschaft secondaryLabel unterstützt ein intlMessageShape-Objekt, um zusätzlichen Kontext unter der Hauptbeschriftung anzuzeigen.
Die Eigenschaft tooltip unterstützt entweder ein intlMessageShape-Objekt oder ein benutzerdefiniertes Objekt. Sie können sie verwenden, um eine QuickInfo mit zusätzlichen Informationen anzuzeigen. Sie können das Verhalten der QuickInfo mit dem benutzerdefinierten Objekt ändern.
<CheckboxGroup label="This is a group" tooltip="Select one of the available options" secondaryLabel="This label provides additional context."> <Checkbox tooltip="By selecting this option, you enable feature X." label="Option 1" value="1" /> <Checkbox tooltip={{text:"By selecting this option, you enable feature Y.",trigger:"pointerover"}} label="Option 2" value="2" secondaryLabel="This label provides additional context." /> </CheckboxGroup>
Die Eigenschaft secondaryLabel wurde der Komponente Checkbox hinzugefügt. Mit dieser Eigenschaft können Sie eine zusätzliche Beschriftung hinzufügen, die mit dem einzelnen Kontrollkästchen verknüpft ist.
Es wurden die neuen Komponenten @jutro/components/Checkbox und @jutro/components/CheckboxGroup eingeführt, die CheckboxField und CheckboxGroupField ersetzen.
Die früheren Kontrollkästchen-bezogenen Komponenten wurden abgekündigt und in das @jutro/legacy-Paket verschoben. Wechseln Sie zu einer älteren Version, um die zugehörige Dokumentation anzuzeigen.
