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 non vengono uniti. Il primo trovato è l'unico utilizzato.

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 opzionale 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 è ignorato nelle implementazioni in sede.

enterpriseId: 'acme-corp'

`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 le guide che mostrano come utilizzare il mapping dei componenti personalizzati, vedi 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 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`

Puoi permettere o vietare le regole individualmente con l'opzione rules nella tua configurazione. Ogni regola può essere impostata su true (abilitata, segnalata come errore — il predefinito), false (disabilitata) o warn (abilitata, segnalata come 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 nella tua richiesta JSON REST:

{
  "config": {
    "rules": {
      "some-rule": false,
      "other-rule": true,
      "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 vietare le regole come gruppo in base allo standard WCAG a cui sono associate 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, 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.