Riferimento API JavaScript del browser per axe DevTools per Web

Introduzione

L'API axe DevTools è progettata per rappresentare un miglioramento rispetto alla precedente generazione di API di accessibilità. Offre i seguenti vantaggi:

• Funziona su qualsiasi browser moderno
• Progettato per funzionare con l'infrastruttura di test esistente
• Funziona localmente; non è necessaria alcuna connessione a un server di terze parti
• Esegue il controllo delle violazioni su più livelli di iframe nidificati
• Fornisce un elenco di regole ed elementi che hanno superato il controllo di accessibilità, assicurando che le regole siano state eseguite sull'intero documento

Iniziare

Questa sezione descrive brevemente come utilizzare le API di axe DevTools per analizzare il contenuto delle pagine web e restituire un oggetto JSON che elenca tutte le violazioni di accessibilità rilevate.

L'API axe DevTools può essere utilizzata come parte di un processo più ampio che viene eseguito su molte, se non tutte, le pagine di un sito web. L'API analizza il contenuto della pagina web e restituisce un oggetto JSON che elenca tutte le violazioni di accessibilità rilevate. Ecco come iniziare:

1. Carica la pagina nel sistema di test
2. Facoltativamente, imposta le opzioni di configurazione per l'API JavaScript (AxeDevTools.configure)
3. Chiama l'API JavaScript di analisi (AxeDevTools.run)
4. O verifica i risultati o salvali per un'elaborazione successiva

Riferimento API

Panoramica

Le API di axe DevTools sono fornite nel file JavaScript axe-devtools.js. Deve essere incluso nella pagina web in fase di test. I parametri vengono inviati come parametri di funzione JavaScript. I risultati vengono restituiti in formato JSON.

Note API

• Un Test della regola è composto da sottotest. Ogni sottotest viene restituito in un array di 'controlli'
• Il "helpUrl" nell'oggetto dei risultati rimanda a una descrizione più ampia del problema di accessibilità e alla soluzione suggerita. Tutti i link puntano alle pagine di aiuto della Deque University.

AxeDevTools.init

Scopo

Inizializza l'API axe DevTools per utilizzare uno dei set di regole standard integrati.

Descrizione

Inizializza il motore axe DevTools, sovrascrivendo il set di regole predefinito e abilitando uno dei sottoinsiemi di regole standard.

Sinossi

AxeDevTools.init(ruleSetID);

Parametri

• ruleSetID - facoltativo Stringa che identifica il set di regole. I valori validi correnti sono:

  • 508
  • en301549
  • ttv5
  • wcag2
  • wcag21
  • wcag22
  • wcag2aaa
  • wcag21aaa
  • wcag22aaa

Restituisce: undefined

AxeDevTools.ruleSets

Scopo

Un array di definizioni di set di regole standard

Descrizione

Fornisce accesso diretto all'array di definizione del set di regole standard. L'array è costituito da oggetti JavaScript con la seguente struttura:

{
  id: String identifier for the rule set,
  defn: Object containing the rule set definition
}

Esempio Uno

Come filtrare l'array per trovare la definizione del set di regole WCAG 2 livello A e AA.

var rsets = AxeDevTools.ruleSets;
var wcag2 = rsets.filter(function (item) {
  return item.id === 'wcag2';
})[0].defn;

AxeDevTools.getRules

Scopo

Per ottenere informazioni su tutte le regole del sistema

Descrizione

Restituisce un elenco di tutte le regole con il relativo ID e descrizione.

Sinossi

AxeDevTools.getRules([Tag Name 1, Tag Name 2...]);

Parametri

• tags - facoltativo Array di tag utilizzati per filtrare le regole restituite. Se omesso, restituirà tutte le regole.

Restituisce: Array di regole che corrispondono al filtro di input con ogni voce con un formato di... {ruleId: <id>, description: <desc>}

L'attuale set di tag supportati è elencato nella seguente tabella:

Esempio 1

In questo esempio, passiamo i tag WCAG 2 A e AA a AxeDevTools.getRules per recuperare solo quelle regole. La chiamata di funzione restituisce un array di regole.

Chiamata: AxeDevTools.getRules(['wcag2aa', 'wcag2a']);

Dati restituiti:

[
  { ruleId: "area-alt", description: "Checks the <area> elements of image…" },
  { ruleId: "aria-allowed-attr", description: "Checks all attributes that start…" },
  { ruleId: "aria-required-attr", description: "Checks all elements that contain…" },
  …
]

AxeDevTools.configure

Scopo

Per configurare il formato dei dati utilizzati da axe DevTools. Può essere utilizzato per aggiungere nuove regole, che devono essere registrate nella libreria per poter essere eseguite.

Descrizione

L'utente specifica il formato della struttura JSON passata al callback di AxeDevTools.run.

Sinossi

AxeDevTools.configure({
  branding: {
    brand: String,
    application: String
  },
  reporter: 'option',
  checks: [Object],
  rules: [Object]
});

Parametri

• configurationOptions - Oggetto delle opzioni in cui le coppie nome/valore valide sono:
  • branding - mixed (facoltativo) Utilizzato per impostare il marchio del helpUrls.
    • brand - stringa (opzionale) imposta la stringa del marchio--predefinito: "worldspace"
    • application - stringa (opzionale) imposta la stringa dell'applicazione -- predefinita: "AxeDevToolsAPI"
  • reporter - Utilizzato per impostare il formato di output che la AxeDevTools.run funzione passerà alla funzione di callback
    • v1 per utilizzare il formato della versione precedente: AxeDevTools.configure({ reporter: "v1" });
    • v2 per utilizzare il formato della versione corrente: AxeDevTools.configure({ reporter: "v2" });
  • checks - Utilizzato per aggiungere controlli all'elenco dei controlli utilizzati dalle regole o per sovrascrivere le proprietà dei controlli esistenti.
    • L'attributo checks è un array di oggetti check.
    • Ogni oggetto check può contenere i seguenti attributi:
    • id - stringa (obbligatoria). Ciò identifica in modo univoco il check. Se il check esiste già, tutte le proprietà del check fornite verranno sovrascritte. Sono facoltative quando il controllo viene ignorato, le proprietà sottostanti contrassegnate come richiesto se nuovo .
    • evaluate - funzione (obbligatoria se nuova). Questa è la funzione che implementa la funzionalità del controllo.
    • after - funzione (opzionale). Questa funzione viene chiamata per le verifiche che operano a livello di pagina per elaborare i risultati degli iframe.
    • options - misto (facoltativo). Questo options oggetto viene passato alla funzione evaluate ed è destinato a essere utilizzato per configurare i controlli. Si tratta della proprietà più comune destinata a essere sovrascritta per i controlli esistenti.
    • matches - stringa (facoltativo). Questa stringa di selezione CSS filtrerà i nodi passati alla funzione evaluate .
    • enabled - booleano (opzionale, predefinito true). Indica se il controllo è attivato o disattivato per impostazione predefinita. I controlli disattivati non vengono valutati, anche se inclusi in una regola. Ignorare questa regola è un metodo comune per disattivare un controllo specifico su più regole.
  • rules - Utilizzato per aggiungere regole al set di regole esistente o per sovrascrivere le proprietà delle regole esistenti. L'attributo rules è un array di rule oggetti. Ogni rule oggetto può contenere i seguenti attributi:
    • id - stringa (obbligatoria). Questa identifica in modo univoco la regola. Se la regola esiste già, verrà sovrascritta con tutti gli attributi forniti. Gli attributi seguenti contrassegnati come obbligatori sono richiesti solo per le nuove regole.
    • selector - stringa (facoltativa, predefinita *). Selettore CSS utilizzato per identificare gli elementi passati alla regola per la valutazione.
    • excludeHidden - booleano (facoltativo, predefinito true). Indica se gli elementi nascosti devono essere passati alla regola per la valutazione.
    • enabled - booleano (opzionale, predefinito true). Se la regola è attivata (un attributo comune per l'override).
    • pageLevel - booleano (facoltativo, predefinito false). Indica se la pagina funziona solo quando l'ambito è l'intera pagina. Un esempio di regola di questo tipo è la regola link di salto . Si sconsiglia di sovrascrivere questa proprietà, a meno che non venga modificata anche l'implementazione.
    • any - array ( facoltativo, predefinito []). Questo è l'elenco dei controlli che devono essere superati, altrimenti si verifica una violazione.
    • all - array (facoltativo, predefinito []). Questo è l'elenco dei controlli che, se non superano, genereranno una violazione.
    • none - array (facoltativo, predefinito []). Questo è un elenco dei controlli che, se nessuno di essi viene superato, genereranno una violazione.
    • tags - array (facoltativo, predefinito []). Un elenco dei tag che classificano la regola. In pratica, è necessario fornire alcuni tag validi, altrimenti la valutazione predefinita non invocherà la regola. La convenzione prevede di includere lo standard (WCAG 2 e/o sezione 508), il livello WCAG 2, il paragrafo della Sezione 508 e i criteri di successo WCAG 2. I tag vengono creati convertendo tutte le lettere in minuscolo, rimuovendo spazi e punti e concatenando il risultato. Ad esempio, il criterio di successo WCAG 2 A 1.1.1 diventerebbe ["wcag2a", "wcag111"]
    • matches - stringa (facoltativa, predefinita *). Un selettore CSS che escluderà gli elementi che non corrispondono.

Restituisce: Niente

AxeDevTools.reset

Scopo

Ripristina la configurazione alla configurazione predefinita.

Descrizione

Sovrascrive tutte le chiamate precedenti a AxeDevTools.configure o AxeDevTools.reset e ripristina la configurazione predefinita.

Sinossi

AxeDevTools.reset();

Parametri

Nessuno

Restituisce: undefined

AxeDevTools.run

Scopo

Analizza la pagina attualmente caricata.

Descrizione

Esegue diverse regole sulla pagina HTML fornita e restituisce l'elenco dei problemi risultante.

Sinossi

AxeDevTools.run(context, options, callback);

Parametri per AxeDevTools.run

• context: (facoltativo) Definisce l'ambito dell'analisi, ovvero la parte del DOM che si desidera analizzare. Questo sarà tipicamente il document o un selettore specifico come il nome della classe, l'ID, il selettore, ecc.
• opzioni: (facoltativo) Insieme di opzioni passate nelle regole o nei controlli, modificandoli temporaneamente. Ciò contrasta con AxeDevTools.configure, che è più permanente. Vedi sopra per maggiori informazioni
• callback: (facoltativo) La funzione di callback che riceve o null un risultato di errore come primo parametro e l'oggetto risultati quando l'analisi è stata completata con successo o undefined se non lo è.

context Parametro

Per impostazione predefinita, AxeDevTools.run verrà testato l'intero documento. L'oggetto context è un parametro facoltativo che specifica quale elemento deve essere testato e quale no. Può essere passato uno dei seguenti:

1. Un riferimento di elemento che rappresenta la parte del documento che deve essere analizzata
   • Esempio: Per limitare l'analisi all'elemento <div id="content"> : document.getElementById("content")
2. Un NodeList come quello restituito da document.querySelectorAll.
3. Un selettore CSS che seleziona la parte del documento che deve essere analizzata. Ciò include:
   • Un selettore CSS come nome di classe (ad esempio, .classname)
   • Un selettore CSS come nome del nodo (ad esempio, div)
   • Un selettore CSS di un elemento ID (ad esempio, #tag)
4. Un oggetto include-exclude (vedi sotto)

include e exclude Oggetti

L'oggetto include-exclude è un oggetto JSON con due attributi: include e exclude. È obbligatorio specificare o include o exclude . Se viene specificato solo exclude , include sarà impostato di default a tutto il document.

• Un nodo, o
• Un array di array di selettori CSS

Nella maggior parte dei casi, gli array conterranno un solo selettore CSS. Sono necessari più selettori CSS solo se si desidera includere o escludere aree di una pagina che si trovano all'interno di iframe (o iframe all'interno di iframe all'interno di iframe). In questo caso, i primi n-1 selettori selezionano gli iframe, mentre l'n-esimo selettore seleziona le regioni all'interno dell'iframe.

context Esempi di parametri

1. Includere il primo elemento nel $fixture NodeList ma escludere il suo primo figlio

   {
     include: $fixture[0],
     exclude: $fixture[0].firstChild
   }

2. Includere l'elemento con l'ID del fix ma escludere tutti gli div presenti al suo interno

   {
     include: [['#fix']],
     exclude: [['#fix div']]
   }

3. Includere l'intero documento eccetto le strutture il cui genitore contiene la classe exclude1 o exclude2

   {
     exclude: [['.exclude1'], ['.exclude2']];
   }

options Parametro

Il parametro options è un modo flessibile per configurare il modo in cui AxeDevTools.run funziona. Le diverse modalità di funzionamento sono:

• Eseguire tutte le regole corrispondenti a uno degli standard di accessibilità.
• Eseguire tutte le regole definite nel sistema, ad eccezione delle regole specificate nell'elenco.
• Eseguire un set specifico di regole fornito come elenco di ID regola.

options Esempi di parametri

1. Esegui solo regole per uno standard di accessibilità

   Esistono determinati standard definiti che possono essere utilizzati per selezionare un insieme di regole. Gli standard definiti e la stringa tag sono come segue:

   Nome del tag	Standard di accessibilità
   wcag2a	WCAG 2.0 Livello A
   wcag2aa	WCAG 2.0 Livello AA
   wcag2aaa	WCAG 2.0 Livello AAA
   wcag21a	WCAG 2.1 Livello A
   wcag21aa	WCAG 2.1 Livello AA
   wcag21aaa	WCAG 2.1 Livello AAA
   wcag22a	WCAG 2.2 Livello A
   wcag22aa	WCAG 2.2 Livello AA
   wcag22aaa	WCAG 2.2 Livello AAA
   section508	Sezione 508
   EN-301-549	EN 301 549
   TTv5	Trusted Tester v5
   best-practice	Le migliori pratiche approvate da Deque

   Per eseguire solo le regole WCAG 2.0 Livello A, specificare options in questo modo:

   {
     runOnly: {
      type: "tag",
      values: ["wcag2a"]
     }
   }

   Per eseguire entrambe le regole WCAG 2.0 di livello A e di livello AA, è necessario specificare sia wcag2a e wcag2aa:

   {
     runOnly: {
       type: "tag",
       values: ["wcag2a", "wcag2aa"]
     }
   }

2. Esegui solo un elenco specificato di Regole

   Se si desidera eseguire solo determinate Regole, specificare le opzioni come:

   {
     runOnly: {
       type: "rule",
       values: [ "ruleId1", "ruleId2", "ruleId3" ]
     }
   }

   In questo esempio verranno eseguite solo le Regole con ID ruleId1, ruleId2 e ruleId3. Nessun'altra Regola verrà applicata.

3. Esegui tutte le Regole abilitate ad eccezione di un elenco di Regole

   L'operazione predefinita per AxeDevTools.run è l'esecuzione di tutte le regole WCAG 2.0 di livello A e di livello AA. Se si desidera disabilitare l'esecuzione di determinate regole, specificare options come:

   {
     "rules": {
       "color-contrast": { enabled: false },
       "valid-lang": { enabled: false }
     }
   }

   Questo esempio disabiliterà le regole con l'ID color-contrast o valid-lang . Tutte le altre regole verranno eseguite. L'elenco degli ID regola validi è specificato nella sezione seguente.

4. Esegui un set di regole modificato utilizzando tag e abilitazione della regola

   È possibile definire un set modificato combinando runOnly con type impostato sui tag che desideri e utilizzando l'opzione rules . Ciò consente di includere regole con tag non specificati ed escludere regole con il tag o i tag specificati.

   {
     runOnly: {
       type: "tag",
       values: ["wcag2a"]
     },
     "rules": {
       "color-contrast": { enabled: true },
       "valid-lang": { enabled: false }
     }
   }

   Questo esempio include tutte le regole di livello A, ad eccezione di valid-lang, e includerà anche la regola di livello AA sul contrasto dei colori.

5. Usa solo alcuni tag, ma escludine altri

   L'opzione runOnly può accettare un oggetto con include e exclude una proprietà. Verranno eseguiti solo i controlli che corrispondono a un tag incluso, ad eccezione di quelli che condividono un tag dall'elenco di esclusione.

   {
     runOnly: {
       type: 'tags',
       value: {
         include: ['wcag2a', 'wcag2aa'],
         exclude: ['experimental']
       }
     }
   }

   Questo esempio include wcag2a e wcag2aa innanzitutto tutte le regole. Tutte le regole contrassegnate come experimental vengono quindi rimosse dalle regole da eseguire.

callback Parametro

Il callback parametro è una funzione che verrà chiamata al completamento della funzione asincrona AxeDevTools.run . callback Alla funzione vengono passati due parametri. Il primo parametro sarà un errore generato all'interno di Axe DevTools se AxeDevTools.run non è possibile completare. Se axe DevTools è stato completato correttamente, il primo parametro sarà null e il secondo parametro sarà l'oggetto risultati.

Return Promise

Se il callback non è stato definito, axe DevTools restituirà invece una promessa. Tuttavia, axe DevTools non implementa il polyfill della libreria delle promesse. Pertanto, nei sistemi senza supporto per le promesse, questa funzionalità non è disponibile. Se non sei sicuro che i sistemi su cui ti servirà axe DevTools abbiano supporto per le promesse, ti consigliamo di utilizzare il callback fornito da AxeDevTools.run .

error Risultato

Questo sarà o null un oggetto che è un'istanza di Error. Se si verificano ripetutamente errori, segnalare il problema a Deque Systems.

results Oggetto

La funzione di callback passata come terzo parametro di AxeDevTools.a11yCheck viene eseguita sull'oggetto results . Questo oggetto ha due componenti: un passes array e un violations array. passes L'array tiene traccia di tutti i test superati e fornisce informazioni dettagliate su ciascun test. Ciò consente di effettuare test più efficienti, soprattutto con i test manuali, poiché l'utente può individuare facilmente i test già superati. violations Allo stesso modo, l'array tiene traccia di tutti i test non superati e fornisce informazioni dettagliate su ciascuno di essi.

url

L'URL della pagina testata.

timestamp

Data e ora in cui è stata completata l'analisi.

passes e violations array

• description - Una stringa di testo che descrive cosa fa la regola
• help - Testo di aiuto che descrive il test eseguito
• helpUrl - Un URL che fornisce maggiori informazioni sui dettagli della violazione. Link a una pagina del sito della Deque University.
• id - Un identificatore univoco per la regola; vedi l'elenco delle regole
• impact - La gravità della violazione. Può essere minore, moderato, grave o critico se la regola fallisce o null se il controllo viene superato.
• tags - Un array di tag assegnati a questa regola. I tag possono essere utilizzati option nell'oggetto per selezionare quali regole eseguire (vedere Parametro Opzioni sopra).
• nodes - Un array di tutti gli elementi testati dalla regola
  • html - Un frammento di HTML dell'elemento
  • impact - La gravità della violazione. Può essere minore, moderato, grave o critico se il test è fallito o null se il controllo è passato.
  • target - Un array di selettori in cui ogni elemento corrisponde a un livello di iframe o frame. Se è presente un iframe o un frame, dovrebbero esserci due voci in target. Se ci sono tre livelli di iframe, dovrebbero esserci quattro voci in target.
  • any - Una serie di controlli di cui almeno uno deve essere stato superato. Ogni voce nell'array contiene:
    • id - Identificatore univoco per questo controllo. Gli ID di controllo potrebbero essere gli stessi degli ID delle regole.
    • impact - La gravità del controllo. Può essere di tipo minore, moderato, grave o critico. Ogni verifica che fa parte di una regola può avere impatti diversi. Per la regola viene segnalato l'impatto più elevato tra tutti i controlli falliti.
    • message - La descrizione del motivo per cui il controllo è stato superato o meno.
    • data - Informazioni aggiuntive e facoltative specifiche del tipo di controllo. Ad esempio, un controllo del contrasto dei colori includerebbe il colore di primo piano, il colore di sfondo, il rapporto di contrasto, ecc.
    • relatedNodes - Una matrice facoltativa di informazioni su altri nodi correlati a questo controllo. Ad esempio, una violazione del controllo dell'ID duplicato elencherebbe gli altri selettori con lo stesso ID duplicato. Ogni voce nell'array contiene le seguenti informazioni:
      • target - Un array di selettori per il nodo correlato
      • html - La sorgente HTML del nodo correlato
  • all - Una serie di verifiche effettuate che devono essere state tutte superate. Ogni voce nell'array any contiene le stesse informazioni dell'array.
  • none - Una serie di verifiche effettuate che non devono essere state superate. Ogni voce nell'array any contiene le stesse informazioni dell'array.

Esempio Due

In questo esempio, passeremo il selettore per l'intero documento, non passeremo alcuna opzione, il che significa che verranno eseguite tutte le regole abilitate, e avremo una semplice funzione di callback che registra l'intero oggetto dei risultati nel console log:

AxeDevTools.run(document, function (err, results) {
  if (err) throw err;
  console.log(results);
});

passes vettore

• passes[0] ...

  • help - "Elements must have sufficient color contrast"
  • helpURL - "https://dequeuniversity.com/courses/html-css/visual-layout/color-contrast"
  • id - "color-contrast"
    • nodes
    • target[0] - "#js_off-canvas-wrap > .inner-wrap >.kinja-title.proxima.js_kinja-title-desktop"

• passes[1] ...

Nell'esempio precedente, l'array passes contiene due voci corrispondenti alle due regole testate. Il primo elemento dell'array descrive un controllo del contrasto dei colori. Per ogni voce nell'array help, vengono restituiti i campi helpUrl, id e passes . L'array target ha un elemento al suo interno con un valore di:

#js_off-canvas-wrap > .inner-wrap >.kinja-title.proxima.js_kinja-title-desktop

L'elemento selezionato da target[0] è stato sottoposto a verifica per la regola del contrasto cromatico e ha superato il test.

Ogni voce successiva nell'array dei passaggi ha lo stesso formato, ma descrive in dettaglio le diverse regole eseguite.

violations vettore

• violations[0]

  • help - "<button> elements must have alternate text"
  • helpURL - "https://dequeuniversity.com/courses/html-css/forms/form-labels#id84_example_button"
  • id - "button-name"
    • nodes
    • target[0]
    • "post_5919997 > .row.content-wrapper > .column > span > iframe" * target[1]
    • "#u_0_1 > .pluginConnectButton > .pluginButtonImage > button"

• violations[1] ...

L'array violations contiene una voce per un test che verifica se i pulsanti hanno un testo alternativo valido (la button-name regola). La prima voce nell'array contiene i campi help, helpUrl e id .

L'array target mostra come specificare i selettori quando il nodo specificato si trova all'interno di un iframe o frame. Il primo elemento nell' target array (target[0]) specifica il selettore per il iframe che contiene il pulsante. Il secondo elemento nell'array target (target[1]) specifica il selettore per il pulsante effettivo ma inizia dall'interno dell'iframe selezionato in target[0].

Ogni voce successiva nell'array delle violazioni ha lo stesso formato, ma descriverà in dettaglio le regole che hanno generato violazioni di accessibilità.

Esempio Tre

In questo esempio, passiamo il selettore per l'intero documento, abilitiamo due regole di best practice aggiuntive e disponiamo di una semplice funzione di callback che registra l'intero oggetto dei risultati nel registro della console:

AxeDevTools.run(
  document,
  {
    rules: {
      'heading-order': { enabled: true },
      'label-title-only': { enabled: true }
    }
  },
  function (err, results) {
    if (err) throw err;
    console.log(results);
  }
);