Linten van Aangepaste Componenten met de Axe Accessibility Linter voor VS Code of JetBrains IDE's

Dit artikel laat zien hoe u de Axe Accessibility Linter-extensie voor Visual Studio Code (VS Code) of de plugin voor JetBrains kunt configureren om toegankelijkheidsfouten in uw aangepaste componenten te vinden.

Als u een overzicht wilt lezen over het linten van aangepaste componenten, zie dan Linten van Aangepaste Componenten.

Om deze handleiding te gebruiken, zou u het volgende geïnstalleerd moeten hebben:

Voor Visual Studio Code:

• Visual Studio Code
• De Axe Accessibility Linter-extensie voor VS Code

Voor JetBrains IDE's:

• IntelliJ IDEA Ultimate

  of

• WebStorm

• De Axe Accessibility Linter-plugin voor JetBrains

Een Voorbeeld van een Toegankelijkheidsfout

Wanneer u de extensie gebruikt om broncode te linten, worden eventuele toegankelijkheidsfouten in uw IDE weergegeven met een rode golvende onderstreping. Bijvoorbeeld, de volgende HTML toont het gebruik van het img-element zonder een alt-attribuut, wat een toegankelijkheidsfout is (weergegeven in VS Code).

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

(Dit is een sterk vereenvoudigd voorbeeld om linting aan te tonen, eerder dan een werkelijk praktijkvoorbeeld.)

De extensie markeert de foutregel en geeft een tooltip weer wanneer u met de muiscursor over de fout zweeft. Omdat dit img-element geen alt-attribuut heeft, krijgt u een toegankelijkheidsfout van de extensie in uw IDE (VS Code wordt getoond):

Een Aangepaste Afbeelding Component

Voor dit voorbeeld heeft een ontwikkelaar een aangepaste component genaamd custom-image gemaakt. Het volgende voorbeeld toont het gebruik van de custom-image-component:

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

Voor dit voorbeeld creëert de custom-image-component een img-element met een path-attribuut (wat wordt gemapt naar een src-attribuut door de implementatie van de aangepaste controle). De extensie geeft geen fout omdat er geen mapping is tussen custom-image en img, ondanks dat het uitvoer-img-element een alt-attribuut mist:

Mapping van custom-image naar img

Als u een mapping tussen custom-image en img aanbiedt, kan Axe DevTools Linter uw aangepaste component als een standaard HTML-element mappen en toegankelijkheidsfouten lokaliseren. U kunt de mapping opgeven door de global-components-configuratieoptie te gebruiken in een axe-linter.yml-configuratiebestand:

global-components:
  custom-image: img

De extensie markeert nu de toegankelijkheidsfout en biedt een tooltip wanneer je met je cursor over de fout zweeft:

Je kunt dezelfde mapping als hierboven ook aangeven met een van deze syntaxis:

global-components:
  custom-image:
    element: img

Of, alternatief, door element af te korten als el:

global-components:
  custom-image:
    el: img

Het toegankelijkheidsprobleem oplossen

U kunt een alt-attribuut aan uw custom-image toevoegen om het toegankelijkheidsprobleem op te lossen:

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

Er is geen fout meer, dus je IDE toont niet langer de rode golvende onderstreping (VS Code getoond):

Mapping van een alternative-text-attribuut

Als uw aangepaste beeldcomponent in plaats daarvan een ander attribuut gebruikt om alternatieve tekst aan te geven, kunt u dat attribuut specificeren in de configuratie. Stel, uw custom-image-component gebruikt een alternative-text-attribuut in plaats van alt, zoals hieronder weergegeven:

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

In dit geval zou u een mapping kunnen specificeren tussen het alternative-text-attribuut en het alt-attribuut zoals getoond met de attributes-array in een axe-linter.yml-bestand zoals hieronder weergegeven:

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

Deze global-components-configuratie verschilt enigszins van de eerdere mapping van één aangepaste component naar één HTML-element. Met alleen elementen gebruikt u een mapping van een sleutel (custom-image) naar een waarde (img). Met de toevoeging van de attributes-array moet u nu de element (of el) eigenschap gebruiken om het uitgezonden HTML-element te specificeren.

Deze verandering lost de fout op, en er wordt geen rode golvende onderstreping weergegeven in je IDE (VS Code getoond).

U kunt ook attributes afkorten als attrs:

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

Speciale Attribuutwaarden: <text> en aria-*

Stel dat u een custom-button-component als volgt gebruikt:

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

(De aangepaste knop zal, met behulp van JavaScript en CSS die hier niet zijn inbegrepen, een div verbergen en tonen.)

Er zijn twee problemen met dit gebruik:

1. Als u deze custom-button-component direct naar een button-element mapt, zal er geen tekstinhoud zijn om op de knop weer te geven. De intentie van de componentauteur is echter dat het message-attribuut als tekstinhoud moet worden gebruikt: <button> waarde van het message-attribuut </button>
2. Het uitgezonden button-element heeft een impliciete rol van button, dus het aria-colindex-attribuut is onjuist en moet worden verwijderd.

Zoals standaard het geval is, zal deze HTML niet resulteren in een fout omdat er geen mapping is tussen custom-button en button. Echter, als u een eenvoudige mapping tussen custom-button en button maakt zoals hieronder weergegeven:

global-components:
  custom-button: button

Je zult twee fouten van je IDE ontvangen (VS Code wordt getoond):

De Speciale <text> Waarde

Om het eerste probleem aan te pakken (tekstinhoud voor het button-element afkomstig van een message-attribuut, hierboven geïdentificeerd als button-name in de tooltip van uw IDE), kunt u de speciale <text>-waarde gebruiken die een attribuut naar de tekstinhoud van het uitgezonden element mappt. In dit geval moet de tekst van het message-attribuut worden gekopieerd naar de tekstinhoud van het uitgezonden button-element.

Om de extensie zo te configureren dat het message-attribuut als tekstinhoud voor het HTML-button-element wordt beschouwd, kunt u de speciale <text>-waarde gebruiken in een axe-linter.yml-configuratiebestand:

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

Omdat u het message-attribuut als <text> hebt gedefinieerd, vertelde u de extensie om dat attribuut te beschouwen als vervanging van tekstuele inhoud van het HTML-button-element met de waarde van het message-attribuut.

Helaas, door de attributes-array te gebruiken, was het enige attribuut dat werd doorgegeven aan het uitgezonden button-element alleen het message-attribuut; alle attributen die niet in de attributes-array staan, worden niet doorgegeven. Dit betekent dat de onjuiste aria-colindex niet werd opgemerkt door de extensie.

Het gebruik van aria-*

U kunt de speciale aria-*-waarde gebruiken om alle ARIA-attributen door te geven, zoals hieronder weergegeven:

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

Deze fout treedt op omdat het button-element een impliciete role="button" heeft en het gebruik van aria-colindex ongeldig is met knoppen. Met aria-* worden alle ARIA-attributen gekopieerd naar het uitgezonden element; dit omvat het kopiëren van het ongeldige aria-colindex-attribuut.

<element>

Met complexe componenten wilt u misschien een ander HTML-element uitzenden dan het standaard element in specifieke gevallen. Bijvoorbeeld, u kunt een knopcomponent hebben die zich typisch als een knop gedraagt en in andere staten als een tijdelijke afbeeldingsruimte. De <element>-waarde stelt u in staat om een attribuut op uw aangepaste component te specificeren dat bepaalt welk element wordt uitgezonden.

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

In dit geval geeft het use-attribuut op de my-button-component aan welk element moet worden uitgezonden. Omdat het uitgezonden img-element geen alt-attribuut bevat, ontvangt u een foutmelding:

Alle Attributen Impliciet Doorvoeren

Als u alleen elementmapping had gebruikt (waarbij de mapping de attributes-array niet gebruikt), zouden standaard alle attributen worden gekopieerd naar het button-element. De configuratie voor dit geval werd eerder getoond:

global-components:
  custom-button: button

Naast de foutmelding die in je IDE wordt getoond (VS Code is hier getoond):

Het bovenstaande voorbeeld laat zien dat een praktische eerste stap bij het beginnen met het controleren van aangepaste componenten zou zijn om te beginnen met een elementmapping (waardoor alle attributen naar het uitgegeven standaard HTML-element worden gekopieerd) en dan te bekijken welke attributen aan de configuratie moeten worden toegevoegd:

1. Of een van de attributen van de aangepaste component naar andere attributen moet worden gemapt.
2. Of u <text> of aria-* moet gebruiken.

Standaard Attributen

Standaardattributen stellen u in staat waarden voor attributen in uw configuratiebestand in te stellen in plaats van één attribuut naar een ander te mappen. Bijvoorbeeld, de volgende voorbeeldconfiguratie toont een custom-menu-component die is gemapt naar een li-element met een role van *menu*:

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

Omdat het role-attribuut een standaardwaarde van *menu* heeft, ingesteld in het configuratiebestand, hoeven gebruikers bij gebruik van de custom-menu-component in hun code geen role-attribuut te specificeren. De implicatie is dat de implementatie van uw aangepaste component deze attributen op het uitvoerelement creëert en hun waarden instelt in plaats van dat gebruikers ze moeten instellen wanneer ze uw component gebruiken.

Optioneel wordt de name-waarde ingesteld op *null* in de configuratie, wat ervoor zorgt dat Axe DevTools Linter eventuele role-attributen negeert die gebruikers op custom-menu hebben gespecificeerd in gelinte code.

Zie ook

Configuratie van Axe DevTools Linter

Aangepaste Componenten en de REST Endpoint

Vooraf Geconfigureerde Componentbibliotheken

Axe DevTools Linter voor React Native

Analyseren van Overtredingen van Aangepaste Componenten in CI/CD-rapporten