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

Der REST-API-Endpunkt verwendet JSON zur Konfiguration, und der Axe Accessibility Linter-Erweiterung für VS Code, das JetBrains-Plugin und der Axe DevTools Linter Connector verwenden YAML zur Konfiguration. Sowohl JSON- als auch YAML-Beispiele für Axe DevTools Linter-Konfigurationen werden in diesem Leitfaden gezeigt.

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 nutzt:

rules:
  html-has-lang: false

Das folgende Beispiel zeigt dieselbe Konfiguration als komplettes Anforderungsobjekt mit der rules-Option für den Axe DevTools Linter REST-Dienst mit seinem hervorgehobenen eingebetteten config-Objekt:

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

In beiden Fällen führen diese Konfigurationen dazu, dass der 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 eine Referenzposition für die Konfiguration bereitzustellen.

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

Suchreihenfolge der Konfigurationsdatei

Die Axe Accessibility Linter-Erweiterung für VS Code, das JetBrains-Plugin und der Axe DevTools Linter Connector (wenn mit der --config-Option ohne Parameter verwendet) durchsuchen das aktuelle Verzeichnis und übergeordnete Verzeichnisse nach einer axe-linter.yml-Konfigurationsdatei in Ihrer Projektverzeichnisstruktur und verwenden die erste, die sie finden. Eine nützliche Praxis ist es, eine Konfigurationsdatei im Hauptverzeichnis 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

Die durch diese Suche gefundenen Konfigurationsdateien werden nicht zusammengeführt. Nur die erste gefundene Datei wird verwendet. Um Einstellungen aus mehr als einer Datei zu kombinieren, soll die Konfigurationsdatei mit der extends-Option von den anderen erben.

Die Schritte zum Auffinden 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 die übergeordneten Verzeichnisse, bis eine axe-linter.yml-Konfigurationsdatei gefunden wird. Stoppen Sie in Ihrem Home-Ordner, wenn sich das Projekt in Ihrem Home-Verzeichnisbaum befindet, oder im Root-Verzeichnis, wenn es sich außerhalb Ihres Home-Ordners befindet.
Verwenden Sie eine axe-linter.yml-Konfigurationsdatei in Ihrem Home-Verzeichnis (auch wenn sich Ihr Projekt in einem Verzeichnis außerhalb Ihres Home-Ordners oder auf einem anderen Laufwerk unter Windows befindet). Beispielsweise sind dies die typischen verwendeten Dateien:
- /home/Benutzername/axe-linter.yml (Linux)
- /Users/Benutzername/axe-linter.yml (macOS)
- C:\Users\Benutzername\axe-linter.yml (Windows)

Die Suche wird beendet, sobald 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 emittierte Element basierend auf dem angegebenen Attributwert Ihrer Komponente zu ändern. Beispielsweise könnten Sie eine benutzerdefinierte Komponente haben, die in bestimmten Fällen ein img-Element und in anderen Fällen ein button-Element erzeugt, was komplexere Anwendungsfälle ermöglicht.

Die folgende Konfiguration legt fest, dass das as-Attribut auf der my-button-Komponente das emittierte 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>"
          }
        ]
      }
    }
  }
}

Die folgende Verwendung gibt ein img-Element anstelle des standardmäßigen button-Elements aus, weil das as-Attribut das Ausgabeelement angibt:

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

Das Ausgabe-img-Element wird dann geprüft und es wird festgestellt, dass ihm ein alt-Attribut fehlt.

`exclude`

Die exclude-Option verhindert, dass übereinstimmende Dateien geprüft werden. Sie können Wildcards und Globs verwenden. Ihre Verwendung ist hauptsächlich für die VS Code-Erweiterung oder das JetBrains-Plugin gedacht und wird vom REST-Endpunkt ignoriert.

exclude: *.tmp

`enterpriseId`

Das optionale enterpriseId-Feld akzeptiert einen String, der an Nutzungsanalyse-Ereignisse für Unternehmenskontenzuordnung angehängt wird. Die meisten Benutzer müssen diesen Wert nicht festlegen; er kann von Ihrem Deque-Kundenbetreuer angefordert werden. Dieses Feld wird bei Vor-Ort-Bereitstellungen ignoriert.

enterpriseId: 'acme-corp'

`extends`

Die extends-Option ermöglicht es einer axe-linter.yml-Datei, ihre Einstellungen von einer oder mehreren übergeordneten Konfigurationsdateien zu erben, sodass eine gemeinsame Basis an einem Ort gespeichert werden kann, anstatt in jedes Projekt kopiert zu werden. Sie akzeptiert entweder einen einzelnen Dateipfad oder ein Array von Dateipfaden und ist in Version 4.13.0 und höher der Axe Accessibility Linter-Erweiterung für VS Code, des JetBrains-Plugins und des Axe DevTools Linter Connectors verfügbar.

extends: ./axe-linter.base.yml
rules:
  color-contrast: warn

Um von mehr als einer Datei zu erben, verwenden Sie ein Array:

extends:
  - ./axe-linter.base.yml
  - ../shared/team-rules.yml

Pfade werden relativ zu der Datei aufgelöst, die die extends-Option enthält, nicht relativ zu dem Verzeichnis, von dem aus Sie den Linter gestartet haben. Absolute Pfade werden ebenfalls akzeptiert. Übergeordnete Dateien müssen nicht axe-linter.yml genannt werden, und eine übergeordnete Datei kann selbst extends verwenden, um von einer anderen Datei zu erben.

note

Reine Paketnamen (wie @my-org/axe-linter-config) und Remote-URLs (wie https://example.com/axe-linter.yml) werden nicht unterstützt. Es können nur relative und absolute Dateipfade verwendet werden.

Wie geerbte Einstellungen kombiniert werden

Übergeordnete Dateien werden von links nach rechts gelesen und Ihre eigene Konfiguration wird zuletzt angewendet, sodass sie bei Konflikten gewinnt. Jede Option wird wie folgt kombiniert:

Option	Wie sie kombiniert wird
`rules`	Nach Regel-ID zusammengeführt, und Ihr Wert gewinnt. Da jede Regel standardmäßig als Fehler aktiviert und gemeldet wird (siehe `rules`), verwendet eine übergeordnete Datei diese Option, um Regeln zu deaktivieren oder sie als Warnungen zu melden, und Ihre eigene Konfiguration kann jede dieser Entscheidungen ändern, einschließlich der Rücksetzung einer Regel zu `true`, um die standardmäßige Fehlerberichterstattung wiederherzustellen.
`tags`	Mit den Werten des übergeordneten Elements kombiniert, wobei Duplikate entfernt werden.
`exclude`	Mit den Werten des übergeordneten Elements kombiniert, wobei Duplikate entfernt werden.
`global-libraries`	Mit den Werten des übergeordneten Elements kombiniert, wobei Duplikate entfernt werden.
`global-components`	Nach Komponentennamen zusammengeführt. Ein Eintrag in Ihrer Konfiguration ersetzt einen übergeordneten Eintrag mit demselben Namen vollständig, anstatt in ihn integriert zu werden. Das Wiederholen eines Komponentennamens bedeutet also, alle Einstellungen dieser Komponente zu wiederholen.
`overrides`	Kombiniert, mit den Einträgen des übergeordneten Elements zuerst und anschließend Ihren eigenen.
Jede andere Option, wie `enterpriseId`	Ihr Wert gewinnt, und der übergeordnete Wert liefert die Werte für jede von Ihnen ausgelassene Option.

important

Wenn eine übergeordnete Datei enterpriseId setzt und Ihre eigene Konfiguration nicht, wird die Nutzung Ihres Projekts unter der Enterprise-ID des übergeordneten Elements gezählt. Setzen Sie enterpriseId in Ihrer eigenen Konfiguration, wenn Sie einen anderen Wert benötigen.

Grenzen und Fehlermanagement

Eine Konfigurationsdatei kann sich selbst weder direkt noch über eine Kette von übergeordneten Dateien erweitern. Ketten sind auf 10 Ebenen beschränkt, und eine einzige Konfiguration kann insgesamt von maximal 100 übergeordneten Dateien erben.

Wenn eine übergeordnete Datei fehlt, kein gültiges YAML ist oder eine ungültige Einstellung enthält, meldet Axe DevTools Linter einen Fehler, der die Datei benennt, die das Problem verursacht hat. In VS Code und JetBrains IDEs erscheint eine Benachrichtigung und das Linting wird mit der Standardkonfiguration fortgesetzt. Axe DevTools Linter Connector meldet den Fehler und beendet sich mit dem Exit-Code 3 (siehe Exit-Codes).

`global-components`

Die global-components-Konfigurationsoption gibt dem Axe DevTools Linter an, wie Ihre eigenen benutzerdefinierten Komponenten oder Komponenten von Drittanbieterbibliotheken in native HTML-Elemente abgebildet werden, sodass Sie Ihre Komponenten so prüfen können, als wären sie native HTML-Elemente. Zum Beispiel behandelt die folgende Konfiguration alle benutzerdefinierten DqButton-Komponenten, als wären sie native HTML-button-Elemente. Dies weist automatisch jedes Attribut auf DqButton button zu, wodurch ein zugänglicher Name für alle DqButton-Komponenten erforderlich wird.

YAML:

global-components:
  DqButton: button

JSON:

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

Alternativ können Sie für Komponenten, die nicht alle Attribute auf native HTML-Komponenten abbilden, die für die Barrierefreiheitskonformität erforderlichen Attribute mit der attributes-Option auflisten. Sie können die unterstützten Attribute der Komponente auflisten und auch Attribute umbenennen. Es gibt drei spezielle Werte:

Der aria-*-Wert teilt dem 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 Stern endet.
Der <text>-Wert teilt dem Axe DevTools Linter mit, dass eine Eigenschaft verwendet wird, um den Inhalt (den Wert zwischen dem offenen und geschlossenen Tag) des nativen HTML-Elements festzulegen.
Der <element>-Wert teilt dem Axe DevTools Linter mit, dass das emittierte Element den Wert dieses Attributs annehmen kann, was es ermöglicht, das emittierte Element abhängig vom Wert des angegebenen Attributs zu ändern.

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 gleichwertige JSON-Version (innerhalb des config-Objekts) sieht wie folgt aus:

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

Nur Attribute, die für die Barrierefreiheit relevant sind, müssen in der attributes-Liste stehen. Elementnamen unterscheiden zwischen Groß- und Kleinschreibung. CamelCase, wie oben gezeigt, wird häufig mit .jsx-Dateien verwendet, aber Kebab-Case (das in Vue, Angular und HTML-benutzerdefinierten Elementen verwendet wird) kann ebenfalls verwendet werden.

Für Anleitungen zur Verwendung der benutzerdefinierten Komponentenmapping sehen Sie Linting benutzerdefinierter Komponenten. Für ein schrittweises Beispiel zum Erstellen und Überprüfen einer Konfiguration für eine Komponentenbibliothek, einschließlich Komponenten, die kein eigenes Element rendern, siehe Linten von Salesforce Lightning Web Components (LWC).

`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 Linting-Bibliothek für Komponenten zu aktivieren, fügen Sie den NPM-Paketnamen der Bibliothek dem 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 ä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 der Axe DevTools Linter dateiweise konfiguriert wird, indem Sie die overrides-Konfigurationsoption verwenden. Mehrere Überschreibungen auf derselben Datei werden in der Reihenfolge aufgelöst. Das heißt, die letzte aufgelistete Überschreibung hat die höchste Priorität.

Derzeit wird nur die linter-Überschreibung unterstützt und wird verwendet, um den Linter zu ändern, der auf die übereinstimmenden Dateien angewendet wird.

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`

Jede Regel ist standardmäßig aktiviert und wird als Fehler gemeldet. Verwenden Sie die Option rules, um zu ändern, wie einzelne Regeln behandelt werden: Setzen Sie eine Regel auf false, um sie zu deaktivieren, oder auf warn, um sie als Warnung anstelle eines Fehlers zu melden. Das Auflisten einer Regel beschränkt das Linting nicht auf die von Ihnen aufgeführten Regeln, sodass es nicht notwendig ist, die Regeln aufzulisten, die Sie behalten möchten. Um das Linting auf eine Gruppe von Regeln zu beschränken, verwenden Sie stattdessen Tags.

rules:
  some-rule: false      # turn off rule
  color-contrast: warn  # report violations as warnings instead of errors

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

{
  "config": {
    "rules": {
      "some-rule": false,
      "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 Connector verwenden möchten, siehe Konfigurationsdatei. Um die Regeln zu sehen, die der Axe DevTools Linter befolgt, siehe Barrierefreiheitsregeln. Weitere Informationen zur Verwendung der tags-Option, um Sammlungen von Regeln von der Verarbeitung auszuschließen, siehe unten Tags.

Zum Unterdrücken von Regeln für bestimmte Zeilen in einer Quelldatei ohne Änderung dieser Konfigurationsdatei siehe Unterdrücken von Linting-Regeln mit Inline-Direktiven.

`tags`

Sie können Regeln als Gruppe auswählen, basierend auf dem Barrierefreiheitsstandard, mit dem sie verbunden sind, indem Sie die Option tags verwenden. Eine Regel wird überprüft, wenn sie eines der von Ihnen aufgeführten Tags trägt, und jede Regel, die keines davon trägt, wird deaktiviert:

tags: # Check only WCAG 2.0 A, WCAG 2.0 AA, and best-practice rules.
  - wcag2a
  - wcag2aa
  - best-practice

important

Da das Auflisten eines Tags jede Regel deaktiviert, die es nicht trägt, deaktiviert eine eng gefasste Tag-Auswahl die meisten der Regeln. Die meisten der Regeln, die Axe DevTools Linter überprüft, tragen wcag2a, sodass eine Konfiguration, die nur WCAG 2.1-Tags auflistet, beinahe alle von ihnen deaktiviert. Für die Tags, die Sie verwenden können, siehe Tags.

Siehe auch

Für einen Überblick über die von Axe DevTools Linter bereitgestellten REST-APIs siehe Die Axe DevTools Linter REST-API-Referenz.
Für Anleitungen zur Erstellung benutzerdefinierter Komponentenabbildungen 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.

Konfiguration von Axe DevTools Linter

Überblick

Beispielkonfigurationen

Suchreihenfolge der Konfigurationsdatei

Zusammenfassung der Konfiguration von Axe DevTools Linter

Konfigurationsoptionen

`element`

`exclude`

`enterpriseId`

`extends`

Wie geerbte Einstellungen kombiniert werden

Grenzen und Fehlermanagement

`global-components`

`global-libraries`

`overrides`

`rules`

`tags`

Siehe auch

Is this page helpful?

Help us improve this page

Try

Still need help?