Configurazione di Axe DevTools Linter

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 di riferimento per configurare Axe DevTools Linter

Not for use with personal data

Questo articolo fornisce un riferimento per le opzioni di configurazione di Axe DevTools Linter.

Panoramica

Il endpoint dell'API REST utilizza JSON per la configurazione, e l' estensione Axe Accessibility Linter per VS Code, il plugin JetBrains, e il Connettore Axe DevTools Linter usano YAML per la configurazione. Esempi di configurazioni di Axe DevTools Linter in JSON e YAML sono mostrati in questa guida.

Esempi di Configurazione

Il seguente esempio YAML dimostra una configurazione semplice che utilizza l'opzione rules per l'uso con l'estensione Axe Accessibility Linter per VS Code, il plugin JetBrains o il Connettore Axe DevTools Linter:

rules:
  html-has-lang: false

Il seguente esempio dimostra la stessa configurazione come un oggetto di richiesta completo con l'opzione rules per il servizio REST di Axe DevTools Linter con il suo oggetto config incorporato evidenziato:

{
  "source": "<html></html>",
  "filename": "file.html",
  "config": {    "rules": {      "html-has-lang": false    },    "exclude": [],
    "tags": []
  }
}

In entrambi i casi, queste configurazioni causano che Axe DevTools Linter ignori gli errori di accessibilità quando l'elemento html manca di un attributo lang . (Vedi la regola html-has-lang per maggiori informazioni.)

note

Per tutti gli esempi JSON in questo articolo, l'oggetto config è incluso per fornire un riferimento di posizione per la configurazione.

Le sezioni seguenti descrivono ognuna delle opzioni di configurazione e forniscono esempi del loro utilizzo.

Ordine di Ricerca del File di Configurazione

L'estensione Axe Accessibility Linter per VS Code, il plugin JetBrains, e il Connettore Axe DevTools Linter (quando utilizzati con l'opzione --config senza parametro) cercheranno la directory corrente e le directory genitrici per un file di axe-linter.yml configurazione nella struttura delle directory del progetto e utilizzeranno il primo che trovano. È utile posizionare un file di configurazione alla radice del progetto che contenga la configurazione predefinita e sostituirlo (se necessario) con file di configurazione in diverse sottodirectory. Puoi anche posizionare un file di configurazione nella tua home directory che sarà usato di default se non ci sono file di configurazione nel tuo progetto.

important

I file di configurazione non vengono uniti. Il primo trovato è l'unico utilizzato.

I passaggi per individuare il file di axe-linter.yml configurazione da utilizzare sono:

Usa il file di configurazione nella directory corrente (la directory che contiene il file in fase di modifica con VS Code, un IDE JetBrains, o la directory corrente del prompt dei comandi con il Connettore Axe DevTools Linter).
Se non viene trovato alcun file di configurazione al primo passaggio, cerca nelle directory genitrici fino a quando non si trova un file di axe-linter.yml configurazione, fermandoti alla tua cartella home se il progetto è nella tua struttura home o alla directory radice se è al di fuori della tua cartella home.
Utilizza un file di axe-linter.yml configurazione situato nella tua home directory (anche se il tuo progetto si trova in una directory al di fuori della tua cartella home o su un'altra unità su Windows). Ad esempio, questi sono i file tipici utilizzati:
- /home/username/axe-linter.yml (Linux)
- /Users/username/axe-linter.yml (macOS)
- C:\Users\username\axe-linter.yml (Windows)

La ricerca si interrompe quando viene trovato il primo file di axe-linter.yml .

Riepilogo della Configurazione di Axe DevTools Linter

Prodotto	Tipo di Configurazione	Descrizione
Estensione Axe Accessibility Linter per VS Code o il plugin JetBrains	Un file YAML chiamato `axe-linter.yml`	Vedi Ordine di Ricerca dei File di Configurazione.
Axe Linter Connector	Un file YAML chiamato `axe-linter.yml`	Segui i passaggi in Ordine di Ricerca dei File di Configurazione quando usato con l'opzione `--config` senza parametro.
Axe Linter Connector	Un file YAML chiamato nomefile	Quando usato con `--config` nomefile.
Axe Linter REST API	Oggetto di configurazione JSON	Vedi L'oggetto di configurazione.

Opzioni di Configurazione

`element`

L'opzione element permette di cambiare l'elemento emesso in base al valore dell'attributo specificato nel tuo componente. Per esempio, potresti far emettere a un componente personalizzato un elemento img in alcuni casi e un elemento button in altri casi, permettendo così casi d'uso più complessi.

La configurazione di esempio sottostante specifica che l'attributo as sul componente my-button può cambiare l'elemento emesso dal valore predefinito di button:

YAML:

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

JSON:

{
  "config": {
    "global-components": {
      "my-button": {
        "element": "button",
        "attributes": [
          {
            "as": "<element>"
          }
        ]
      }
    }
  }
}

L'uso di esempio qui sotto emette un elemento img invece del predefinito elemento button perché l'attributo as specifica l'elemento di output:

<my-button as="img"></my-button>

L'elemento di output img verrà poi analizzato e risulterà mancante di un attributo alt .

`exclude`

L'opzione exclude impedisce che i file corrispondenti vengano analizzati. Puoi usare wildcard e glob. Il suo uso è principalmente per l'estensione VS Code o il plugin JetBrains ed è ignorato dall'endpoint REST.

exclude: *.tmp

`global-components`

L'opzione di configurazione global-components dirige Axe DevTools Linter su come mappare i tuoi componenti personalizzati o componenti da librerie di terze parti agli elementi HTML nativi, permettendoti di analizzare i tuoi componenti come se fossero elementi HTML nativi. Ad esempio, la seguente configurazione tratterà tutti i componenti personalizzati DqButton come se fossero elementi HTML nativi button . Questo mappa automaticamente ogni attributo su DqButton a button, richiedendo così un nome accessibile per tutti i componenti DqButton .

YAML:

global-components:
  DqButton: button

JSON:

{
  "config": {
    "global-components" {
      "DqButton": "button"
    }
  }
}

In alternativa, per i componenti che non mappano tutti gli attributi ai componenti HTML nativi, puoi elencare gli attributi richiesti per la conformità all'accessibilità usando l'opzione attributes . Puoi elencare gli attributi supportati dal componente e rinominare gli attributi. Ci sono tre valori speciali:

Il valore aria-* indica ad Axe DevTools Linter che tutti gli attributi che iniziano con aria- sono mappati all'elemento HTML nativo così come sono. Nota che il valore termina con un asterisco.
Il valore <text> indica ad Axe DevTools Linter che una proprietà è usata per impostare il contenuto (il valore tra i tag di apertura e chiusura) dell'elemento HTML nativo.
Il valore <element> indica ad Axe DevTools Linter che l'elemento emesso può assumere il valore di questo attributo, il che ti permette di cambiare l'elemento emesso a seconda del valore dell'attributo specificato.

Il seguente esempio YAML mostra tutti i valori che possono essere usati con global-components:

global-components:
  DqButton:
    element: button
    # Ignore all attributes on <DqButton> except the following:
    attributes:
      - role # Map the role attribute from <DqButton /> to <button />
      - aria-* # Map all attributes starting with aria-
      - action: type # <DqButton action="submit" /> maps to <button type="submit" />
      - label: <text> #  <DqButton label="ABC" /> emits <button>ABC</button>
      - as: <element> # <DqButton as="img" /> emits <img> instead of <button>. (You don't have to use *as* for the attribute name.)

Una versione equivalente JSON (all'interno dell'oggetto config ) è la seguente:

{
  "config": {
    "global-components": {
      "DqButton": {
        "element": "button",
        "attributes": [
          "role",
          "aria-*",
          {
            "action": "type"
          },
          {
            "label": "<text>"
          },
          {
            "as": "<element>"
          }
        ]
      }
    }
  }
}

Solo gli attributi rilevanti per l'accessibilità devono essere nella lista attributes . I nomi degli elementi sono case-sensitive. Il caso Camel, come mostrato sopra, è comunemente usato con file .jsx, ma può essere usato anche il caso Kebab (che è utilizzato in Vue, Angular e negli elementi HTML personalizzati).

Per tutorial che mostrano come utilizzare il mapping dei componenti personalizzati, consulta Linting dei Componenti Personalizzati.

`global-libraries`

Axe DevTools Linter ha supporto integrato per diverse librerie e framework di componenti popolari.

Le seguenti librerie sono attualmente supportate:

react-native
@mui/material
@deque/cauldron-react

Per abilitare il linting dei componenti della libreria, aggiungi il nome del pacchetto NPM della libreria all'array global-libraries per i file di configurazione YAML:

global-libraries:
  - '@mui/material'
  - '@deque/cauldron-react'
  - react-native

note

Devi racchiudere tra virgolette @mui/material e @deque/cauldron-react in YAML perché @ è interpretato come un carattere riservato.

O la configurazione equivalente in JSON è mostrata di seguito:

{
  "config": {
    "global-libraries": [
      "@mui/material"
    ]
  }
}

Qualsiasi componente con lo stesso nome di un componente dalla libreria globale sarà trattato come quel componente della libreria, permettendo il ri-esportazione e la dichiarazione dei componenti senza perdere il loro mapping.

Per maggiori informazioni, consulta Librerie di Componenti Preconfigurate.

`overrides`

Puoi modificare come Axe DevTools Linter è configurato per ogni file utilizzando l'opzione di configurazione overrides . Più sostituzioni sullo stesso file vengono risolte in ordine. Cioè, l'ultima sostituzione elencata ha la precedenza più alta.

Attualmente, solo la sostituzione linter è supportata ed è usata per cambiare il linter utilizzato sui file corrispondenti.

overrides:
  - files: # An array or single string of filename(s) or glob pattern(s) that match this override setting
      - vue/**/*.html
    linter: vue # Specify that all files that match the pattern should be linted as Vue
  - files: php/**/*.html
    linter: null # Disable Axe Linter for these files

`rules`

Puoi consentire o vietare le regole individualmente con l'opzione rules nella tua configurazione. Ogni regola può essere impostata su true (abilitata, riportata come un errore — l'impostazione predefinita), false (disabilitata), o warn (abilitata, riportata come un avviso):

rules:
  some-rule: false   # turn off rule
  other-rule: true   # turn on rule (default)
  color-contrast: warn  # report violations as warnings instead of errors

Oppure nell'oggetto config della tua richiesta REST JSON:

{
  "config": {
    "rules": {
      "some-rule": false,
      "other-rule": true,
      "color-contrast": "warn"
    }
  }
}

Per informazioni su come utilizzare rules con l'API REST, consulta La proprietà delle regole. Se vuoi usare rules con il connettore Axe DevTools Linter, consulta File di configurazione. Per vedere le regole che segue Axe DevTools Linter, consulta Regole di Accessibilità. Consulta tag qui sotto per ulteriori informazioni sull'uso dell'opzione tags per escludere collezioni di regole dal processo.

Per sopprimere regole per linee specifiche in un file sorgente senza modificare questo file di configurazione, consulta Sopprimere le Regole di Linter con Direttive Inline.

`tags`

Puoi vietare gruppi di regole basati sullo standard WCAG con cui sono associati usando l'opzione tags :

tags: # Disallow all rules other than WCAG 2.1 A, WCAG 2.1 AA, and best practices.
  - wcag21a
  - wcag21aa
  - best-practices

Vedi Anche

Per un riferimento alle API REST fornite da Axe DevTools Linter, consulta Il Riferimento all'API REST di Axe DevTools Linter.
Per guide passo-passo sulla creazione di mappature di componenti personalizzati, consulta Linting dei Componenti Personalizzati.
Per scaricare l'estensione per VS Code, consulta Axe Accessibility Linter.
Per maggiori informazioni sul plugin JetBrains, consulta Usare il Plugin con le IDE di JetBrains.