Configuration de l'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

Guide de référence pour configurer l'Axe DevTools Linter

Not for use with personal data

Cet article fournit une référence pour les options de configuration de l'Axe DevTools Linter.

Vue d'ensemble

L' endpoint de l'API REST utilise JSON pour la configuration, et l' extension Axe Accessibility Linter pour VS Code, le plugin JetBrains, et le Connecteur Axe DevTools Linter utilisent YAML pour la configuration. Des exemples de configurations de l'Axe DevTools Linter en JSON et YAML sont présentés dans ce guide.

Exemples de Configurations

L'exemple YAML suivant montre une configuration simple qui utilise l'option rules pour l'extension Axe Accessibility Linter pour VS Code, le plugin JetBrains, ou le Connecteur Axe DevTools Linter :

rules:
  html-has-lang: false

L'exemple suivant montre la même configuration en tant qu'objet de requête complet avec l'option rules pour le service REST de l'Axe DevTools Linter avec son objet intégré config mis en évidence :

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

Dans les deux cas, ces configurations font que l'Axe DevTools Linter ignore les erreurs d'accessibilité lorsque l'élément html est dépourvu de l'attribut lang . (Voir la règle html-has-lang pour plus d'informations.)

note

Pour tous les exemples JSON de cet article, l'objet config est inclus pour fournir un emplacement de référence pour la configuration.

Les sections suivantes décrivent chaque option de configuration et donnent des exemples de leur utilisation.

Ordre de Recherche des Fichiers de Configuration

L'extension Axe Accessibility Linter pour VS Code, le plugin JetBrains, et le Connecteur Axe DevTools Linter (lorsqu'il est utilisé avec l'option --config sans paramètre) vont chercher dans le répertoire actuel et les répertoires parents un fichier de configuration axe-linter.yml dans l'arborescence du répertoire de votre projet et utiliser le premier qu'ils trouvent. Une pratique utile est de placer un fichier de configuration à la racine de votre projet contenant votre configuration par défaut, et de le remplacer (si nécessaire) par des fichiers de configuration dans différents sous-répertoires. Vous pouvez également placer un fichier de configuration dans votre répertoire personnel qui sera utilisé par défaut s'il n'y a pas de fichiers de configuration dans votre projet.

important

Les fichiers de configuration ne sont pas fusionnés ensemble. Le premier trouvé est le seul utilisé.

Les étapes pour localiser le fichier de configuration axe-linter.yml à utiliser sont :

Utiliser le fichier de configuration dans le répertoire actuel (le répertoire contenant le fichier édité avec VS Code, un IDE JetBrains, ou le répertoire actuel de l'invite de commande avec le Connecteur Axe DevTools Linter).
Si aucune configuration n'est trouvée à l'étape 1, chercher dans les répertoires parents jusqu'à ce qu'un fichier de configuration axe-linter.yml soit trouvé, en s'arrêtant à votre dossier personnel si le projet se trouve dans l'arborescence de votre répertoire personnel ou au répertoire racine s'il est en dehors de votre dossier personnel.
Utiliser un fichier de configuration axe-linter.yml situé dans votre répertoire personnel (même si votre projet est situé dans un répertoire en dehors de votre dossier personnel ou sur un autre lecteur sous Windows). Par exemple, voici les fichiers typiques utilisés :
- /home/nom d'utilisateur/axe-linter.yml (Linux)
- /Users/nom d'utilisateur/axe-linter.yml (macOS)
- C:\Users\nom d'utilisateur\axe-linter.yml (Windows)

La recherche s'arrête lorsque le premier fichier axe-linter.yml est trouvé.

Résumé de la Configuration de l'Axe DevTools Linter

Produit	Type de Configuration	Description
Extension Axe Accessibility Linter pour VS Code ou le plugin JetBrains	Un fichier YAML nommé `axe-linter.yml`	Voir Ordre de Recherche des Fichiers de Configuration.
Connecteur Axe Linter	Un fichier YAML nommé `axe-linter.yml`	Suivez les étapes dans Ordre de Recherche des Fichiers de Configuration lors de l'utilisation de l'option `--config` sans paramètre.
Connecteur Axe Linter	Un fichier YAML nommé nom_fichier	Lorsqu'utilisé avec `--config` nom_fichier.
API REST Axe Linter	Objet de configuration JSON	Voir L'objet de configuration.

Options de Configuration

`element`

L'option element vous permet de changer l'élément émis en fonction de la valeur de l'attribut spécifié par votre composant. Par exemple, vous pourriez avoir un composant personnalisé qui émet un élément img dans certains cas et un élément button dans d'autres cas, permettant ainsi des cas d'utilisation plus complexes.

La configuration d'exemple ci-dessous spécifie que l'attribut as sur le composant my-button peut changer l'élément émis par défaut de button:

YAML :

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

JSON :

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

L'exemple d'utilisation ci-dessous émet un élément img au lieu de l'élément button par défaut car l'attribut as spécifie l'élément de sortie :

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

L'élément img de sortie sera alors analysé et il sera trouvé qu'il manque un attribut alt .

`exclude`

L'option exclude empêche les fichiers correspondants d'être analysés. Vous pouvez utiliser des jokers et des motifs globaux. Son utilisation est principalement pour l'extension VS Code ou le plugin JetBrains et est ignorée par le point de terminaison REST.

exclude: *.tmp

`global-components`

L'option de configuration global-components dirige Axe DevTools Linter sur la façon de mapper vos propres composants personnalisés ou les composants de bibliothèques tierces en éléments HTML natifs, vous permettant d'analyser vos composants comme s'ils étaient des éléments HTML natifs. Par exemple, la configuration suivante traitera tous les composants DqButton personnalisés comme s'ils étaient des éléments button HTML natifs. Cela mappe automatiquement chaque attribut sur DqButton à button, nécessitant ainsi un nom accessible pour tous les composants DqButton .

YAML :

global-components:
  DqButton: button

JSON :

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

Alternativement, pour les composants qui ne mappent pas tous les attributs aux composants HTML natifs, vous pouvez lister les attributs requis pour la conformité en matière d'accessibilité en utilisant l'option attributes . Vous pouvez lister les attributs que le composant supporte ainsi que renommer des attributs. Il y a trois valeurs spéciales :

La valeur aria-* indique à Axe DevTools Linter que tous les attributs commençant par aria- sont mappés tels quels à l'élément HTML natif. Notez que la valeur se termine par un astérisque.
La valeur <text> indique à Axe DevTools Linter qu'une propriété est utilisée pour définir le contenu (la valeur entre les balises ouvrante et fermante) de l'élément HTML natif.
La valeur <element> indique à Axe DevTools Linter que l'élément émis peut prendre la valeur de cet attribut, ce qui vous permet de changer l'élément émis en fonction de la valeur de l'attribut spécifié.

L'exemple YAML suivant montre toutes les valeurs qui peuvent être utilisées avec global-components:

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.)

Une version JSON équivalente (à l'intérieur de l'objet config ) est la suivante :

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

Seuls les attributs pertinents pour l'accessibilité doivent être dans la liste attributes . Les noms des éléments sont sensibles à la casse. Le style Camel case, comme montré ci-dessus, est couramment utilisé avec les fichiers .jsx, mais le style kebab case (utilisé dans Vue, Angular et les éléments HTML personnalisés) peut être utilisé.

Pour des démonstrations sur comment utiliser le mappage des composants personnalisés, voir Linting des composants personnalisés.

`global-libraries`

Axe DevTools Linter a un support intégré pour plusieurs bibliothèques de composants et frameworks populaires.

Les bibliothèques suivantes sont actuellement supportées :

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

Pour activer le linting des composants de la bibliothèque, ajoutez le nom du package NPM de la bibliothèque au tableau global-libraries pour les fichiers de configuration YAML :

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

note

Vous devez citer @mui/material et @deque/cauldron-react dans YAML car @ est interprété comme un caractère réservé.

Ou la configuration JSON équivalente est montrée ci-dessous :

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

Tout composant portant le même nom qu'un composant de la bibliothèque globale sera traité comme ce composant de bibliothèque, permettant de réexporter et redéclarer des composants sans perdre leur mappage.

Pour plus d'informations, voir Bibliothèques de composants préconfigurées.

`overrides`

Vous pouvez modifier la configuration d'Axe DevTools Linter par fichier en utilisant l'option overrides de configuration. Plusieurs remplacements sur le même fichier sont résolus dans l'ordre. C'est-à-dire que le dernier remplacement listé a la plus haute priorité.

Actuellement, seul le remplacement linter est supporté et est utilisé pour changer le linter utilisé sur les fichiers correspondants.

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`

Vous pouvez autoriser ou interdire des règles individuellement avec l'option rules dans votre configuration. Chaque règle peut être définie comme true (activée, signalée comme une erreur — par défaut), false (désactivée), ou warn (activée, signalée comme un avertissement) :

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

Ou dans l'objet config dans votre requête JSON REST :

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

Pour des informations sur l'utilisation de rules avec l’API REST, voir La propriété rules. Si vous souhaitez utiliser rules avec le connecteur Axe DevTools Linter, voir Fichier de configuration. Pour voir les règles suivies par Axe DevTools Linter, voir Règles d’accessibilité. Voir balises ci-dessous pour plus d'informations sur l'utilisation de l’ tags option pour exclure des collections de règles du processus.

Pour ignorer les règles pour des lignes spécifiques dans un fichier source sans modifier ce fichier de configuration, voir Suppression des règles de linting avec des directives en ligne.

`tags`

Vous pouvez désactiver des règles en groupe en fonction de la norme WCAG à laquelle elles sont associées en utilisant l’ tags option :

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

Voir aussi

Pour une référence aux API REST fournies par Axe DevTools Linter, voir La référence de l’API REST d’Axe DevTools Linter.
Pour des guides sur la création de mappages de composants personnalisés, voir Lint des composants personnalisés.
Pour télécharger l'extension pour VS Code, voir Axe Accessibility Linter.
Pour plus d'informations sur le plugin JetBrains, voir Utilisation du plugin avec les IDE JetBrains.