Konfigurieren von axe DevTools Linter

Link to Konfigurieren von axe DevTools Linter copied to clipboard

Ein Referenzhandbuch zur Konfiguration von axe DevTools Linter

Not for use with personal data

Dieser Artikel bietet eine Referenz zu den Konfigurationsoptionen des axe DevTools Linter.

Überblick

Der REST-API-Endpunkt verwendet JSON zur Konfiguration und die axe Accessibility Linter-Erweiterung für VS Code, das JetBrains-Plugin und der axe DevTools Linter Connector verwenden YAML zur Konfiguration. In diesem Handbuch werden sowohl JSON- als auch YAML-Beispiele für axe DevTools Linter-Konfigurationen gezeigt.

Beispielkonfigurationen

Das folgende YAML-Beispiel zeigt eine einfache Konfiguration, die die Option rules zur Verwendung mit der axe Accessibility Linter-Erweiterung für VS Code, dem JetBrains-Plugin oder dem axe DevTools Linter Connector verwendet:

rules:
  html-has-lang: false

Das folgende Beispiel zeigt dieselbe Konfiguration als vollständiges Anforderungsobjekt mit der Option rules für den axe DevTools Linter REST-Dienst, wobei das eingebettete config Objekt hervorgehoben ist:

{
  "source": "<html></html>",
  "filename": "file.html",
  "config": {    "rules": {      "html-has-lang": false    },    "exclude": [],
    "tags": []
  }
}

In beiden Fällen bewirken diese Konfigurationen, dass axe DevTools Linter Zugänglichkeitsfehler ignoriert, wenn dem html Element ein lang Attribut fehlt. (Weitere Informationen finden Sie in der html-has-lang -Regel.)

note

Für alle JSON-Beispiele in diesem Artikel ist das config -Objekt enthalten, um einen Referenzspeicherort für die Konfiguration bereitzustellen.

In den folgenden Abschnitten werden die einzelnen Konfigurationsoptionen beschrieben und Beispiele für ihre Verwendung gegeben.

Mehrere Konfigurationsdateien

Die axe Accessibility Linter-Erweiterung für VS Code, das JetBrains-Plugin und der axe DevTools Linter Connector (bei Verwendung mit der Option --config ohne Parameter) durchsuchen das aktuelle Verzeichnis und die übergeordneten Verzeichnisse nach axe-linter.yml Konfigurationsdateien in Ihrem Projektverzeichnisbaum und verwenden die erste, die sie finden. Es empfiehlt sich, im Stammverzeichnis Ihres Projekts eine Konfigurationsdatei mit Ihrer Standardkonfiguration abzulegen und diese (falls nötig) durch Konfigurationsdateien in anderen Unterverzeichnissen zu überschreiben. Sie können auch eine Konfigurationsdatei in Ihrem Home-Verzeichnis platzieren, die standardmäßig verwendet wird, wenn in Ihrem Projekt keine Konfigurationsdateien vorhanden sind.

Die Schritte zum Auffinden von axe-linter.yml Konfigurationsdateien sind:

Verwenden Sie die Konfigurationsdatei im aktuellen Verzeichnis (dem Verzeichnis, in dem die Datei, die mit VS Code oder einer JetBrains IDE bearbeitet wird, oder das aktuelle Verzeichnis der Eingabeaufforderung mit dem axe DevTools Linter Connector).
Wenn in Schritt 1 keine Konfiguration gefunden wird, durchsuchen Sie die übergeordneten Verzeichnisse, bis eine Konfigurationsdatei gefunden wird. Halten Sie dabei bei Ihrem Home-Ordner an, wenn sich das Projekt in Ihrem Home-Verzeichnisbaum befindet, oder beim Stammverzeichnis, wenn es sich außerhalb Ihres Home-Ordners befindet. axe-linter.yml
Verwenden Sie eine Konfigurationsdatei, die sich in Ihrem Home-Verzeichnis befindet (auch wenn sich Ihr Projekt in einem Verzeichnis außerhalb Ihres Home-Ordners oder auf einem anderen Laufwerk unter Windows befindet). axe-linter.yml Dies sind beispielsweise die typischerweise verwendeten Dateien:
- /home/username/axe-linter.yml (Linux)
- /Benutzer/username/axe-linter.yml (macOS)
– C:\Benutzer\username\axe-linter.yml (Windows)

Die Suche wird beendet, wenn die erste axe-linter.yml Datei gefunden wurde.

Zusammenfassung der Konfiguration von axe DevTools Linter

Produkt	Konfigurationstyp	Beschreibung
Axe Accessibility Linter-Erweiterung für VS Code oder das JetBrains-Plugin	Eine oder mehrere YAML-Dateien benannte `axe-linter.yml`	Siehe Mehrere Konfigurationen.
axe Linter Connector	Eine oder mehrere YAML-Dateien benannte `axe-linter.yml`	Befolgt die Schritte unter Mehrere Konfigurationen bei Verwendung mit der `--config` Option ohne Parameter.
axe Linter Connector	Eine YAML-Datei mit dem Namen Dateiname	Bei Verwendung mit `--config` Dateiname.
axe Linter REST API	JSON-Konfigurationsobjekt	Siehe Das Konfigurationsobjekt.

Konfigurationsmöglichkeiten

`element`

Mit der Option element können Sie das ausgegebene Element basierend auf dem angegebenen Attributwert Ihrer Komponente ändern. Sie können beispielsweise eine benutzerdefinierte Komponente so konfigurieren, dass sie in bestimmten Fällen ein img -Element und in anderen Fällen ein button -Element ausgibt, um komplexere Anwendungsfälle zu ermöglichen.

Die folgende Beispielkonfiguration gibt an, dass das as -Attribut der my-button -Komponente das ausgegebene Element vom Standardwert button ändern kann:

YAML:

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

JSON:

{
  "config": {
    "global-components": {
      "my-button": {
        "element": "button",
        "attributes": [
          {
            "as": "<element>"
          }
        ]
      }
    }
  }
}

Das folgende Verwendungsbeispiel gibt ein img -Element anstelle des Standardelements button aus, da das Attribut as das Ausgabeelement angibt:

<my-button as="img"></my-button>

Das img Ausgabeelement wird anschließend überprüft und es wird festgestellt, dass ein alt Attribut fehlt.

`exclude`

Die Option exclude verhindert, dass übereinstimmende Dateien einer Überprüfung unterzogen werden. Sie können Platzhalter und Globs verwenden. Es wird hauptsächlich für die VS Code-Erweiterung oder das JetBrains-Plugin verwendet und vom REST-Endpunkt ignoriert.

exclude: *.tmp

`global-components`

Die global-components Konfigurationsoption weist axe DevTools Linter an, wie Ihre eigenen benutzerdefinierten Komponenten oder Komponenten aus Bibliotheken von Drittanbietern nativen HTML-Elementen zugeordnet werden sollen. So können Sie Ihre Komponenten linten, als wären sie native HTML-Elemente. Beispielsweise behandelt die folgende Konfiguration alle benutzerdefinierten DqButton Komponenten, als wären sie native HTML button Elemente. Dadurch wird jedes Attribut automatisch auf DqButton button abgebildet, sodass für alle DqButton Komponenten ein zugänglicher Name erforderlich ist.

YAML:

global-components:
  DqButton: button

JSON:

{
  "config": {
    "global-components" {
      "DqButton": "button"
    }
  }
}

Alternativ können Sie für Komponenten, die nicht alle Attribute nativen HTML-Komponenten zuordnen, die für die Barrierefreiheitskonformität erforderlichen Attribute mit der Option attributes auflisten. Sie können die von der Komponente unterstützten Attribute auflisten und Attribute umbenennen. Es gibt drei Sonderwerte:

– Der Wert „aria-*“ teilt axe DevTools Linter mit, dass alle Attribute, die mit aria- beginnen, unverändert dem nativen HTML-Element zugeordnet werden. Beachten Sie, dass der Wert mit einem Sternchen endet. – Der Wert <text> teilt axe DevTools Linter mit, dass eine Eigenschaft verwendet wird, um den Inhalt (den Wert zwischen den öffnenden und schließenden Tags) des nativen HTML-Elements festzulegen. – Der <element> -Wert teilt axe DevTools Linter mit, dass das ausgegebene Element den Wert dieses Attributs annehmen kann, wodurch Sie das ausgegebene Element abhängig vom Wert des angegebenen Attributs ändern können.

Das folgende YAML-Beispiel zeigt alle Werte, die mit global-components verwendet werden können:

global-components:
  DqButton:
    element: button
    # Ignore all attributes on <DqButton> except the following:
    attributes:
      - role # Map the role attribute from <DqButton /> to <button />
      - aria-* # Map all attributes starting with aria-
      - action: type # <DqButton action="submit" /> maps to <button type="submit" />
      - label: <text> #  <DqButton label="ABC" /> emits <button>ABC</button>
      - as: <element> # <DqButton as="img" /> emits <img> instead of <button>. (You don't have to use *as* for the attribute name.)

Eine entsprechende JSON-Version (innerhalb des config -Objekts) lautet wie folgt:

{
  "config": {
    "global-components": {
      "DqButton": {
        "element": "button",
        "attributes": [
          "role",
          "aria-*",
          {
            "action": "type"
          },
          {
            "label": "<text>"
          },
          {
            "as": "<element>"
          }
        ]
      }
    }
  }
}

Nur für die Barrierefreiheit relevante Attribute müssen in der attributes Liste enthalten sein. Bei Elementnamen muss die Groß-/Kleinschreibung beachtet werden. Camel Case, wie oben gezeigt, wird häufig mit .jsx-Dateien verwendet, aber auch Kebab Case (das in Vue, Angular und benutzerdefinierten HTML-Elementen verwendet wird) kann verwendet werden.

Exemplarische Vorgehensweisen zur Verwendung der benutzerdefinierten Komponentenzuordnung finden Sie unter Linting Custom Components.

`global-libraries`

Axe DevTools Linter bietet integrierte Unterstützung für mehrere beliebte Komponentenbibliotheken und Frameworks.

Die folgenden Bibliotheken werden derzeit unterstützt:

react-native
@mui/material
@deque/cauldron-react

Um die Lint-Prüfung von Bibliothekskomponenten zu aktivieren, fügen Sie den NPM-Paketnamen der Bibliothek zum global-libraries Array für YAML-Konfigurationsdateien hinzu:

global-libraries:
  - '@mui/material'
  - '@deque/cauldron-react'
  - react-native

note

Sie müssen @mui/material und @deque/cauldron-react in YAML in Anführungszeichen setzen, da @ als reserviertes Zeichen interpretiert wird.

Oder die entsprechende JSON-Konfiguration ist unten dargestellt:

{
  "config": {
    "global-libraries": [
      "@mui/material"
    ]
  }
}

Jede Komponente mit demselben Namen wie eine Komponente aus der globalen Bibliothek wird als diese Bibliothekskomponente behandelt. Dadurch können Komponenten erneut exportiert und neu deklariert werden, ohne dass ihre Zuordnung verloren geht.

Weitere Informationen finden Sie unter Vorkonfigurierte Komponentenbibliotheken.

`overrides`

Sie können die Konfiguration von axe DevTools Linter pro Datei ändern, indem Sie die Konfigurationsoption overrides verwenden. Mehrere overrides derselben Datei werden der Reihe nach aufgelöst. Das heißt, der letzte aufgeführte override hat die höchste Priorität.

Derzeit wird nur die linter Überschreibung unterstützt und dient zum Ändern des für die übereinstimmenden Dateien verwendeten Linters.

overrides:
  - files: # An array or single string of filename(s) or glob pattern(s) that match this override setting
      - vue/**/*.html
    linter: vue # Specify that all files that match the pattern should be linted as Vue
  - files: php/**/*.html
    linter: null # Disable axe-linter for these files

`rules`

Mit der Option rules in Ihrer Konfiguration können Sie Regeln einzeln zulassen oder verbieten:

rules:
  some-rule: false # turn off rule
  other-rule: true # turn on rule

Oder im config -Objekt in Ihrer JSON-REST-Anfrage:

{
  "config": {
    "rules": {
      "some-rule": false,
      "other-rule": true
    }
  }
}

Informationen zur Verwendung rules mit der REST-API finden Sie unter Die Eigenschaft „rules“. Wenn Sie den axe DevTools Linter-Connector verwenden möchten, sehen Sie in der [Konfigurationsdatei] rules nach.(axe-linter-connector#configuration-file) Die von axe DevTools Linter befolgten Regeln finden Sie unter Barrierefreiheitsregeln. Weitere Informationen zur Verwendung der Option zum Ausschließen von Regelsammlungen von der Verarbeitung finden Sie unten tags . tags

`tags`

Sie können Regeln als Gruppe basierend auf dem WCAG-Standard, mit dem sie verknüpft sind, mit der folgenden Option verbieten: tags

tags: # Disallow all rules other than WCAG 2.1 A, WCAG 2.1 AA, and best practices.
  - wcag21a
  - wcag21aa
  - best-practices

Siehe auch

– Eine Referenz zu den von axe DevTools Linter bereitgestellten REST-APIs finden Sie unter Die axe DevTools Linter REST-API-Referenz. – Anleitungen zum Erstellen von benutzerdefinierten Komponentenzuordnungen finden Sie unter Linting Custom Components. – Um die Erweiterung für VS Code herunterzuladen, siehe axe Accessibility Linter. – Weitere Informationen zum JetBrains-Plugin finden Sie unter Verwenden des Plugins mit JetBrains-IDEs.