Lintieren benutzerdefinierter Komponenten mit dem axe DevTools Linter für VS Code oder JetBrains IDEs

Dieser Artikel zeigt, wie Sie die Erweiterung axe Accessibility Linter für Visual Studio Code (VS Code) oder das Plug-In für JetBrains konfigurieren, um Barrierefreiheitsfehler in Ihren benutzerdefinierten Komponenten zu finden.

Eine Übersicht zum Linting benutzerdefinierter Komponenten finden Sie unter Linting benutzerdefinierter Komponenten.

Um diese exemplarische Vorgehensweise verwenden zu können, sollte Folgendes installiert sein:

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 zum Lint-Testen des Quellcodes verwenden, werden alle Zugänglichkeitsfehler mit einer roten Wellenlinie in Ihrer IDE angezeigt. Beispielsweise zeigt das folgende HTML die Verwendung des Elements img ohne Attribut alt , was einen Zugänglichkeitsfehler darstellt (wird in VS Code angezeigt).

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

(Dies ist eher ein vereinfachtes Beispiel zur Demonstration des Lintings als ein tatsächliches Beispiel aus der Praxis.)

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

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 custom-image Komponente:

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

Für dieses Beispiel erstellt die custom-image Komponente ein img Element mit einem path Attribut (das durch die Implementierung des benutzerdefinierten Steuerelements einem src Attribut zugeordnet wird). Die Erweiterung zeigt keinen Fehler an, da die Erweiterung keine Zuordnung zwischen custom-image und img hat, obwohl dem Ausgabeelement img ein alt Attribut fehlt:

Zuordnung custom-image zu img

Wenn Sie eine Zuordnung zwischen custom-image und img angeben, kann axe DevTools Linter Ihre benutzerdefinierte Komponente als Standard-HTML-Element zuordnen und Barrierefreiheitsfehler lokalisieren. Sie können die Zuordnung mithilfe der global-components Konfigurationsoption in einer axe-linter.yml Konfigurationsdatei angeben:

global-components:
  custom-image: img

Die Erweiterung hebt nun den Zugänglichkeitsfehler hervor und bietet einen Tooltip, wenn Sie mit der Maus über den Fehler fahren:

Sie können dieselbe Zuordnung wie oben auch mit einer der folgenden Syntaxen angeben:

global-components:
  custom-image:
    element: img

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

global-components:
  custom-image:
    el: img

Behebung des Zugänglichkeitsproblems

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

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

Es liegt kein Fehler mehr vor, sodass Ihre IDE die rote Wellenlinie nicht mehr anzeigt (hier als Beispiel VS Code):

Zuordnung eines alternative-text Attributs

Wenn Ihre benutzerdefinierte Bildkomponente stattdessen ein anderes Attribut zur Angabe von alternativem Text verwendet, 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 unten mit dem attributes Array in einer axe-linter.yml Datei gezeigt:

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

Diese global-components Konfiguration unterscheidet sich geringfügig von der früheren Zuordnung einer benutzerdefinierten Komponente zu einem HTML-Element. Bei ausschließlichen 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 Eigenschaft element (oder el) verwenden, um das ausgegebene HTML-Element anzugeben.

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

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

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>

(Die benutzerdefinierte Schaltfläche wird mithilfe von JavaScript und CSS, das hier nicht enthalten ist, ein div ausblenden und anzeigen.)

Diese Verwendung bringt zwei Probleme mit sich:

1. Wenn Sie diese custom-button Komponente direkt einem button Element zuordnen, wird auf der Schaltfläche kein Textinhalt angezeigt. Die Absicht des Komponentenautors besteht jedoch darin, dass das message Attribut als Textinhalt verwendet werden soll: <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.

Standardmäßig führt dieses HTML nicht zu einem Fehler, da keine Zuordnung zwischen custom-button und button besteht. 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 Besonderer <text> Wert

Um das erste Problem zu lösen (Textinhalt für das button Element stammt von einem message Attribut, das oben als Schaltflächenname im Tooltip Ihrer IDE identifiziert wurde), können Sie den speziellen <text> Wert verwenden, der ein Attribut dem Textinhalt des ausgegebenen Elements zuordnet. In diesem Fall sollte der Text des message Attributs in den Textinhalt des ausgegebenen button Elements kopiert werden.

Um die Erweiterung so zu konfigurieren, dass das message -Attribut als Textinhalt für das HTML- button -Element berücksichtigt 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>

Da Sie das message Attribut als <text> definiert haben, haben Sie der Erweiterung mitgeteilt, dass dieses Attribut als Ersetzung des Textinhalts des HTML- button Elements durch den Wert des message Attributs betrachtet werden soll.

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

Verwenden von aria-*

Sie können den speziellen Wert aria-* 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 ein implizites role="button" Element hat und die Verwendung von aria-colindex bei Schaltflächen ungültig ist. Mit dem Attribut „aria-*, all ARIA attributes are copied to the emitted element; this includes copying the invalid aria-colindex“.

<element>

Bei komplexen Komponenten möchten Sie in bestimmten Fällen möglicherweise ein anderes HTML-Element als das Standardelement ausgeben. Sie verfügen beispielsweise möglicherweise über eine Schaltflächenkomponente, die sich normalerweise wie eine Schaltfläche und in anderen Zuständen wie ein Platzhalterbild verhält. Mit dem <element> Wert können Sie ein Attribut für Ihre benutzerdefinierte Komponente angeben, das das ausgegebene Element bestimmt.

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

In diesem Fall gibt das use Attribut der my-button Komponente das auszugebende Element an. Da das ausgegebene img Element kein alt Attribut enthält, erhalten Sie eine Fehlermeldung:

Implizite Übergabe aller Attribute

Wenn Sie nur die Elementzuordnung verwendet hätten (wobei die Zuordnung das attributes -Array nicht verwendet), würden alle Attribute standardmäßig in das button -Element kopiert. Die Konfiguration für diesen Fall wurde bereits früher gezeigt:

global-components:
  custom-button: button

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

Das obige Beispiel zeigt, dass ein praktischer erster Schritt beim Lintieren benutzerdefinierter Komponenten darin besteht, mit einer Elementzuordnung zu beginnen (wobei alle Attribute in das ausgegebene Standard-HTML-Element kopiert werden) und dann zu prüfen, welche Attribute der Konfiguration hinzugefügt werden müssen:

1. Ob irgendwelche Attribute der benutzerdefinierten Komponente anderen Attributen zugeordnet werden sollen.
2. Ob Sie <text> oder aria-* verwenden müssen.

Standardattribute

Mit Standardattributen können Sie Werte für Attribute in Ihrer Konfigurationsdatei festlegen, anstatt ein Attribut einem anderen zuzuordnen. Beispielsweise 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 Attribut role den Standardwert Menü hat, der in der Konfigurationsdatei festgelegt ist, müssen Benutzer kein Attribut role angeben, wenn sie die Komponente custom-menu in ihrem Code verwenden. Dies hat zur Folge, dass die Implementierung Ihrer benutzerdefinierten Komponente diese Attribute im Ausgabeelement erstellt und ihre Werte festlegt, anstatt dass Benutzer diese festlegen müssen, wenn sie Ihre Komponente verwenden.

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 im geprüften Code angegeben haben. custom-menu

Siehe auch

axe DevTools Linter konfigurieren

Benutzerdefinierte Komponenten und der REST-Endpunkt

Vorkonfigurierte Komponentenbibliotheken

axe DevTools Linter für React Native