Linting des composants personnalisés avec l'endpoint REST

Cet article montre comment utiliser le point de terminaison REST axe DevTools Linter pour le linting des erreurs d'accessibilité dans les composants personnalisés.

Prérequis

Vous aurez besoin d'accéder soit à la version SaaS, soit à une version sur site d'axe DevTools Linter. Consultez Obtention d'une clé API SaaS axe DevTools Linter ou Configuration de l'édition sur site d'axe DevTools Linter pour plus d'informations.

Vous aurez également besoin d’un outil REST qui :

• Peut envoyer des requêtes POST
• Peut ajouter des en-têtes (pour la version SaaS d'axe DevTools Linter) Authorization
• Permet de créer des corps de requête JSON

Procédure pas à pas du linting des composants personnalisés

Lorsque vous utilisez axe DevTools Linter pour analyser le code source, vous fournissez un corps JSON contenant la source et la configuration dans votre requête HTTP. Par exemple, le code HTML suivant montre l'utilisation de l'élément img  :

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

(Il s'agit d'un exemple grandement simplifié uniquement pour illustrer le linting plutôt qu'un exemple concret.)

Le corps JSON de la requête à envoyer à axe DevTools Linter ressemblerait à ceci :

{ 
  "source": "<img src=\"path/to/image.jpg\"/>",
  "filename": "image-demo.html"
}

Étant donné que cet élément n'a pas d'attribut, vous obtiendrez une erreur d'accessibilité de la part d'axe DevTools Linter : img alt

{
  "report": {
    "errors": [
      {
        "column": 1,
        "description": "Ensures <img> elements have alternate text or a role of none or presentation",
        "endColumn": 31,
        "helpURL": "https://dequeuniversity.com/rules/axe/4.4/image-alt?application=axe-linter",
        "lineContent": "<img src=\"path/to/image.jpg\"/>",
        "lineNumber": 1,
        "linterType": "html",
        "ruleId": "image-alt"
      }
    ]
  }
}

Un composant d'image personnalisé

L'exemple suivant montre un composant personnalisé : custom-image

<custom-image src="path/to/image.jpg"></custom-image>

Pour envoyer le code HTML à axe DevTools Linter à l'aide d'une requête POST, utilisez ce qui suit comme corps JSON :

{
  "source": "<custom-image src=\"path/to/image.jpg\"></custom-image>",
  "filename": "custom-image.html"
}

Le serveur répond sans erreur d'accessibilité car il n'y a pas de mappage entre custom-image et img, donc axe DevTools Linter ne peut pas signaler un attribut manquant alt  :

{
  "report": {
    "errors": []
  }
}

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 (partie de l'objet) : global-components config

{
  "config": {
    "global-components": {
      "custom-image": "img"
    }
  },
  "filename": "c-image.html",
  "source": "<custom-image src=\"path/to/image.jpg\"></custom-image>\n\n"
}

axe DevTools Linter répond désormais avec ce qui suit :

{
  "report": {
    "errors": [
      {
        "column": 1,
        "description": "Ensures <img> elements have alternate text or a role of none or presentation",
        "endColumn": 54,
        "helpURL": "https://dequeuniversity.com/rules/axe/4.4/image-alt?application=axe-linter",
        "lineContent": "<custom-image src=\"path/to/image.jpg\"></custom-image>",
        "lineNumber": 1,
        "linterType": "html",
        "ruleId": "image-alt"
      }
    ]
  }
}

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

{
  "config": {
    "global-components": {
      "custom-image": {
        "element": "img"
      }
    }
  }
}

Ou en abrégé element comme el :

{
  "config": {
    "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é (comme indiqué ci-dessous avec le corps JSON de la requête) :

{
  "config": {
    "global-components": {
      "custom-image": "img"
    }
  },
  "filename": "c-image.html",
  "source": "<custom-image src=\"path/to/image.jpg\" alt=\"alt text\"></custom-image>\n\n"
}

Le serveur répond avec le tableau vide suivant car votre composant personnalisé possède l'attribut requis (qui a été copié, avec tous les autres attributs du composant, dans l'élément émis) : errors alt ** custom-image img

{
  "report": {
    "errors": []
  }
}

Mappage de l'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 src="path/to/image.jpg" alternative-text="alt text"></custom-image>

Dans ce cas, vous pouvez spécifier un mappage entre l' alternative-text attribut et l' alt attribut comme indiqué avec le attributes tableau dans le corps de la requête JSON ci-dessous :

{
  "config": {
    "global-components": {
      "custom-image": {
        "element": "img",
        "attributes": [
          {
            "alternative-text": "alt"
          }
        ]
      }
    }
  },
  "filename": "c-image.html",
  "source": "<custom-image src=\"path/to/image.jpg\" alternative-text=\"alt text\"></custom-image>\n\n"
}

axe DevTools Linter répond comme suit car la alt-text règle a été satisfaite par votre alternative-text attribut :

{
  "report": {
    "errors": []
  }
}

Vous pouvez également abréger attributes comme attrs :

{
  "config": {
    "global-components": {
      "custom-image": {
        "attrs": [
          {
            "alternative-text": "alt"
          }
        ],
        "element": "img"
      }
    }
  }
}

Valeurs d'attribut spéciales : <text>, aria-* and <element>

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'élément émis a un rôle implicite de, donc l'attribut est incorrect et doit être supprimé. button button aria-colindex

Si vous envoyez le code ci-dessus à axe DevTools Linter (sans mappage), vous recevez cette réponse : global-components

{
  "report": {
    "errors": []
  }
}

La valeur spéciale <text>

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

Pour configurer la requête pour alerter axe DevTools Linter que l'attribut doit être considéré comme un contenu texte pour l'élément HTML, vous pouvez utiliser la valeur spéciale et envoyer la requête suivante : message button <text>

{
  "config": {
    "global-components": {
      "custom-button": {
        "attributes": [
          {
            "message": "<text>"
          }
        ],
        "element": "button"
      }
    }
  },
  "filename": "aria-button.html",
  "source": "<custom-button aria-controls=\"expand-region\" aria-expanded=\"false\" aria-colindex=\"1\" message=\"Show Region\"></custom-button>\n"
}

Étant donné que vous avez défini l'attribut message comme <text>, vous avez indiqué à axe DevTools Linter 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 le serveur. aria-colindex

Utilisation de aria-*

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

{
  "config": {
    "global-components": {
      "custom-button": {
        "attributes": [
          {
            "message": "<text>"
          },
          "aria-*"
        ],
        "element": "button"
      }
    }
  },
  "filename": "aria-button.html",
  "source": "<custom-button aria-controls=\"expand-region\" aria-expanded=\"false\" aria-colindex=\"1\" message=\"Show Region\"></custom-button>\n"
}

Le serveur répond avec :

{
  "report": {
    "errors": [
      {
        "column": 1,
        "description": "Ensures ARIA attributes are allowed for an element's role",
        "endColumn": 124,
        "helpURL": "https://dequeuniversity.com/rules/axe/4.4/aria-allowed-attr?application=axe-linter",
        "lineContent": "<custom-button aria-controls=\"expand-region\" aria-expanded=\"false\" aria-colindex=\"1\" message=\"Show Region\"></custom-button>",
        "lineNumber": 1,
        "linterType": "html",
        "ruleId": "aria-allowed-attr"
      }
    ]
  }
}

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.

{  
  "config": {
    "global-components": {
      "my-button": {
        "element": "button",
        "attributes": [
         {
          "use": "<element>"
         },
         'src',
         'alt'
        ]
      } 
    }
  },

  "filename": "aria-button.html",
  "source": "<my-button use=\"img\" src=\"globe.jpg\"></my-button>"
}

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

{
  "report": {
    "errors": [
      {
        "ruleId": "image-alt",
        "helpURL": "https://dequeuniversity.com/rules/axe/4.10/image-alt?application=axe-linter",
        "description": "Images must have alternative text",
        "lineNumber": 1,
        "column": 1,
        "linterType": "html",
        "lineContent": "<my-button use=\"img\" src=\"globe.jpg\"></my-button>",
        "endColumn": 50
      }
    ]
  }
}

Passer tous les attributs de manière implicite

Notez que 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 comme indiqué ci-dessous : attributes button

{
  "config": {
    "global-components": {
      "custom-button": "button"
    }
  },
  "filename": "aria-button.html",
  "source": "<custom-button aria-controls=\"expand-region\" aria-expanded=\"false\" aria-colindex=\"1\" message=\"Show Region\"></custom-button>\n"
}

Avec cette réponse du serveur, vous pouvez voir que tous les attributs de custom-button sont vérifiés pour les problèmes d'accessibilité, et deux erreurs sont trouvées :

{
  "report": {
    "errors": [
      {
        "column": 1,
        "description": "Ensures ARIA attributes are allowed for an element's role",
        "endColumn": 124,
        "helpURL": "https://dequeuniversity.com/rules/axe/4.4/aria-allowed-attr?application=axe-linter",
        "lineContent": "<custom-button aria-controls=\"expand-region\" aria-expanded=\"false\" aria-colindex=\"1\" message=\"Show Region\"></custom-button>",
        "lineNumber": 1,
        "linterType": "html",
        "ruleId": "aria-allowed-attr"
      },
      {
        "column": 1,
        "description": "Ensures buttons have discernible text",
        "endColumn": 124,
        "helpURL": "https://dequeuniversity.com/rules/axe/4.4/button-name?application=axe-linter",
        "lineContent": "<custom-button aria-controls=\"expand-region\" aria-expanded=\"false\" aria-colindex=\"1\" message=\"Show Region\"></custom-button>",
        "lineNumber": 1,
        "linterType": "html",
        "ruleId": "button-name"
      }
    ]
  }
}

L'exemple ci-dessus montre qu'une première étape pratique lorsque l'on commence à analyser 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 (si les attributs du composant personnalisé doivent être mappés à des attributs différents ou 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, l'exemple de configuration suivant montre un custom-menu composant mappé à un li élément avec un role de menu:

{
  "config": {
    "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 dans la configuration, ce qui oblige axe DevTools Linter à ignorer tous les null attributs que les utilisateurs ont role spécifiés custom-menu dans le code linté.

Voir aussi

• axe DevTools Linter REST API Reference contient plus d'informations sur l'utilisation des différents points de terminaison REST fournis par axe DevTools Linter.
• Obtention d'une clé API SaaS axe DevTools Linter montre comment obtenir une clé API pour utiliser la version Software as a Service (SaaS) d'axe DevTools Linter.