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 il estensione Axe Accessibility Linter per VS Code, il plugin JetBrains, e il Connettore Axe DevTools Linter usano YAML per la configurazione. In questa guida sono mostrati esempi di configurazioni di Axe DevTools Linter sia in JSON che in YAML.

Esempi di Configurazione

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

rules:
  html-has-lang: false

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

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

In entrambi i casi, queste configurazioni fanno sì 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 una posizione di riferimento per la configurazione.

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

Ordine di Ricerca dei File di Configurazione

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

important

I file di configurazione trovati da questa ricerca non vengono uniti insieme. Il primo trovato è l'unico utilizzato. Per combinare le impostazioni di più file, fai sì che il file di configurazione erediti dagli altri con l'opzione extends.

I passaggi per individuare il file di configurazione axe-linter.yml 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 trovata una configurazione al passaggio 1, cerca nelle directory genitori fino a trovare un file di configurazione axe-linter.yml, fermandoti alla cartella home se il progetto è nella tua struttura di directory home o alla directory radice se è fuori dalla tua cartella home.
Usa un file di configurazione axe-linter.yml situato nella tua directory home (anche se il tuo progetto si trova in una directory fuori dalla tua cartella home o su un altro drive 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 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 denominato `axe-linter.yml`	Vedi Ordine di Ricerca dei File di Configurazione.
Axe Linter Connector	Un file YAML denominato `axe-linter.yml`	Segue i passaggi in Ordine di Ricerca dei File di Configurazione quando usato con l'opzione `--config` senza parametro.
Axe Linter Connector	Un file YAML denominato 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 consente di cambiare l'elemento emesso in base al valore dell'attributo specificato del tuo componente. Ad esempio, potresti avere un componente personalizzato che emette un elemento img in certi casi e un elemento button in altri casi, permettendo usi più complessi.

La configurazione d'esempio qui sotto specifica che l'attributo as sul componente my-button può cambiare l'elemento emesso dal 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 dell'esempio riportato di seguito emette un elemento img invece dell'elemento predefinito button perché l'attributo as specifica l'elemento di output:

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

L'elemento di output img sarà quindi analizzato e risulterà privo di un attributo alt.

`exclude`

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

exclude: *.tmp

`enterpriseId`

Il campo facoltativo enterpriseId accetta una stringa che è associata agli eventi di analisi dell'utilizzo per l'attribuzione aziendale. La maggior parte degli utenti non avrà bisogno di impostare questo valore; potrebbe essere richiesto dal tuo rappresentante dell'account Deque. Questo campo viene ignorato per le implementazioni on-premise.

enterpriseId: 'acme-corp'

`extends`

L'opzione extends consente a un file axe-linter.yml di ereditare le sue impostazioni da uno o più file di configurazione genitori, in modo che una base condivisa possa risiedere in un unico luogo anziché essere copiata in ogni progetto. Accetta un singolo percorso file o un array di percorsi file ed è disponibile nella versione 4.13.0 e successive dell'estensione Axe Accessibility Linter per VS Code, il plugin di JetBrains e Axe DevTools Linter Connector.

extends: ./axe-linter.base.yml
rules:
  color-contrast: warn

Per ereditare da più di un file, usa un array:

extends:
  - ./axe-linter.base.yml
  - ../shared/team-rules.yml

I percorsi vengono risolti rispetto al file che contiene l'opzione extends, non rispetto alla directory da cui hai avviato il linter. Sono accettati anche i percorsi assoluti. I file genitori non devono necessariamente essere chiamati axe-linter.yml, e un file genitore può a sua volta utilizzare extends per ereditare da un altro file.

note

Non sono supportati i nomi di pacchetti nudi (come @my-org/axe-linter-config) e gli URL remoti (come https://example.com/axe-linter.yml). Possono essere utilizzati solo percorsi di file relativi e assoluti.

Come vengono combinati le impostazioni ereditate

I file genitori vengono letti da sinistra a destra, e la tua configurazione viene applicata per ultima, quindi prevale in caso di conflitto. Ogni opzione viene combinata come segue:

Opzione	Come viene combinata
`rules`	Unita per ID della regola, e il tuo valore prevale. Poiché ogni regola è abilitata e riportata come errore di default (vedi `rules`), un file genitore utilizza questa opzione per disabilitare le regole o segnalarle come avvisi, e la tua configurazione può modificare una qualsiasi di tali decisioni, inclusa la rimpostazione di una regola su `true` per ripristinare il reporting degli errori di default.
`tags`	Combinata con i valori del genitore, con i duplicati rimossi.
`exclude`	Combinata con i valori del genitore, con i duplicati rimossi.
`global-libraries`	Combinata con i valori del genitore, con i duplicati rimossi.
`global-components`	Unita per nome del componente. Una voce nella tua configurazione sostituisce completamente una voce genitore con lo stesso nome anziché essere unita ad essa, quindi ripetere un nome di componente significa ripetere tutte le impostazioni di quel componente.
`overrides`	Combinata, con le voci del genitore per prime, seguite dalle tue.
Qualsiasi altra opzione, come `enterpriseId`	Il tuo valore prevale, e il genitore fornisce il valore per qualsiasi opzione che ometti.

important

Se un file genitore imposta enterpriseId e la tua configurazione non lo fa, l'utilizzo del tuo progetto viene conteggiato sotto l'ID aziendale del genitore. Imposta enterpriseId nella tua configurazione se hai bisogno di un valore diverso.

Limiti e gestione degli errori

Un file di configurazione non può estendere se stesso, né direttamente né attraverso una catena di file genitori. Le catene sono limitate a 10 livelli di profondità, e una singola configurazione può ereditare da non più di 100 file genitori in totale.

Se un file genitore manca, non è un YAML valido, o contiene un'impostazione non valida, Axe DevTools Linter riporta un errore nominando il file che ha causato il problema. In VS Code e JetBrains IDEs, appare una notifica e il linting continua utilizzando la configurazione di default. Axe DevTools Linter Connector riporta l'errore ed esce con il codice di uscita 3 (vedi Codici di uscita).

`global-components`

L'opzione di configurazione global-components indica ad Axe DevTools Linter come mappare i tuoi componenti personalizzati o i componenti di librerie di terze parti agli elementi HTML nativi, consentendoti di analizzare i tuoi componenti come se fossero elementi HTML nativi. Ad esempio, la configurazione seguente tratterà tutti i componenti personalizzati DqButton come se fossero elementi HTML nativi button. Questo mappa automaticamente ogni attributo su DqButton a button, richiedendo quindi 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 come sono. Nota che il valore termina con un asterisco.
Il valore <text> indica ad Axe DevTools Linter che una proprietà viene utilizzata per impostare il contenuto (il valore tra i tag aperti e chiusi) dell'elemento HTML nativo.
Il valore <element> indica ad Axe DevTools Linter che l'elemento emesso può prendere il valore di questo attributo, il che ti consente 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 JSON equivalente (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 fanno distinzione tra maiuscole e minuscole. Il camel case, come mostrato sopra, è comunemente usato con i file .jsx, ma il kebab case (che è usato in Vue, Angular e elementi personalizzati HTML) può essere utilizzato.

Per esempi dettagliati su come utilizzare la mappatura dei componenti personalizzati, vedi Linting dei Componenti Personalizzati. Per un esempio passo a passo di costruzione e verifica di una configurazione per una libreria di componenti, inclusi componenti che non rendono alcun elemento proprio, vedi Linting dei Salesforce Lightning Web Components (LWC).

`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 l'analisi 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

È necessario citare @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 ulteriori informazioni, vedi Librerie di Componenti Preconfigurate.

`overrides`

Puoi cambiare come Axe DevTools Linter è configurato per file usando l'opzione di configurazione overrides. Più sovrascritture sullo stesso file vengono risolte in ordine. Cioè, l'ultima sovrascrittura elencata ha la precedenza più alta.

Attualmente, solo la sovrascrittura linter è supportata ed è utilizzata per cambiare l'analizzatore usato 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`

Ogni regola è abilitata e segnalata come errore per impostazione predefinita. Usa l'opzione rules per modificare il modo in cui le singole regole vengono gestite: imposta una regola su false per disabilitarla, oppure su warn per segnalarla come avviso anziché errore. Elencare una regola non limita l'analisi lint alle regole che elenchi, quindi non è necessario elencare le regole che vuoi mantenere. Usa invece tag per limitare l'analisi lint a un gruppo di regole.

rules:
  some-rule: false      # turn off rule
  color-contrast: warn  # report violations as warnings instead of errors

Oppure nell'oggetto config nella tua richiesta JSON REST:

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

Per informazioni sull'uso di rules con l'API REST, vedi La proprietà delle regole. Se desideri usare rules con il connettore Axe DevTools Linter, vedi File di configurazione. Per vedere le regole che Axe DevTools Linter segue, vedi Regole di accessibilità. Vedi tag qui sotto per ulteriori informazioni sull'uso dell'opzione tags per escludere collezioni di regole dall'elaborazione.

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

`tags`

Puoi selezionare le regole come un gruppo, in base allo standard di accessibilità a cui sono associate, utilizzando l'opzione tags. Una regola viene verificata se porta uno dei tag che elenchi, e ogni regola che non ne porta nessuno viene disabilitata:

tags: # Check only WCAG 2.0 A, WCAG 2.0 AA, and best-practice rules.
  - wcag2a
  - wcag2aa
  - best-practice

important

Poiché elencare un tag disabilita ogni regola che non lo porta, un insieme ristretto di tag disabilita la maggior parte delle regole. La maggior parte delle regole verificate da Axe DevTools Linter porta wcag2a, quindi una configurazione che elenca solo i tag WCAG 2.1 lascia disabilitate quasi tutte. Per i tag che puoi utilizzare, vedi Tag.

Vedi Anche

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

Configurazione di Axe DevTools Linter

Panoramica

Esempi di Configurazione

Ordine di Ricerca dei File di Configurazione

Riepilogo della Configurazione di Axe DevTools Linter

Opzioni di Configurazione

`element`

`exclude`

`enterpriseId`

`extends`

Come vengono combinati le impostazioni ereditate

Limiti e gestione degli errori

`global-components`

`global-libraries`

`overrides`

`rules`

`tags`

Vedi Anche

Is this page helpful?

Help us improve this page

Try

Still need help?