Linting de composants personnalisés avec le axe Accessibility Linter pour VS Code ou JetBrains IDEs

Cet article montre comment configurer l’extension axe Accessibility Linter pour Visual Studio Code (VS Code) ou le plug-in pour JetBrains pour rechercher les erreurs d’accessibilité dans vos composants personnalisés.

Si vous souhaitez lire un aperçu du linting des composants personnalisés, consultez Linting Custom Components.

Pour utiliser cette procédure pas à pas, vous devez avoir installé les éléments suivants :

Pour Visual Studio Code :

• Visual Studio Code
• L'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 lint le code source, toutes les erreurs d'accessibilité sont affichées dans votre IDE avec un soulignement ondulé rouge. Par exemple, le code HTML suivant montre l'utilisation sans attribut img de l'élément alt , ce qui constitue une erreur d'accessibilité (affichée dans VS Code).

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

(Il s'agit d'un exemple simplifié à l'extrême pour illustrer le linting plutôt que d'un exemple réel.)

L'extension met en évidence la ligne erronée et fournit une info-bulle lorsque vous passez le curseur de votre souris sur l'erreur. Étant donné que cet élément n'a pas d'attribut, vous obtiendrez une erreur d'accessibilité de l'extension dans votre IDE (VS Code est affiché) : img alt

Un composant d'image personnalisé

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

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

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

Mappage custom-image vers img

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

global-components:
  custom-image: img

L'extension met désormais en évidence l'erreur d'accessibilité et fournit une info-bulle lorsque vous passez votre curseur sur l'erreur :

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

global-components:
  custom-image:
    element: img

Ou en abrégé element comme el :

global-components:
  custom-image:
    el: img

Résoudre le problème d’accessibilité

Vous pouvez ajouter un alt attribut à 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 le trait rouge ondulé (VS Code affiché) :

Mappage d'un attribut alternative-text

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

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

Dans ce cas, vous pouvez spécifier un mappage 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 global-components configuration est légèrement différente du mappage précédent d'un composant personnalisé à un élément HTML. Avec uniquement des éléments, vous utilisez un mappage d'une clé (custom-image) vers une valeur (img). Avec l'inclusion du tableau attributes , vous devez désormais utiliser la propriété element (ou el) pour spécifier l'élément HTML émis.

Cette modification corrige l'erreur et aucun soulignement ondulé rouge n'est affiché dans votre IDE (VS Code est affiché).

Vous pouvez également abréger attributes comme attrs :

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

Valeurs d'attribut spéciales : <text> et aria-*

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

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

(Le bouton personnalisé, en utilisant JavaScript et CSS qui ne sont pas inclus ici, masquera et affichera un div.)

Cette utilisation pose deux problèmes :

1. Si vous associez ce custom-button composant directement à un button élément, aucun contenu textuel ne sera affiché sur le bouton. L'intention de l'auteur du composant est cependant que l' message attribut soit utilisé comme contenu textuel : <button> *valeur de l'attribut message * </button>
2. L' button élément émis a un button rôle implicite de donc l' aria-colindex attribut est incorrect et doit être supprimé.

Comme c'est le cas par défaut, ce code HTML ne générera pas d'erreur car il n'y a pas de mappage entre custom-button et button. Cependant, si vous créez un mappage simple entre custom-button et button comme indiqué ci-dessous :

global-components:
  custom-button: button

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

La valeur spéciale <text>

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

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

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

Étant donné 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 attributes tableau, le seul attribut transmis à l'élément émis button était l'attribut message ; tous les attributs ne figurant pas dans le attributes tableau ne sont pas transmis. Cela signifie que l'erreur n'a pas été détectée par l'extension. aria-colindex

Utilisation de aria-*

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

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

Cette erreur se produit car l'élément button a un role="button" implicite et utiliser aria-colindex n'est pas valide avec les boutons. Avec l'attribut aria-*, all ARIA attributes are copied to the emitted element; this includes copying the invalid aria-colindex.

<element>

Avec des composants complexes, vous souhaiterez peut-être émettre un élément HTML différent de l'élément par défaut dans des cas spécifiques. Par exemple, vous pouvez avoir un composant de bouton qui se comporte généralement comme un bouton et, dans d’autres états, comme une image d’espace réservé. 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 my-button composant indique l'élément à émettre. Étant donné que l'élément émis ne contient pas d'attribut, vous recevrez une erreur : img alt

Passer tous les attributs de manière implicite

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

global-components:
  custom-button: button

En plus de l'erreur affichée dans votre IDE (VS Code est utilisé ici) :

L'exemple ci-dessus montre qu'une première étape pratique lorsque l'on commence à linter des composants personnalisés serait de commencer par un mappage d'éléments (copiant ainsi tous les attributs dans 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. Que vous ayez besoin d'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, l'exemple de configuration suivant montre un custom-menu composant mappé à un li élément avec un role de menu:

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

Étant donné 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 role attribut lorsqu'ils utilisent le custom-menu composant 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 plutôt que de demander aux utilisateurs de les définir lorsqu'ils utilisent votre composant.

En option, la valeur est définie sur name null dans la configuration, ce qui amène axe DevTools Linter à ignorer tous les attributs que les utilisateurs ont spécifiés role dans le code linté custom-menu .

Voir aussi

Configuration d'axe DevTools Linter

Composants personnalisés et point de terminaison REST

Bibliothèques de composants préconfigurés

axe DevTools Linter pour React Native