Praxisleitfaden ARIA-Befehle verständlich benennen
Eine Rolle allein benennt keinen Befehl
Eine Schaltfläche kann technisch als Button erkennbar sein und ihre Handlung trotzdem verschweigen. Sehen Sie, wie Sie den fehlenden Namen finden, ergänzen und gezielt nachprüfen.
aria-command-nameWCAG 4.1.2
Sehen Sie, was sich durch die Korrektur ändert.
Zuletzt geprüft: Permalink: https://spanier.one/wcag-aria-command-name.html
Befund verstehen
Der Scanner erkennt die Rolle, aber keinen Namen
Erkannter Befund
Das fällt auf
.legacy-channel-import [role="button"] löst aria-command-name aus: Das Element enthält weder Text noch eine zugängliche Beschriftung.So ist es einzuordnen
Im importierten Kanalverzeichnis steht ein leeres div mit role="button". Die Rolle sagt assistiven Technologien, welche Art von Element vorliegt. Sie erklärt nicht, welche Handlung damit verbunden ist.
Das bedeutet es für die Nutzung
Wer sich Bedienelemente vorlesen lässt, erhält hier keine Bezeichnung für den Kurzbefehl. Auch der benachbarte Text „#quakenet“ wird ohne entsprechende Verknüpfung nicht zu seinem Namen.
- Regel
aria-command-name- Referenz
- WCAG 4.1.2
Namensdiagnose vor der Korrektur
Rolle: button
Zugänglicher Name: leer
aria-command-name: Verstoß (Axe-Auswirkung: serious)Befehle in ihrer Verwendung prüfen
Eine gemeinsame Komponente kann je Einsatz eine andere Handlung benennen. Prüfen Sie Name und Aktion zusammen.
- Kanalverzeichnis× Befund im Beispiel
- Kanaldetail× Befund im Beispiel
- Hilfeseite Ohne diesen Befund im Beispiel
Nach der Änderung erneut prüfenPrüfen Sie die gerenderten Befehle und ihre tatsächliche Aktion auf jeder verwendenden Seite.
Schematische Zuordnung, kein Scanergebnis. „Ohne diesen Befund“ sagt nichts über andere Barrieren aus.
Welche Handlung soll der Name vermitteln?
Klären Sie zunächst den tatsächlichen Zweck des Befehls. Der leere Import verrät ihn nicht. Für dieses Beispiel nehmen wir die Handlung „Kanalverzeichnis öffnen“ an.
Fundstelle zuordnen
Der leere Kurzbefehl zwischen den Importdaten
Der Ausschnitt enthält den vollständigen Importbereich mit Überschrift, Erläuterung und benachbarten Kanalangaben. Die Markierung grenzt genau die namenlose ARIA-Schaltfläche ein.
Das umrandete leere Quadrat ist als Button ausgezeichnet. Weder sein Inhalt noch ein Attribut benennt die Handlung. Die übrigen Importdaten erklären den Seitenkontext, beschriften dieses Element aber nicht.
Namen ergänzen
Die Handlung am vorhandenen Element benennen
Das Beispiel ergänzt aria-label="Kanalverzeichnis öffnen" am ursprünglichen div. Der Browser kann daraus einen Namen bilden, obwohl die sichtbaren Pixel gleich bleiben. Ein Handler zum Öffnen des Verzeichnisses wird damit nicht angelegt.
Was sich im Code ändert
Die geänderte Stelle im Beispiel. Unveränderter Anfang und Schluss sind hier ausgeblendet.
- Kommt hinzu
aria-label="Kanalverzeichnis öffnen"
In Ihrer Komponente Tragen Sie den Namen im Feld für die zugängliche Beschriftung ein und kontrollieren Sie das gerenderte Element. Bei eigener Entwicklung bevorzugen Sie einen nativen Button mit sichtbarem Text und implementierter Aktion.
Vollständigen Code vergleichen
Vorher
<div role="button"></div>Nachher
<div role="button"
aria-label="Kanalverzeichnis öffnen"></div>Markierte Zeilen wurden geändert
In der Anwendung umsetzen
Name, Rolle und Verhalten zusammen prüfen
Übernehmen Sie den Beispielnamen nur, wenn er die tatsächliche Handlung beschreibt. Eine verständliche Beschriftung gehört zur Funktion der Komponente.
- 1
Formulieren Sie die Handlung mit ihrem Gegenstand, etwa „Kanalverzeichnis öffnen“ statt „Button“ oder „Hier klicken“.
- 2
Wenn sichtbarer Text vorhanden ist, halten Sie ihn mit dem zugänglichen Namen konsistent.
- 3
Kontrollieren Sie aria-labelledby nach dem Rendern: Die referenzierte ID muss eindeutig sein und zu einem beschriftenden Text führen.
- 4
Prüfen Sie bei einer selbst gebauten ARIA-Schaltfläche Fokus, Aktivierung mit Enter und Leertaste sowie das Ergebnis der Aktion.
Fehlversuche vermeiden
Warum ein ergänztes Attribut nicht immer hilft
Die Rolle als Namen behandeln
role="button" kennzeichnet den Elementtyp. aria-label="Button" wäre zwar Text, würde die Handlung aber weiterhin verschweigen.
Eine leere Referenz setzen
aria-labelledby liefert keine brauchbare Beschriftung, wenn die angegebene ID fehlt oder ihr Ziel keinen nutzbaren Text enthält.
Nur eine Beschreibung hinzufügen
aria-describedby ergänzt eine Erklärung. Es ersetzt den zugänglichen Namen der Schaltfläche nicht.
Den grünen Namenscheck mit Bedienbarkeit verwechseln
Ein benanntes div wird durch ARIA nicht automatisch fokussierbar oder per Tastatur aktivierbar. Diese Funktion fehlt im gezeigten Import weiterhin.
Der Namensfehler ist an dieser Stelle behoben
Axe meldet nach der Ergänzung einen tatsächlichen Pass für aria-command-name am selben Element. Das neue aria-label ist nicht leer; der Ausschnitt bleibt visuell unverändert.
Der Nachweis betrifft den fehlenden Namen dieses Elements. Er bestätigt weder die vollständige Bedienbarkeit der Schaltfläche noch WCAG-Konformität der Kalibrierseite.
Namensdiagnose nach der Korrektur
Rolle: button
Zugänglicher Name: Kanalverzeichnis öffnen
Axe: aria-command-name · Pass am selben Element
Befehlsfunktion und Tastaturbedienung: nicht durch diesen Test bestätigtPrüfumfang abgrenzen
Ein vorhandener Name ist der Anfang
Die Regel prüft die Benennung von ARIA-Befehlen wie button, link und menuitem. Ob ein Name die richtige Handlung vermittelt, erfordert zusätzlich die Betrachtung der Anwendung.
Automatisch prüfbar
- Fehlende zugängliche Namen an den von der Regel erfassten ARIA-Befehlen erkennen.
- Die konkrete Fundstelle samt HTML und Seitenausschnitt zuordnen.
- Nach einer Namenskorrektur den Regelbefund am selben Element erneut auswerten.
Im Kontext zu entscheiden
- Die Benennung mit der tatsächlichen Handlung und dem sichtbaren Inhalt vergleichen.
- Fokus, Tastaturaktivierung und Fokusführung nach der Aktion prüfen.
- Dynamische Zustände und wiederholte Befehle im vollständigen Nutzerweg beurteilen.