Configurazione di axe DevTools Linter

Link to Configurazione di axe DevTools Linter copied to clipboard

Una guida di riferimento per la configurazione di axe DevTools Linter

Not for use with personal data

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

Panoramica

L'endpoint API REST utilizza JSON per la configurazione, mentre l'estensione axe Accessibility Linter per VS Code, il plugin JetBrains e il connettore axe DevTools Linter utilizzano YAML per la configurazione. In questa guida vengono mostrati esempi JSON e YAML delle configurazioni di axe DevTools Linter.

Configurazioni di esempio

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

rules:
  html-has-lang: false

L'esempio seguente dimostra la stessa configurazione di un oggetto di richiesta completo con l'opzione rules per il servizio REST axe DevTools Linter con il suo oggetto incorporato evidenziato: 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 all'elemento html manca un attributo lang . (Per maggiori informazioni, vedere la regola html-has-lang .)

note

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

Le sezioni seguenti descrivono ciascuna opzione di configurazione e forniscono esempi del loro utilizzo.

File di configurazione multipli

L'estensione axe Accessibility Linter per VS Code, il plugin JetBrains e axe DevTools Linter Connector (se utilizzati con l'opzione --config senza parametri) cercheranno i file di configurazione nella directory corrente e nelle directory padre nell'albero delle directory del progetto axe-linter.yml e utilizzeranno il primo che trovano. Una pratica utile è quella di posizionare un file di configurazione nella radice del progetto contenente la configurazione predefinita e di sovrascriverla (se necessario) con file di configurazione in sottodirectory diverse. Puoi anche posizionare un file di configurazione nella tua directory home, che verrà utilizzato per impostazione predefinita se nel tuo progetto non sono presenti file di configurazione.

I passaggi utilizzati per individuare i file di configurazione sono: axe-linter.yml

Usa il file di configurazione nella directory corrente (la directory contenente il file modificato con VS Code, un IDE JetBrains o la directory corrente del prompt dei comandi con axe DevTools Linter Connector).
Se non viene trovata alcuna configurazione nel passaggio 1, cercare nelle directory padre finché non viene trovato un file di configurazione, fermandosi nella cartella home se il progetto si trova nell'albero della directory home o nella directory radice se si trova all'esterno della cartella home. axe-linter.yml
Utilizzare un file di configurazione situato nella directory home (anche se il progetto si trova in una directory esterna alla cartella home o su un'altra unità su Windows). axe-linter.yml Ad esempio, questi sono i file tipici utilizzati:
- /home/username/axe-linter.yml (Linux)
- /Utenti/nomeutente/axe-linter.yml (macOS)
- C:\Users\nomeutente\axe-linter.yml (Windows)

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

Riepilogo della configurazione di axe DevTools Linter

Prodotto	Tipo di configurazione	Descrizione
Estensione Accessibility Linter di axe per VS Code o il plugin JetBrains	Uno o più file YAML denominati `axe-linter.yml`	Vedere Configurazioni multiple.
Connettore Linter axe	Uno o più file YAML denominati `axe-linter.yml`	Segue i passaggi descritti in Configurazioni multiple se utilizzato con l'opzione `--config` senza parametri.
Connettore Linter axe	Un file YAML denominato nomefile	Se utilizzato con `--config` nomefile.
API REST di axe Linter	Oggetto di configurazione JSON	Vedere L'oggetto config.

Opzioni di configurazione

`element`

L'opzione element consente di modificare l'elemento emesso in base al valore dell'attributo specificato del componente. Ad esempio, è possibile che un componente personalizzato emetta un elemento img in alcuni casi e un elemento button in altri, consentendo casi d'uso più complessi.

La configurazione di esempio riportata di seguito specifica che sul componente as l'attributo my-button può modificare 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'esempio di utilizzo seguente emette un img elemento invece di un button elemento predefinito perché l'attributo as specifica l'elemento di output:

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

L'elemento di output img verrà quindi sottoposto a linting e risulterà mancante di un attributo alt .

`exclude`

L'opzione exclude impedisce che i file corrispondenti vengano sottoposti a linting. È possibile utilizzare caratteri jolly e glob. Viene utilizzato principalmente per l'estensione VS Code o il plugin JetBrains e viene ignorato dall'endpoint REST.

exclude: *.tmp

`global-components`

L'opzione di configurazione global-components indica ad axe DevTools Linter come mappare i tuoi componenti personalizzati o componenti provenienti da librerie di terze parti su elementi HTML nativi, consentendoti di eseguire il linting dei tuoi componenti come se fossero elementi HTML nativi. Ad esempio, la seguente configurazione tratterà tutti i componenti personalizzati come se fossero elementi HTML nativi. DqButton button In questo modo ogni attributo viene automaticamente mappato da DqButton a button, rendendo quindi necessario 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, è possibile elencare gli attributi richiesti per la conformità all'accessibilità utilizzando l'opzione attributes . È possibile elencare gli attributi supportati dal componente e rinominarli. Ci sono tre valori speciali:

Il valore aria-* indica a axe DevTools Linter che tutti gli attributi che iniziano con aria- vengono 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à viene utilizzata 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 consente di modificare l'elemento emesso in base al valore dell'attributo specificato.

Il seguente esempio YAML mostra tutti i valori che possono essere utilizzati 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) è la seguente: config

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

Nell' attributes elenco devono essere presenti solo gli attributi rilevanti per l'accessibilità. I nomi degli elementi sono sensibili alle maiuscole e alle minuscole. Il camel case, come mostrato sopra, è comunemente utilizzato con i file .jsx, ma è possibile utilizzare anche il kebab case (utilizzato in Vue, Angular e negli elementi personalizzati HTML).

Per istruzioni dettagliate su come utilizzare la mappatura dei componenti personalizzati, vedere Linting dei componenti personalizzati.

`global-libraries`

Axe DevTools Linter ha un supporto integrato per numerose librerie di componenti e framework diffusi.

Attualmente sono supportate le seguenti librerie:

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

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

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

note

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

Oppure la configurazione JSON equivalente è mostrata di seguito:

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

Qualsiasi componente con lo stesso nome di un componente della libreria globale verrà trattato come quel componente della libreria, consentendo la riesportazione e la nuova dichiarazione dei componenti senza perdere la loro mappatura.

Per ulteriori informazioni, vedere Librerie di componenti preconfigurate.

`overrides`

È possibile modificare la configurazione di axe DevTools Linter per ogni file utilizzando l'opzione di configurazione overrides . Gli overrides multipli sullo stesso file vengono risolti in ordine. Ciò significa che l'ultimo overrides elencato ha la precedenza più alta.

Attualmente è supportato solo l' linter override, che viene utilizzato per modificare 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 singolarmente con l'opzione rules nella tua configurazione:

rules:
  some-rule: false # turn off rule
  other-rule: true # turn on rule

Oppure nell'oggetto config nella tua richiesta JSON REST:

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

Per informazioni sull'utilizzo rules con l'API REST, vedere Proprietà rules. Se si desidera utilizzarlo rules con il connettore axe DevTools Linter, vedere File di configurazione. Per conoscere le regole seguite da axe DevTools Linter, vedere Regole di accessibilità. Per ulteriori informazioni sull'utilizzo dell'(#tags) opzione per escludere raccolte di regole dall'elaborazione, vedere tags di seguito.

`tags`

È possibile non consentire le regole come gruppo in base allo standard WCAG a cui sono associate utilizzando l'opzione tags :

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

Vedere anche

Per un riferimento alle API REST fornite da axe DevTools Linter, vedere Riferimento alle API REST di axe DevTools Linter.
Per istruzioni dettagliate sulla creazione di mappature di componenti personalizzati, vedere Linting di componenti personalizzati.
Per scaricare l'estensione per VS Code, vedere axe Accessibility Linter.
Per maggiori informazioni sul plugin JetBrains, vedere Utilizzo del plugin con gli IDE JetBrains.