Analisi dei Componenti Personalizzati con il Linter di Accessibilità Axe per VS Code o IDE JetBrains

This page is not available in the language you requested. You have been redirected to the English version of the page.

Link to this page copied to clipboard

Una guida per analizzare i componenti personalizzati in VS Code o IDE JetBrains

Not for use with personal data

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

important

Questo articolo è destinato agli utenti di Estensione Axe Accessibility Linter per VS Code e plugin per JetBrains. Se sei un utente dell'endpoint REST di Axe DevTools Linter, vedi Analisi dei Componenti Personalizzati con l'Endpoint REST.

Se desideri leggere una panoramica sull'analisi dei componenti personalizzati, vedi Analisi dei Componenti Personalizzati.

Per utilizzare questa guida, dovresti avere installato quanto segue:

Per Visual Studio Code:

Per IDE JetBrains:

Un Esempio di Errore di Accessibilità

Quando utilizzi l'estensione per analizzare il codice sorgente, gli errori di accessibilità vengono mostrati nel tuo IDE con una sottolineatura ondulata rossa. Ad esempio, il seguente HTML mostra l'uso dell'elemento img senza un attributo alt, che è un errore di accessibilità (mostrato in VS Code).

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

(Questo è un esempio semplificato per dimostrare l'analisi piuttosto che un esempio reale.)

L'estensione evidenzia la riga in errore e fornisce un tooltip quando posizioni il cursore del mouse sull'errore. Poiché questo elemento img non ha un attributo alt, riceverai un errore di accessibilità dall'estensione nel tuo IDE (mostrato in VS Code):

Un Componente Immagine Personalizzato

In questo esempio, uno sviluppatore ha creato un componente personalizzato chiamato custom-image. Il seguente esempio mostra l'uso 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 errori perché non ha una corrispondenza tra custom-image e img anche se l'elemento di output img manca di un attributo alt:

Mappare `custom-image` a `img`

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

global-components:
  custom-image: img

L'estensione ora evidenzia l'errore di accessibilità e fornisce un tooltip quando posizioni il cursore sul errore:

Puoi anche indicare lo stesso mapping illustrato sopra con uno dei seguenti sintassi:

global-components:
  custom-image:
    element: img

Oppure, in alternativa, abbreviando element come el:

global-components:
  custom-image:
    el: img

important

Quando usi una mappatura di elementi, tutti gli attributi del componente personalizzato vengono copiati nell'elemento emesso, e quell'elemento emesso viene analizzato.

Risolvere il Problema di Accessibilità

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

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

Non vi è più alcun errore, quindi il tuo IDE non mostra più la sottolineatura ondulata rossa (mostrato in VS Code):

Mappare un Attributo `alternative-text`

Se il tuo componente immagine personalizzato invece utilizza un altro attributo per indicare il testo alternativo, puoi specificare quell'attributo nella configurazione. Per esempio, supponi che il tuo componente custom-image usi un attributo alternative-text invece di alt, come mostrato di seguito:

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

In questo caso, potresti 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 configurazione global-components è leggermente diversa dalla mappatura precedente di un componente personalizzato a un elemento HTML. Con solo gli elementi, usi 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 risolve l'errore, e non viene mostrata la sottolineatura ondulata rossa nel tuo IDE (mostrato in VS Code).

important

Poiché hai specificato l'array attributes nella configurazione, quando l'estensione mappa da custom-image a img, solo gli attributi corrispondenti a quelli nell'array attributes vengono copiati all'elemento HTML emesso.

Puoi anche abbreviare attributes come attrs:

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

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

Supponiamo che tu utilizzi un componente custom-button 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 che non sono inclusi qui, nasconderà e mostrerà un div.)

Ci sono due problemi con questo utilizzo:

Se mappi direttamente questo componente custom-button a un elemento button, non ci sarà alcun contenuto testuale da visualizzare sul pulsante. L'intento dell'autore del componente, tuttavia, è che l'attributo message venga utilizzato come contenuto testuale: <button> valore dell'attributo message </button>
L'elemento button emesso ha un ruolo implicito di button quindi l'attributo aria-colindex è errato e dovrebbe essere rimosso.

Come predefinito, questo HTML non genererà un errore perché non c'è un mapping tra custom-button e button. Tuttavia, se crei un semplice mapping tra custom-button e button come mostrato di seguito:

global-components:
  custom-button: button

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

Il valore speciale `<text>`

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

Per configurare l'estensione affinché l'attributo message sia considerato come contenuto testuale per l'elemento HTML button, puoi 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 quell'attributo come sostituzione del contenuto testuale dell'elemento HTML button con il valore dell'attributo message.

Sfortunatamente, utilizzando l'array attributes, l'unico attributo che è stato passato al solo elemento button emesso è stato l'attributo message; qualsiasi attributo non presente nell'array attributes non viene trasmesso. Ciò significa che l'errore aria-colindex non è stato rilevato dall'estensione.

Utilizzo di `aria-*`

Puoi utilizzare il valore speciale aria-* per trasmettere 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 role="button" implicito e l'utilizzo di aria-colindex è invalido con i pulsanti. Con aria-*, tutti gli attributi ARIA vengono copiati sull'elemento emesso; questo include la copia dell'attributo aria-colindex non valido.

`<element>`

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

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

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

Passaggio implicito di tutti gli attributi

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

global-components:
  custom-button: button

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

L'esempio sopra mostra che un primo passo pratico quando si inizia a fare lint di componenti personalizzati è partire con un mapping di elementi (copiando così tutti gli attributi sull'elemento HTML standard emesso) e quindi vedere quali attributi devono essere aggiunti alla configurazione:

Se uno degli attributi del componente personalizzato debba essere mappato a diversi attributi.
Se devi utilizzare <text> o aria-*.

Attributi predefiniti

Gli attributi predefiniti ti permettono di impostare valori per gli attributi nel tuo file di configurazione piuttosto che 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. L'implicazione è che l'implementazione del tuo componente personalizzato crea questi attributi sull'elemento di output e imposta i loro valori anziché richiedere agli utenti di impostarli quando utilizzano il tuo componente.

Facoltativamente, il valore name è impostato su null nella configurazione, il che causa che Axe DevTools Linter ignori qualsiasi attributo role che gli utenti hanno specificato su custom-menu nel codice analizzato.

note

Il valore specificato con default dovrebbe essere una stringa.