Linter des composants personnalisés avec l’Axe Accessibility Linter pour VS Code ou les IDE JetBrains

Cet article montre comment configurer l'extension Axe Accessibility Linter pour Visual Studio Code (VS Code) ou le plugin pour JetBrains afin de trouver des erreurs d'accessibilité dans vos composants personnalisés.

Si vous souhaitez lire un aperçu de l'analyse des composants personnalisés, consultez Linter des composants personnalisés.

Pour utiliser ce guide, vous devez avoir installé les éléments suivants :

Pour Visual Studio Code :

• Visual Studio Code
• Le Extension Axe Accessibility Linter pour VS Code

Pour les IDE JetBrains :

• IntelliJ IDEA Ultimate

  ou

• WebStorm

• Le Plugin Axe Accessibility Linter pour JetBrains

Un exemple d'erreur d'accessibilité

Lorsque vous utilisez l'extension pour analyser le code source, les erreurs d'accessibilité sont affichées dans votre IDE avec un soulignement ondulé rouge. Par exemple, le HTML suivant montre l'utilisation de l'élément img sans l'attribut alt, ce qui constitue une erreur d'accessibilité (montrée dans VS Code).

<img src="path/to/image.jpg"/>

(Ceci est un exemple simplifié pour démontrer l'analyse plutôt qu'un exemple réel.)

L'extension met en évidence la ligne en erreur et fournit un tooltip lorsque vous survolez l'erreur avec la souris. Étant donné que cet élément img ne possède pas d'attribut alt, vous recevrez une erreur d'accessibilité de l'extension dans votre IDE (montré dans VS Code) :

Un composant image personnalisé

Pour cet exemple, un développeur a créé un composant personnalisé appelé custom-image. L'exemple suivant montre l'utilisation du composant personnalisé custom-image :

<custom-image path="images/image.jpg"></custom-image>

Pour cet exemple, le composant custom-image crée un élément img avec un attribut path (qui est mappé à un attribut src par l'implémentation du contrôle personnalisé). L'extension n'affiche aucune erreur car elle ne possède pas de mapping entre custom-image et img, même si l'élément de sortie img manque d'un attribut alt :

Mapper custom-image à img

Si vous fournissez un mapping entre custom-image et img, Axe DevTools Linter peut mapper votre composant personnalisé comme un élément HTML standard et localiser les erreurs d'accessibilité. Vous pouvez spécifier le mapping en utilisant l'option de configuration global-components dans un fichier de configuration axe-linter.yml :

global-components:
  custom-image: img

L'extension met maintenant en évidence l'erreur d'accessibilité et fournit un tooltip lorsque vous survolez l'erreur avec votre curseur :

Vous pouvez également indiquer le même mapping que ci-dessus avec l'une de ces syntaxes :

global-components:
  custom-image:
    element: img

Ou, alternativement, en abrégé element comme el :

global-components:
  custom-image:
    el: img

Résoudre le problème d'accessibilité

Vous pouvez ajouter un attribut alt à votre custom-image pour résoudre le problème d'accessibilité :

<custom-image path="images/image.jpg" alt="alt text"></custom-image>

Il n'y a plus d'erreur, donc votre IDE n'affiche plus de soulignement ondulé rouge (montré dans VS Code) :

Mapper un attribut alternative-text

Si votre composant image personnalisé utilise à la place un attribut différent pour indiquer le texte alternatif, vous pouvez spécifier cet attribut dans la configuration. Par exemple, supposons que votre composant custom-image utilise un attribut alternative-text au lieu de alt, comme indiqué ci-dessous :

<custom-image path="images/image.jpg" alternative-text="alt text"></custom-image>

Dans ce cas, vous pourriez spécifier un mapping entre l'attribut alternative-text et l'attribut alt, comme indiqué avec le tableau attributes dans un fichier axe-linter.yml comme indiqué ci-dessous :

global-components:
  custom-image:
    element: img
    attributes:
      - alternative-text: alt

Cette configuration global-components est légèrement différente du mapping précédent d'un composant personnalisé à un élément HTML. Avec seulement des éléments, vous utilisez un mapping d'une clé (custom-image) à une valeur (img). Avec l'inclusion du tableau attributes, vous devez maintenant utiliser la propriété element (ou el) pour spécifier l'élément HTML émis.

Cette modification corrige l'erreur, et il n'y a pas de soulignement ondulé rouge affiché dans votre IDE (montré dans VS Code).

Vous pouvez également abréger attributes comme attrs :

global-components:
  custom-image:
    element: img
    attrs:
      - alternative-text: alt

Valeurs Spéciales des Attributs : <text> et aria-*

Supposons que vous utilisiez un composant custom-button comme suit :

<custom-button aria-controls="expand-region" aria-expanded="false" aria-colindex="1" message="Show Region"></custom-button>

(Le bouton personnalisé, utilisant JavaScript et CSS non inclus ici, cachera et affichera un div.)

Il y a deux problèmes avec cette utilisation :

1. Si vous mappez ce composant custom-button directement sur un élément button, il n'y aura pas de contenu textuel à afficher sur le bouton. Cependant, l'intention de l'auteur du composant est que l'attribut message soit utilisé comme contenu textuel : <button> valeur de l'attribut message </button>
2. L'élément button émis a un rôle implicite de button donc l'attribut aria-colindex est incorrect et devrait être supprimé.

Par défaut, cet HTML ne provoquera pas d'erreur car il n'y a pas de mappage entre custom-button et button. Cependant, si vous créez un simple mappage entre custom-button et button comme montré ci-dessous :

global-components:
  custom-button: button

Vous recevrez deux erreurs de votre IDE (VS Code est montré) :

La Valeur Spéciale <text>

Pour résoudre le premier problème (le contenu textuel pour l'élément button provenant d'un attribut message, identifié ci-dessus sous nom-du-bouton dans l'info-bulle de votre IDE), vous pouvez utiliser la valeur spéciale <text> qui associe un attribut au contenu textuel de l'élément émis. Dans ce cas, le texte de l'attribut message doit être copié dans le contenu textuel de l'élément button émis.

Pour configurer l'extension afin que l'attribut message soit considéré comme contenu textuel pour l'élément HTML button, vous pouvez utiliser la valeur spéciale <text> dans un fichier de configuration axe-linter.yml :

global-components:
  custom-button:
    element: button
    attributes:
      - message: <text>

Parce que vous avez défini l'attribut message comme <text>, vous avez indiqué à l'extension de considérer cet attribut comme remplaçant le contenu textuel de l'élément HTML button par la valeur de l'attribut message.

Malheureusement, en utilisant le tableau attributes, le seul attribut qui a été transmis à l'élément button émis était seulement l'attribut message ; tout attribut ne se trouvant pas dans le tableau attributes n'est pas transmis. Cela signifie que l'incorrect aria-colindex n'a pas été détecté par l'extension.

Utiliser aria-*

Vous pouvez utiliser la valeur spéciale aria-* pour transmettre tous les attributs ARIA, comme montré ci-dessous :

global-components:
  custom-button:
    element: button
    attributes:
      - message: <text>
      - aria-*

Cette erreur se produit parce que l'élément button a un role="button" implicite et que l'utilisation de aria-colindex est invalide avec les boutons. Avec aria-*, tous les attributs ARIA sont copiés dans l'élément émis ; cela inclut la copie de l'attribut aria-colindex invalide.

<element>

Avec des composants complexes, vous pourriez vouloir émettre un élément HTML différent de l'élément par défaut dans des cas spécifiques. Par exemple, vous pourriez avoir un composant bouton qui se comporte généralement comme un bouton et, dans d'autres états, comme une image de remplacement. La valeur <element> vous permet de spécifier un attribut sur votre composant personnalisé qui détermine l'élément émis.

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

Dans ce cas, l'attribut use sur le composant my-button indique l'élément à émettre. Parce que l'élément img émis ne contient pas d'attribut alt, vous recevrez une erreur :

Passer Tous les Attributs Implicitement

Si vous n'aviez utilisé que le mappage d'éléments (où le mappage n'utilise pas le tableau attributes), tous les attributs seraient, par défaut, copiés vers l'élément button. La configuration pour ce cas a été montrée précédemment :

global-components:
  custom-button: button

Avec l'erreur affichée dans votre IDE (VS Code est montré ici) :

L'exemple ci-dessus montre qu'un premier pas pratique lorsque vous commencez à vérifier les composants personnalisés serait de commencer par un mappage d'éléments (copiant ainsi tous les attributs vers l'élément HTML standard émis) puis de voir quels attributs doivent être ajoutés à la configuration :

1. Si l'un des attributs du composant personnalisé doit être mappé à différents attributs.
2. Si vous devez utiliser <text> ou aria-*.

Attributs Par Défaut

Les attributs par défaut vous permettent de définir des valeurs pour les attributs dans votre fichier de configuration plutôt que de mapper un attribut à un autre. Par exemple, la configuration exemple suivante montre un composant custom-menu mappé à un élément li avec un role de menu :

global-components:
  custom-menu:
    element: li
    attributes:
      - role:
          name: null
          default: menu

Parce que l'attribut role a une valeur par défaut de menu, définie dans le fichier de configuration, les utilisateurs n'ont pas besoin de spécifier un attribut role quand ils utilisent le composant custom-menu dans leur code. L'implication est que l'implémentation de votre composant personnalisé crée ces attributs sur l'élément de sortie et définit leurs valeurs au lieu de demander aux utilisateurs de les définir lorsqu'ils utilisent votre composant.

Optionnellement, la valeur name est définie sur null dans la configuration, ce qui fait que Axe DevTools Linter ignore tout attribut role que les utilisateurs ont spécifié sur custom-menu dans le code vérifié.

Voir Aussi

Configuration de Axe DevTools Linter

Composants Personnalisés et l'Endpoint REST

Bibliothèques de Composants Préconfigurées

Axe DevTools Linter pour React Native

Analyse des Violations des Composants Personnalisés dans les Rapports CI/CD