Konfiguration von Axe DevTools Linter

This page is not available in the language you requested. You have been redirected to the English version of the page.

Link to this page copied to clipboard

Ein Referenzhandbuch zur Konfiguration von Axe DevTools Linter

Not for use with personal data

Dieser Artikel bietet eine Referenz für die Konfigurationsoptionen des Axe DevTools Linter.

Überblick

Das REST-API-Endpunkt verwendet JSON für die Konfiguration, und die Axe Accessibility Linter-Erweiterung für VS Code, das JetBrains-Plugin, und der Axe DevTools Linter Connector verwenden YAML für die Konfiguration. Sowohl JSON- als auch YAML-Beispiele für die Konfigurationen von Axe DevTools Linter sind in diesem Leitfaden dargestellt.

Beispielkonfigurationen

Das folgende YAML-Beispiel zeigt eine einfache Konfiguration, die die rules -Option für die 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 die gleiche Konfiguration als vollständiges Anforderungsobjekt mit der rules -Option für den Axe DevTools Linter REST-Dienst mit seinem eingebetteten config -Objekt hervorgehoben:

{
  "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 Barrierefreiheitsfehler ignoriert, wenn das html -Element ein lang -Attribut fehlt. (Siehe die html-has-lang -Regel für weitere Informationen.)

note

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

Die folgenden Abschnitte beschreiben jede Konfigurationsoption und geben Beispiele für deren Verwendung.

Suchreihenfolge der Konfigurationsdateien

Die Axe Accessibility Linter-Erweiterung für VS Code, das JetBrains-Plugin und der Axe DevTools Linter Connector (wenn verwendet mit der --config -Option ohne Parameter) durchsuchen das aktuelle Verzeichnis und übergeordnete Verzeichnisse nach einer axe-linter.yml -Konfigurationsdatei in Ihrem Projektverzeichnisbaum und verwenden die erste, die sie finden. Eine nützliche Praxis besteht darin, eine Konfigurationsdatei im Stammverzeichnis Ihres Projekts zu platzieren, die Ihre Standardkonfiguration enthält, und sie bei Bedarf mit Konfigurationsdateien in verschiedenen Unterverzeichnissen zu ersetzen. Sie können auch eine Konfigurationsdatei in Ihrem Home-Verzeichnis platzieren, die standardmäßig verwendet wird, wenn keine Konfigurationsdateien in Ihrem Projekt vorhanden sind.

important

Konfigurationsdateien werden nicht zusammengeführt. Die erste gefundene wird verwendet.

Die Schritte zur Suche nach der zu verwendenden axe-linter.yml -Konfigurationsdatei sind:

Verwenden Sie die Konfigurationsdatei im aktuellen Verzeichnis (das Verzeichnis, das die Datei enthält, die mit VS Code, einer JetBrains-IDE oder das aktuelle Verzeichnis im Befehlsfenster mit Axe DevTools Linter Connector bearbeitet wird).
Wenn in Schritt 1 keine Konfiguration gefunden wird, durchsuchen Sie übergeordnete Verzeichnisse, bis eine axe-linter.yml -Konfigurationsdatei gefunden wird, und stoppen Sie bei Ihrem Home-Ordner, wenn sich das Projekt im Verzeichnisbaum Ihres Home-Verzeichnisses befindet, oder im Stammordner, wenn es außerhalb Ihres Home-Verzeichnisses liegt.
Verwenden Sie eine axe-linter.yml -Konfigurationsdatei in Ihrem Home-Verzeichnis (auch wenn Ihr Projekt sich in einem Verzeichnis außerhalb Ihres Home-Ordners oder auf einem anderen Laufwerk unter Windows befindet). Zum Beispiel werden typischerweise diese Dateien verwendet:
- /home/Benutzername/axe-linter.yml (Linux)
- /Users/Benutzername/axe-linter.yml (macOS)
- C:\Users\Benutzername\axe-linter.yml (Windows)

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

Zusammenfassung der Konfiguration von Axe DevTools Linter

Produkt	Art der Konfiguration	Beschreibung
Axe Accessibility Linter-Erweiterung für VS Code oder das JetBrains-Plugin	Eine YAML-Datei namens `axe-linter.yml`	Siehe Suchreihenfolge der Konfigurationsdatei.
Axe Linter Connector	Eine YAML-Datei namens `axe-linter.yml`	Befolgt die Schritte in Suchreihenfolge der Konfigurationsdatei wenn mit der `--config` Option ohne Parameter verwendet.
Axe Linter Connector	Eine YAML-Datei namens Dateiname	Wenn verwendet mit `--config` Dateiname.
Axe Linter REST API	JSON-Konfigurationsobjekt	Siehe Das Konfigurationsobjekt.

Konfigurationsoptionen

`element`

Die element Option ermöglicht es Ihnen, das ausgegebene Element basierend auf dem angegebenen Attributwert Ihres Bauteils zu ändern. Beispielsweise könnte ein benutzerdefiniertes Bauteil ein img Element in bestimmten Fällen und ein button Element in anderen Fällen ausgeben, was komplexere Anwendungsfälle ermöglicht.

Die folgende Konfiguration gibt an, dass das as Attribut auf dem my-button Bauteil das ausgegebene Element von dem Standard von button:

YAML:

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

JSON:

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

Das folgende Anwendungsbeispiel gibt ein img Element anstelle des Standard- button Elements aus, weil das as Attribut das Ausgabeelement angibt:

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

Das Ausgabe- img Element wird dann überprüft und als fehlerhaft ohne ein alt Attribut erkannt.

`exclude`

Die exclude Option verhindert, dass übereinstimmende Dateien überprüft werden. Sie können Platzhalter und Globs verwenden. Dies 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 Sie Ihre eigenen benutzerdefinierten Bauteile oder Bauteile aus Drittanbieterbibliotheken auf native HTML-Elemente abbilden, sodass Sie Ihre Bauteile überprüfen können, als wären sie native HTML-Elemente. Zum Beispiel behandelt die folgende Konfiguration alle benutzerdefinierten DqButton Bauteile, als wären sie native HTML- button Elemente. Dies ordnet automatisch jedes Attribut auf DqButton zu button, was einen zugänglichen Namen für alle DqButton Bauteile erfordert.

YAML:

global-components:
  DqButton: button

JSON:

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

Alternativ, für Komponenten, die nicht alle Attribute auf native HTML-Komponenten abbilden, können Sie die Attribute, die für die Barrierefreiheit erforderlich sind, mithilfe der attributes Option auflisten. Sie können Attribute auflisten, die die Komponente unterstützt, sowie Attribute umbenennen. Es gibt drei spezielle Werte:

Der aria-* Wert teilt Axe DevTools Linter mit, dass alle Attribute, die mit aria- beginnen, unverändert auf das native HTML-Element abgebildet werden. Beachten Sie, dass der Wert mit einem Sternchen endet.
Der <text> Wert 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 ausgesendete Element den Wert dieses Attributs übernehmen kann, was es Ihnen ermöglicht, das ausgesendete Element je nach Wert des angegebenen Attributs zu ändern.

Das folgende YAML-Beispiel zeigt alle Werte, die mit global-componentsverwendet 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.)

Ein äquivalentes JSON-Beispiel (im config Objekt) ist 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. Elementnamen sind case-sensitiv. Camel Case, wie oben gezeigt, wird häufig mit .jsx-Dateien verwendet, jedoch kann auch Kebab Case (welches in Vue, Angular und benutzerdefinierten HTML-Elementen verwendet wird) verwendet werden.

Für Anleitungen, wie Sie die benutzerdefinierte Komponentenabbildung verwenden, siehe Linten benutzerdefinierter Komponenten.

`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 das Linten von Bibliothekskomponenten zu aktivieren, fügen Sie den NPM-Paketnamen der Bibliothek der 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 zitieren, da @ als reserviertes Zeichen interpretiert wird.

Oder die äquivalente JSON-Konfiguration wird unten gezeigt:

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

Jede Komponente mit dem gleichen Namen wie eine Komponente aus der globalen Bibliothek wird als diese Bibliothekskomponente behandelt, was das erneute Exportieren und Umdeklarieren von Komponenten ohne Verlust ihrer Zuordnung ermöglicht.

Für weitere Informationen siehe Vorkonfigurierte Komponentenbibliotheken.

`overrides`

Sie können ändern, wie Axe DevTools Linter dateiweise konfiguriert wird, indem Sie die overrides Konfigurationsoption verwenden. Mehrfaches Überschreiben in derselben Datei wird in der angegebenen Reihenfolge aufgelöst. Das bedeutet, dass das letzte aufgeführte Überschreiben die höchste Priorität hat.

Derzeit wird nur die linter Überschreibung unterstützt und wird verwendet, um den für die übereinstimmenden Dateien verwendeten Linter zu ändern.

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`

Sie können Regeln individuell mit der rules Option in Ihrer Konfiguration erlauben oder verbieten. Jede Regel kann auf true (aktiviert, als Fehler gemeldet — die Standardeinstellung), false (deaktiviert) oder warn (aktiviert, als Warnung gemeldet) gesetzt werden:

rules:
  some-rule: false   # turn off rule
  other-rule: true   # turn on rule (default)
  color-contrast: warn  # report violations as warnings instead of errors

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

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

Für Informationen zur Verwendung von rules mit der REST-API, siehe Die rules-Eigenschaft. Wenn Sie rules mit dem Axe DevTools Linter-Konnektor verwenden möchten, siehe Konfigurationsdatei. Um die Regeln zu sehen, die Axe DevTools Linter befolgt, siehe Barrierefreiheitsregeln. Siehe Tags unten für weitere Informationen zur Verwendung der tags Option zum Ausschließen von Regelgruppen aus der Verarbeitung.

Um Regeln für bestimmte Zeilen in einer Quelldatei zu unterdrücken, ohne diese Konfigurationsdatei zu ändern, siehe Unterdrücken von Linting-Regeln mit Inline-Direktiven.

`tags`

Sie können Regeln als Gruppe basierend auf dem WCAG-Standard, mit dem sie verbunden sind, mithilfe der tags Option nicht zulassen:

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

Siehe auch

Für eine Referenz der von Axe DevTools Linter bereitgestellten REST-APIs siehe Die Axe DevTools Linter REST-API-Referenz.
Für Anleitungen zum Erstellen benutzerdefinierter Komponentenzuordnungen siehe Linting benutzerdefinierter Komponenten.
Um die Erweiterung für VS Code herunterzuladen, siehe Axe Accessibility Linter.
Für weitere Informationen über das JetBrains-Plugin, siehe Verwendung des Plugins mit JetBrains-IDEs.