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 trouvés par cette recherche ne sont pas fusionnés. Le premier trouvé est le seul utilisé. Pour combiner les paramètres de plusieurs fichiers, faites en sorte que le fichier de configuration hérite des autres avec l'option extends.

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 enterpriseId facultatif 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é pour les déploiements sur site.

enterpriseId: 'acme-corp'

`extends`

L'option extends permet à un fichier axe-linter.yml d'hériter de ses paramètres d'un ou plusieurs fichiers de configuration parent, de sorte qu'une base commune puisse se trouver à un seul endroit au lieu d'être copiée dans chaque projet. Elle accepte soit un chemin de fichier unique, soit un tableau de chemins de fichiers, et est disponible à partir de la version 4.13.0 de l'extension Axe Accessibility Linter pour VS Code, le plugin JetBrains et Axe DevTools Linter Connector.

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

Pour hériter de plus d'un fichier, utilisez un tableau :

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

Les chemins sont résolus par rapport au fichier contenant l'option extends, et non au répertoire à partir duquel vous avez lancé le linter. Les chemins absolus sont également acceptés. Les fichiers parent n'ont pas besoin d'être nommés axe-linter.yml, et un fichier parent peut lui-même utiliser extends pour hériter d'un autre fichier.

note

Les noms de paquets nus (comme @my-org/axe-linter-config) et les URL distantes (comme https://example.com/axe-linter.yml) ne sont pas pris en charge. Seuls les chemins de fichiers relatifs et absolus peuvent être utilisés.

Comment les paramètres hérités sont combinés

Les fichiers parent sont lus de gauche à droite, et votre propre configuration est appliquée en dernier, elle l'emporte donc en cas de conflit. Chaque option est combinée comme suit :

Option	Comment elle est combinée
`rules`	Fusionné par ID de règle, et votre valeur l'emporte. Parce que chaque règle est activée et signalée comme une erreur par défaut (voir `rules`), un fichier parent utilise cette option pour désactiver des règles ou les signaler comme des avertissements, et votre propre configuration peut modifier l'une de ces décisions, y compris en rétablissant une règle à `true` pour restaurer le signalement d'erreur par défaut.
`tags`	Combiné avec les valeurs du parent, avec suppression des doublons.
`exclude`	Combiné avec les valeurs du parent, avec suppression des doublons.
`global-libraries`	Combiné avec les valeurs du parent, avec suppression des doublons.
`global-components`	Fusionné par nom de composant. Une entrée dans votre configuration remplace entièrement une entrée parente avec le même nom plutôt que d'y être fusionnée, donc répéter un nom de composant signifie répéter tous les paramètres de ce composant.
`overrides`	Combiné, avec les entrées du parent d'abord, suivies par les vôtres.
Toute autre option, comme `enterpriseId`	Votre valeur l'emporte, et le parent fournit la valeur pour toute option que vous laissez de côté.

important

Si un fichier parent définit enterpriseId et que votre propre configuration ne le fait pas, l'utilisation de votre projet est comptée sous l'ID d'entreprise du parent. Définissez enterpriseId dans votre propre configuration si vous avez besoin d'une valeur différente.

Limites et gestion des erreurs

Un fichier de configuration ne peut pas s'étendre à lui-même, soit directement, soit à travers une chaîne de fichiers parent. Les chaînes sont limitées à 10 niveaux de profondeur, et une seule configuration peut hériter de pas plus de 100 fichiers parent au total.

Si un fichier parent est manquant, n'est pas un YAML valide, ou contient un paramètre invalide, Axe DevTools Linter signale une erreur en nommant le fichier qui a causé le problème. Dans VS Code et les IDE JetBrains, une notification apparaît et le linting continue en utilisant la configuration par défaut. Axe DevTools Linter Connector signale l'erreur et se termine avec le code de sortie 3 (voir Codes de sortie).

`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 guides montrant comment utiliser la cartographie des composants personnalisés, voir Lint des composants personnalisés. Pour un exemple étape par étape de la création et de la vérification d'une configuration pour une bibliothèque de composants, y compris des composants qui ne rendent aucun élément propre, voir Linter les composants Web Lightning de Salesforce (LWC).

`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`

Chaque règle est activée et signalée comme une erreur par défaut. Utilisez l'option rules pour modifier la gestion des règles individuelles : définissez une règle sur false pour la désactiver, ou sur warn pour la signaler comme un avertissement au lieu d'une erreur. Lister une règle ne limite pas l'analyse aux règles que vous mentionnez, il n'est donc pas nécessaire de lister les règles que vous souhaitez conserver. Pour limiter l'analyse à un groupe de règles, utilisez plutôt balises.

rules:
  some-rule: false      # turn off rule
  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,
      "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 sélectionner des règles en groupe, en fonction de la norme d'accessibilité avec laquelle elles sont associées, en utilisant l'option tags. Une règle est vérifiée si elle porte l'un des tags que vous mentionnez, et toute règle ne portant aucun de ces tags est désactivée :

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

important

Étant donné que lister un tag désactive chaque règle qui ne le porte pas, un ensemble restreint de tags désactive la plupart des règles. La plupart des règles vérifiées par Axe DevTools Linter portent wcag2a, donc une configuration ne listant que les tags WCAG 2.1 laisse presque toutes désactivées. Pour les tags que vous pouvez utiliser, voir Tags.

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.

Configuration de l'Axe DevTools Linter

Vue d'ensemble

Exemples de Configurations

Ordre de Recherche des Fichiers de Configuration

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

Options de Configuration

`element`

`exclude`

`enterpriseId`

`extends`

Comment les paramètres hérités sont combinés

Limites et gestion des erreurs

`global-components`

`global-libraries`

`overrides`

`rules`

`tags`

Voir aussi

Is this page helpful?

Help us improve this page

Try

Still need help?