Verifica di componenti personalizzati con l'axe Accessibility Linter per VS Code o JetBrains IDE

Questo articolo mostra come configurare l'estensione axe Accessibility Linter per Visual Studio Code (VS Code) o il plugin per JetBrains per individuare errori di accessibilità nei componenti personalizzati.

Per una panoramica sul linting dei componenti personalizzati, vedere Linting dei componenti personalizzati.

Per utilizzare questa procedura dettagliata, è necessario che sia installato quanto segue:

Per Visual Studio Code:

• Visual Studio Code
• L'estensione axe Accessibility Linter per VS Code

Per gli IDE JetBrains:

• IntelliJ IDEA Ultimate

  O

• WebStorm

• Il plugin axe Accessibility Linter per JetBrains

Un esempio di errore di accessibilità

Quando si utilizza l'estensione per eseguire il lint del codice sorgente, eventuali errori di accessibilità vengono visualizzati nell'IDE con una sottolineatura ondulata rossa. Ad esempio, il seguente codice HTML mostra l'utilizzo dell'elemento img senza l'attributo alt , che costituisce un errore di accessibilità (mostrato in VS Code).

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

(Questo è un esempio semplificato per dimostrare il linting, più che un esempio concreto della vita reale.)

L'estensione evidenzia la riga contenente l'errore e fornisce un suggerimento quando si passa il cursore del mouse sull'errore. Poiché questo elemento non ha un attributo, verrà visualizzato un errore di accessibilità dall'estensione nel tuo IDE (viene mostrato VS Code): img alt

Un componente immagine personalizzato

Per questo esempio, uno sviluppatore ha creato un componente personalizzato denominato custom-image. L'esempio seguente mostra un esempio di utilizzo del componente personalizzato: custom-image

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

In questo esempio, il componente custom-image crea un elemento img con un attributo path (che viene mappato a un attributo src dall'implementazione del controllo personalizzato). L'estensione non mostra alcun errore perché non ha alcuna mappatura tra custom-image e img anche se all'elemento output img manca un attributo alt :

Mappatura custom-image con img

Se fornisci una mappatura tra custom-image e img, axe DevTools Linter può mappare il tuo componente personalizzato come un elemento HTML standard e individuare gli errori di accessibilità. È possibile specificare la mappatura utilizzando l' global-components opzione di configurazione in un axe-linter.yml file di configurazione:

global-components:
  custom-image: img

L'estensione ora evidenzia l'errore di accessibilità e fornisce un suggerimento quando si passa il cursore sopra l'errore:

È anche possibile indicare la stessa mappatura di cui sopra con una di queste sintassi:

global-components:
  custom-image:
    element: img

Oppure, in alternativa, abbreviando element come el:

global-components:
  custom-image:
    el: img

Risolvere il problema di accessibilità

Puoi aggiungere un alt attributo al tuo custom-image per risolvere il problema di accessibilità:

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

Non c'è più un errore, quindi il tuo IDE non visualizza più la linea di contorno ondulata rossa (mostrato VS Code):

Mappatura di un attributo alternative-text

Se invece il componente immagine personalizzato utilizza un attributo diverso per indicare un testo alternativo, è possibile specificare tale attributo nella configurazione. Ad esempio, supponiamo che il tuo componente utilizzi un attributo invece di un altro, come mostrato di seguito: custom-image alternative-text alt

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

In questo caso, è possibile specificare una mappatura tra l'attributo alternative-text e l'attributo alt come mostrato con l'array attributes in un file axe-linter.yml come mostrato di seguito:

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

Questa global-components configurazione è leggermente diversa dalla precedente mappatura di un componente personalizzato su un elemento HTML. Con solo elementi, si utilizza una mappatura da una chiave (custom-image) a un valore (img). Con l'inclusione dell'array attributes , ora è necessario utilizzare la proprietà element (o el) per specificare l'elemento HTML emesso.

Questa modifica corregge l'errore e non viene più visualizzata alcuna sottolineatura rossa ondulata nell'IDE (viene visualizzato VS Code).

Puoi anche abbreviare attributes come attrs:

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

Valori degli attributi speciali: <text> e aria-*

Supponiamo di utilizzare un custom-button componente come segue:

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

(Il pulsante personalizzato, utilizzando JavaScript e CSS non inclusi qui, nasconderà e mostrerà un div.)

Ci sono due problemi con questo utilizzo:

1. Se si mappa questo custom-button componente direttamente a un button elemento, non verrà visualizzato alcun contenuto di testo sul pulsante. L'intento dell'autore del componente, tuttavia, è che l'attributo message venga utilizzato come contenuto di testo: <button> *valore dell'attributo message * </button>
2. L'elemento emesso button ha un ruolo implicito di button quindi l'attributo aria-colindex è errato e dovrebbe essere rimosso.

Come impostazione predefinita, questo codice HTML non genererà errori perché non esiste alcuna mappatura tra custom-button e button. Tuttavia, se si crea una mappatura semplice tra custom-button e button come mostrato di seguito:

global-components:
  custom-button: button

Riceverai due errori dal tuo IDE (viene mostrato VS Code):

Il valore speciale <text>

Per risolvere il primo problema (contenuto di testo per l'elemento button proveniente da un attributo message , identificato sopra come nome-pulsante nella descrizione comandi del tuo IDE), puoi usare il valore speciale <text> che mappa un attributo al contenuto di testo dell'elemento emesso. In questo caso il testo dell'attributo message dovrebbe essere copiato nel contenuto di testo dell'elemento emesso button .

Per configurare l'estensione in modo che l'attributo message sia considerato come contenuto di testo per l'elemento HTML button , è possibile utilizzare il valore speciale <text> in un file di configurazione axe-linter.yml :

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

Poiché hai definito l'attributo message come <text>, hai indicato all'estensione di considerare tale attributo come sostituto del contenuto testuale dell'elemento HTML button con il valore dell'attributo message .

Sfortunatamente, utilizzando l' attributes array, l'unico attributo che veniva passato all'elemento button emesso era l' message attributo; tutti gli attributi non presenti nell' attributes array non venivano passati. Ciò significa che l'errore aria-colindex non è stato rilevato dall'estensione.

Utilizzo di aria-*

È possibile utilizzare il valore speciale aria-* per passare tutti gli attributi ARIA, come mostrato di seguito:

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

Questo errore si verifica perché l'elemento button ha un attributo implicito role="button" e l'uso di questo attributo con i pulsanti non è valido. aria-colindex Con l'attributo aria-*, all ARIA attributes are copied to the emitted element; this includes copying the invalid aria-colindex.

<element>

Nel caso di componenti complessi, in casi specifici potrebbe essere necessario emettere un elemento HTML diverso da quello predefinito. Ad esempio, potresti avere un componente pulsante che in genere si comporta come un pulsante e, in altri stati, come un'immagine segnaposto. Il valore <element> consente di specificare un attributo sul componente personalizzato che determina l'elemento emesso.

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

In questo caso, l'attributo use del componente my-button indica l'elemento da emettere. Poiché l'elemento emesso img non contiene un attributo alt , verrà visualizzato un errore:

Passaggio implicito di tutti gli attributi

Se avessi utilizzato solo la mappatura degli elementi (dove la mappatura non utilizza l'array attributes ), tutti gli attributi verrebbero, per impostazione predefinita, copiati nell'elemento button . La configurazione per questo caso è stata mostrata in precedenza:

global-components:
  custom-button: button

Insieme all'errore mostrato nel tuo IDE (VS Code è mostrato qui):

L'esempio sopra riportato mostra che un primo passo pratico quando si inizia a eseguire il lint di componenti personalizzati sarebbe quello di iniziare con una mappatura degli elementi (copiando quindi tutti gli attributi nell'elemento HTML standard emesso) e quindi vedere quali attributi devono essere aggiunti alla configurazione:

1. Se uno qualsiasi degli attributi del componente personalizzato debba essere mappato su attributi diversi.
2. Se devi usare <text> o aria-*.

Attributi predefiniti

Gli attributi predefiniti consentono di impostare i valori per gli attributi nel file di configurazione anziché mappare un attributo su un altro. Ad esempio, la seguente configurazione di esempio mostra un componente custom-menu mappato a un elemento li con un role di menu:

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

Poiché l'attributo role ha un valore predefinito di menu, impostato nel file di configurazione, gli utenti non devono specificare un attributo role quando utilizzano il componente custom-menu nel loro codice. Ciò implica che l'implementazione del componente personalizzato crea questi attributi sull'elemento di output e ne imposta i valori anziché richiedere agli utenti di impostarli quando utilizzano il componente.

Facoltativamente, il valore name viene impostato su null nella configurazione, il che fa sì che axe DevTools Linter ignori tutti gli role attributi che gli utenti hanno specificato custom-menu nel codice sottoposto a linting.

Vedere anche

Configurazione di axe DevTools Linter

Componenti personalizzati ed endpoint REST

Librerie di componenti preconfigurate

axe DevTools Linter per React Native