Linting von benutzerdefinierten Komponenten mit dem Axe Accessibility Linter für VS Code oder JetBrains IDEs

Dieser Artikel zeigt, wie die Axe Accessibility Linter-Erweiterung für Visual Studio Code (VS Code) oder das Plugin für JetBrains konfiguriert wird, um Barrierefreiheitsfehler in Ihren benutzerdefinierten Komponenten zu finden.

Wenn Sie eine Übersicht über das Linting benutzerdefinierter Komponenten lesen möchten, siehe Linting benutzerdefinierter Komponenten.

Um diesen Leitfaden zu verwenden, sollten Sie Folgendes installiert haben:

Für Visual Studio Code:

• Visual Studio Code
• Die Axe Accessibility Linter-Erweiterung für VS Code

Für JetBrains IDEs:

• IntelliJ IDEA Ultimate

  oder

• WebStorm

• Das Axe Accessibility Linter-Plugin für JetBrains

Ein Beispiel für einen Barrierefreiheitsfehler

Wenn Sie die Erweiterung zur Analyse des Quellcodes verwenden, werden alle Barrierefreiheitsfehler in Ihrer IDE mit einer roten Wellenlinie angezeigt. Zum Beispiel zeigt der folgende HTML-Code die Verwendung des img-Elements ohne ein alt-Attribut, was ein Barrierefreiheitsfehler ist (gezeigt in VS Code).

<img src="path/to/image.jpg"/>

(Dies ist ein stark vereinfachtes Beispiel, um das Linting zu demonstrieren, und nicht ein tatsächliches Beispiel aus der Praxis.)

Die Erweiterung hebt die fehlerhafte Zeile hervor und zeigt ein Tooltip an, wenn Sie mit dem Mauszeiger über den Fehler fahren. Da dieses img-Element kein alt-Attribut hat, erhalten Sie einen Barrierefreiheitsfehler von der Erweiterung in Ihrer IDE (VS Code wird gezeigt):

Eine benutzerdefinierte Bildkomponente

Für dieses Beispiel hat ein Entwickler eine benutzerdefinierte Komponente namens custom-image erstellt. Das folgende Beispiel zeigt die Verwendung der benutzerdefinierten Komponente custom-image:

<custom-image path="images/image.jpg"></custom-image>

In diesem Beispiel erstellt die custom-image-Komponente ein img-Element mit einem path-Attribut (das durch die Implementierung der benutzerdefinierten Steuerung einem src-Attribut zugeordnet wird). Die Erweiterung zeigt keinen Fehler an, da es keine Zuordnung zwischen custom-image und img gibt, obwohl dem Ausgabeelement img ein alt-Attribut fehlt:

Zuordnung von custom-image zu img

Wenn Sie eine Zuordnung zwischen custom-image und img bereitstellen, kann der Axe DevTools Linter Ihre benutzerdefinierte Komponente als ein standardmäßiges HTML-Element abbilden und Barrierefreiheitsfehler finden. Sie können die Zuordnung mit der global-components-Konfigurationsoption in einer axe-linter.yml-Konfigurationsdatei angeben:

global-components:
  custom-image: img

Die Erweiterung hebt jetzt den Barrierefreiheitsfehler hervor und zeigt ein Tooltip an, wenn Sie den Cursor über den Fehler bewegen:

Sie können die gleiche Zuordnung wie oben auch mit entweder dieser Syntax angeben:

global-components:
  custom-image:
    element: img

Oder alternativ, indem Sie element als el abkürzen:

global-components:
  custom-image:
    el: img

Behebung des Barrierefreiheitsproblems

Sie können Ihrem custom-image ein alt-Attribut hinzufügen, um das Barrierefreiheitsproblem zu beheben:

<custom-image path="images/image.jpg" alt="alt text"></custom-image>

Es gibt nun keinen Fehler mehr, sodass Ihre IDE keine rote Wellenlinie mehr anzeigt (VS Code wird gezeigt):

Zuordnung eines alternative-text-Attributs

Wenn Ihre benutzerdefinierte Bildkomponente stattdessen ein anderes Attribut verwendet, um alternativen Text anzugeben, können Sie dieses Attribut in der Konfiguration angeben. Angenommen, Ihre custom-image-Komponente verwendet ein alternative-text-Attribut anstelle von alt, wie unten gezeigt:

<custom-image path="images/image.jpg" alternative-text="alt text"></custom-image>

In diesem Fall könnten Sie eine Zuordnung zwischen dem alternative-text-Attribut und dem alt-Attribut angeben, wie mit dem attributes-Array in einer axe-linter.yml-Datei unten gezeigt:

global-components:
  custom-image:
    element: img
    attributes:
      - alternative-text: alt

Diese global-components-Konfiguration unterscheidet sich leicht von der früheren Zuordnung einer benutzerdefinierten Komponente zu einem HTML-Element. Mit nur Elementen verwenden Sie eine Zuordnung von einem Schlüssel (custom-image) zu einem Wert (img). Mit der Einbeziehung des attributes-Arrays müssen Sie jetzt die element- (oder el-) Eigenschaft verwenden, um das ausgegebene HTML-Element anzugeben.

Diese Änderung behebt den Fehler, und es wird keine rote Wellenlinie in Ihrer IDE angezeigt (VS Code wird gezeigt).

Sie können attributes auch als attrs abkürzen:

global-components:
  custom-image:
    element: img
    attrs:
      - alternative-text: alt

Spezielle Attributwerte: <text> und aria-*

Angenommen, Sie verwenden eine custom-button-Komponente wie folgt:

<custom-button aria-controls="expand-region" aria-expanded="false" aria-colindex="1" message="Show Region"></custom-button>

(Der benutzerdefinierte Button wird mittels JavaScript und CSS, das hier nicht enthalten ist, ein div ein- und ausblenden.)

Es gibt zwei Probleme bei dieser Verwendung:

1. Wenn Sie diese custom-button-Komponente direkt auf ein button-Element abbilden, gibt es keinen Textinhalt, der auf dem Button angezeigt werden kann. Die Absicht des Komponentenautors ist jedoch, dass das message-Attribut als Textinhalt verwendet werden sollte: <button> Wert des message-Attributs </button>
2. Das ausgegebene button-Element hat eine implizite Rolle von button, daher ist das aria-colindex-Attribut falsch und sollte entfernt werden.

Wie üblich führt dieses HTML nicht zu einem Fehler, weil es keine Zuordnung zwischen custom-button und button gibt. Wenn Sie jedoch eine einfache Zuordnung zwischen custom-button und button erstellen, wie unten gezeigt:

global-components:
  custom-button: button

Sie erhalten zwei Fehler von Ihrer IDE (VS Code wird angezeigt):

Der spezielle <text>-Wert

Um das erste Problem zu beheben (der Textinhalt für das button-Element stammt aus einem message-Attribut, das oben in Ihrem IDE-Tooltip als Button-Name identifiziert wird), können Sie den speziellen <text>-Wert verwenden, der ein Attribut auf den Textinhalt des ausgegebenen Elements abbildet. In diesem Fall sollte der Text des message-Attributs auf den Textinhalt des ausgegebenen button-Elements kopiert werden.

Um die Erweiterung zu konfigurieren, dass das message-Attribut als Textinhalt für das HTML-button-Element betrachtet werden soll, können Sie den speziellen <text>-Wert in einer axe-linter.yml-Konfigurationsdatei verwenden:

global-components:
  custom-button:
    element: button
    attributes:
      - message: <text>

Weil Sie das message-Attribut als <text> definiert haben, haben Sie der Erweiterung mitgeteilt, dass dieses Attribut den Textinhalt des HTML-button-Elements mit dem Wert des message-Attributs ersetzen soll.

Unglücklicherweise wurde durch die Verwendung des attributes-Arrays nur das message-Attribut an das ausgegebene button-Element weitergegeben; alle Attribute, die nicht im attributes-Array enthalten sind, werden nicht weitergegeben. Das bedeutet, dass die falsche aria-colindex nicht von der Erweiterung erkannt wurde.

Verwendung von aria-*

Sie können den speziellen aria-*-Wert verwenden, um alle ARIA-Attribute zu übergeben, wie unten gezeigt:

global-components:
  custom-button:
    element: button
    attributes:
      - message: <text>
      - aria-*

Dieser Fehler tritt auf, weil das button-Element implizit role="button" hat und die Verwendung von aria-colindex mit Buttons ungültig ist. Mit aria-* werden alle ARIA-Attribute auf das ausgegebene Element kopiert; dies umfasst auch das Kopieren des ungültigen aria-colindex-Attributs.

<element>

Bei komplexen Komponenten möchten Sie möglicherweise in bestimmten Fällen ein anderes HTML-Element als das Standard-Element ausgeben. Zum Beispiel könnten Sie eine Button-Komponente haben, die sich normalerweise wie ein Button verhält und in anderen Zuständen wie ein Platzhalterbild. Der <element>-Wert ermöglicht es Ihnen, ein Attribut an Ihrer benutzerdefinierten Komponente zu spezifizieren, das das ausgegebene Element bestimmt.

global-components:
  my-button:
    element: button
    attributes:
      - use: <element>

In diesem Fall zeigt das use-Attribut auf der my-button-Komponente an, welches Element ausgegeben werden soll. Da das ausgegebene img-Element kein alt-Attribut enthält, wird ein Fehler ausgegeben:

Alle Attribute implizit übergeben

Hätten Sie nur die Elementzuordnung verwendet (bei der die Zuordnung das attributes-Array nicht verwendet), würden alle Attribute standardmäßig auf das button-Element kopiert werden. Die Konfiguration für diesen Fall wurde zuvor gezeigt:

global-components:
  custom-button: button

Zusammen mit dem Fehler, der in Ihrer IDE angezeigt wird (VS Code wird hier angezeigt):

Das obige Beispiel zeigt, dass ein praktischer erster Schritt beim Beginn der Prüfung benutzerdefinierter Komponenten wäre, mit einer Elementzuordnung zu beginnen (dadurch werden alle Attribute auf das ausgegebene, standardisierte HTML-Element kopiert) und dann zu sehen, welche Attribute der Konfiguration hinzugefügt werden müssen:

1. Ob eines der Attribute der benutzerdefinierten Komponente auf andere Attribute abgebildet werden sollte.
2. Ob Sie <text> oder aria-* verwenden müssen.

Standardattribute

Standardattribute ermöglichen es Ihnen, Werte für Attribute in Ihrer Konfigurationsdatei festzulegen, anstatt ein Attribut auf ein anderes abzubilden. Zum Beispiel zeigt die folgende Beispielkonfiguration eine custom-menu-Komponente, die einem li-Element mit einem role von Menü zugeordnet ist:

global-components:
  custom-menu:
    element: li
    attributes:
      - role:
          name: null
          default: menu

Da das role-Attribut einen Standardwert von Menü hat, der in der Konfigurationsdatei festgelegt ist, müssen Benutzer kein role-Attribut angeben, wenn sie die custom-menu-Komponente in ihrem Code verwenden. Das bedeutet, dass die Implementierung Ihrer benutzerdefinierten Komponente diese Attribute auf dem Ausgabeelement erstellt und deren Werte festlegt, anstatt dass Benutzer sie beim Verwenden Ihrer Komponente angeben müssen.

Optional wird der name-Wert in der Konfiguration auf null gesetzt, was dazu führt, dass Axe DevTools Linter alle role-Attribute ignoriert, die Benutzer auf custom-menu im geprüften Code angegeben haben.

Siehe auch

Konfiguration des Axe DevTools Linter

Benutzerdefinierte Komponenten und das REST-Endpunkt

Vorkonfigurierte Komponentenbibliotheken

Axe DevTools Linter für React Native

Analyse von Verstößen bei benutzerdefinierten Komponenten in CI/CD-Berichten