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

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

Exemples de Configurations

L'exemple YAML suivant démontre une configuration simple qui utilise l'option rules pour être utilisée avec l'extension Axe Accessibility Linter pour VS Code, le plugin JetBrains ou Axe DevTools Linter Connector :

rules:
  html-has-lang: false

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

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

Dans les deux cas, ces configurations font en sorte que Axe DevTools Linter ignore les erreurs d'accessibilité lorsque l'élément html manque d'un 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 Axe DevTools Linter Connector (lorsqu'il est utilisé avec l'option --config sans paramètre) chercheront dans le répertoire actuel et les répertoires parents un fichier de configuration axe-linter.yml dans l'arborescence de votre projet et utiliseront le premier qu'ils trouvent. Une pratique utile consiste à placer un fichier de configuration à la racine de votre projet contenant votre configuration par défaut, et à 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, recherchez dans les répertoires parents jusqu'à ce qu'un fichier de configuration axe-linter.yml soit trouvé, en vous arrêtant à votre dossier personnel si le projet est dans votre arborescence de dossiers personnels ou au répertoire racine s'il est en dehors de votre dossier personnel.
Utilisez un fichier de configuration axe-linter.yml situé dans votre répertoire personnel (même si votre projet se trouve dans un répertoire en dehors de votre dossier personnel ou sur un autre disque sous Windows). Par exemple, voici les fichiers typiquement 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`	Suit les étapes dans Ordre de Recherche des Fichiers de Configuration lorsqu'il est utilisé avec l'option `--config` sans paramètre.
Connecteur Axe Linter	Un fichier YAML nommé nom_fichier	Lorsqu'il est 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é émettre un élément img dans certains cas et un élément button dans d'autres cas, permettant 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'usage d'exemple ci-dessous émet un élément img à la place de l'élément par défaut button parce que l'attribut as spécifie l'élément de sortie :

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

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

`exclude`

L'option exclude empêche les fichiers correspondants d'être analysés. Vous pouvez utiliser des caractères génériques et des globaux. Son utilisation est principalement destinée à l'extension VS Code ou au plugin JetBrains et est ignorée par le point d'accès REST.

exclude: *.tmp

`enterpriseId`

Le champ optionnel enterpriseId accepte une chaîne de caractères qui est attachée aux événements d'analyse d'utilisation pour l'attribution d'entreprise. La plupart des utilisateurs n'auront pas besoin de définir cette valeur ; elle peut être demandée par votre représentant de compte Deque. Ce champ est ignoré sur les déploiements sur site.

enterpriseId: 'acme-corp'

`global-components`

L'option de configuration global-components indique à Axe DevTools Linter comment mapper vos propres composants personnalisés ou les composants de bibliothèques tierces vers des é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 HTML button natifs. Cela mappe automatiquement chaque attribut de DqButton à button, exigeant 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é à l'accessibilité en utilisant l'option attributes. Vous pouvez lister les attributs pris en charge par le composant ainsi que renommer les attributs. Il y a trois valeurs spéciales :

La valeur aria-* indique à Axe DevTools Linter que tous les attributs qui commencent par aria- sont mappés tel quel à 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 ouvrantes et fermantes) 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 équivalente en JSON (à 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 d'éléments sont sensibles à la casse. La nomenclature camel case, comme illustré ci-dessus, est couramment utilisée avec les fichiers .jsx, mais la nomenclature kebab case (utilisée dans Vue, Angular et les éléments personnalisés HTML) peut être utilisée.

Pour des présentations montrant comment utiliser le mappage de composant personnalisé, voir Lint 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 permettre l'analyse des composants de 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 mettre entre guillemets @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 de configuration overrides. Plusieurs substitutions sur le même fichier sont résolues dans l'ordre. C'est-à-dire que la dernière substitution listée a la plus haute priorité.

Actuellement, seul le remplacement linter est pris en charge 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 désactiver les règles individuellement avec l'option rules dans votre configuration. Chaque règle peut être réglée sur true (activé, signalé comme une erreur — par défaut), false (désactivé), ou warn (activé, signalé 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 de votre requête REST JSON :

{
  "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 que suit Axe DevTools Linter, voir Règles d’accessibilité. Voir balises ci-dessous pour plus d'informations sur l'utilisation de l'option tags pour exclure les collections de règles du traitement.

Pour supprimer des 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 par groupe basé sur la norme WCAG avec laquelle elles sont associées en utilisant l'option tags :

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 présentations 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.