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 van 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 (getoond 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 lijn met de fout en biedt een tooltip wanneer u met uw 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 gemaakt genaamd custom-image. Het volgende voorbeeld toont een voorbeeld van het gebruik van de custom-image aangepaste 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 het aangepaste controle-element). De extensie toont geen fout omdat de extensie geen mapping heeft tussen custom-image en img hoewel het uitvoer img element een alt attribuut mist:

Mapping custom-image naar img

Als je een mapping tussen custom-image naar img, kan Axe DevTools Linter je aangepaste component als een standaard HTML-element mappen en toegankelijkheidsfouten vinden. Je kunt de mapping specificeren met de global-components configuratieoptie 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, als alternatief, door af te korten element als el:

global-components:
  custom-image:
    el: img

Het toegankelijkheidsprobleem oplossen

Je kunt een alt attribuut toevoegen aan je custom-image 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):

Een attribuut mappen alternative-text

Als je aangepaste afbeeldingscomponent in plaats daarvan een ander attribuut gebruikt om alternatieve tekst aan te geven, kun je dat attribuut in de configuratie specificeren. Stel bijvoorbeeld dat je custom-image component een alternative-text attribuut gebruikt in plaats van alt, zoals hieronder getoond:

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

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

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

Deze global-components configuratie verschilt enigszins van de eerdere mapping van een aangepast component naar een HTML-element. Met alleen elementen gebruik je een mapping van een sleutel (custom-image) naar een waarde (img). Met de opname van de attributes array, ben je nu verplicht om de element (of el) eigenschap te 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).

Je kunt ook afkorten attributes als attrs:

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

Speciale attribuutwaarden: <text> en aria-*

Stel dat je 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 JavaScript en CSS die hier niet zijn inbegrepen, een divverbergen en tonen.)

Er zijn twee problemen met dit gebruik:

1. Als je deze custom-button component direct koppelt aan een button element, zal er geen tekstinhoud op de knop worden weergegeven. De intentie van de maker van de component 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 gebruikelijk zal deze HTML niet in een fout resulteren omdat er geen koppeling is tussen custom-button en button. Maar als je een eenvoudige koppeling maakt tussen custom-button en button zoals hieronder getoond:

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 je IDE), kun je de speciale <text> waarde gebruiken die een attribuut koppelt aan de tekstinhoud van het uitgezonden element. In dit geval moet de tekst van het message attribuut worden gekopieerd naar de tekstinhoud van het uitgezonden button element.

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

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

Omdat je het message attribuut hebt gedefinieerd als <text>, heb je de extensie verteld om dat attribuut te beschouwen als het vervangen van de tekstuele inhoud van het HTML button element met de waarde van het message attribuut.

Helaas, door gebruik te maken van de attributes reeks, werd alleen het attribuut dat doorgestuurd werd naar het uitgezonden button element alleen het message attribuut; alle andere attributen die niet in de attributes reeks staan worden niet doorgestuurd. Dit betekent dat de onjuiste aria-colindex niet werd opgevangen door de extensie.

Gebruik van aria-*

Je kunt de speciale aria-* waarde om alle ARIA-attributen door te geven, zoals hieronder getoond:

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 naar het uitgegeven element gekopieerd; dit omvat het kopiëren van het ongeldige aria-colindex attribuut.

<element>

Bij complexe componenten wil je misschien een ander HTML-element uitgeven dan het standaardelement in specifieke gevallen. Bijvoorbeeld, je hebt een knopcomponent die zich meestal gedraagt als een knop en, in andere staten, als een plaatsaanduidingsafbeelding. De <element> waarde stelt je in staat een attribuut te specificeren op je aangepaste component dat het uitgegeven element bepaalt.

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

In dit geval geeft het use attribuut op het my-button component het element aan dat moet worden uitgegeven. Omdat het uitgegeven img element geen alt attribuut bevat, ontvang je een foutmelding:

Alle Attributen Impliciet Doorvoeren

Als je 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 je moet gebruiken <text> of aria-*.

Standaard Attributen

Standaardattributen stellen je in staat om waarden voor attributen in je configuratiebestand in te stellen in plaats van één attribuut naar een ander te mappen. Bijvoorbeeld, de volgende voorbeeldconfiguratie toont een custom-menu component gemapped 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 heeft van *menu*, die is ingesteld in het configuratiebestand, hoeven gebruikers geen role attribuut op te geven wanneer ze de custom-menu component in hun code gebruiken. De implicatie is dat de implementatie van je aangepaste component deze attributen op het uitvoerelement creëert en hun waarden instelt in plaats van gebruikers te vereisen deze in te stellen wanneer ze je component gebruiken.

Optioneel wordt de name waarde ingesteld op *null* in de configuratie, wat ervoor zorgt dat Axe DevTools Linter alle role attributen negeert die gebruikers hebben gespecificeerd op custom-menu in gecontroleerde 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