Riferimento API JavaScript del browser per Axe DevTools per Web

Introduzione

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

• Funziona in qualsiasi browser moderno
• Progettata per funzionare con le infrastrutture di test esistenti
• 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 dell'accessibilità, assicurando che le regole siano state eseguite su tutto il documento

Per iniziare

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

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 delle pagine web e restituisce un oggetto JSON che elenca eventuali violazioni di accessibilità trovate. Ecco come iniziare:

1. Caricare la pagina nel sistema di test
2. Facoltativamente, impostare le opzioni di configurazione per l'API JavaScript (AxeDevTools.configure)
3. Chiamare l'API JavaScript per analizzare (AxeDevTools.run)
4. O verificare i risultati o salvarli per l'elaborazione successiva

Riferimento API

Panoramica

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

Note sull'API

• Un test di regola è composto da sottotest. Ogni sottotest è restituito in un array di 'controlli'
• Il "helpUrl" nell'oggetto dei risultati si collega a una descrizione più ampia del problema di accessibilità e le possibili soluzioni. Tutti i collegamenti puntano alle pagine di aiuto di Deque University.

AxeDevTools.init

Scopo

Inizializzare 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 sottogruppi di regole standard.

Sinossi

AxeDevTools.init(ruleSetID);

Parametri

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

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

Restituisce: undefined

AxeDevTools.ruleSets

Scopo

Un array delle definizioni del set di regole standard

Descrizione

Fornisce accesso diretto all'array delle definizioni del set di regole standard. L'array è composto 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

Ottenere informazioni su tutte le regole nel sistema

Descrizione

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

Sinossi

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

Parametri

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

Ritorna: Array di regole che corrispondono al filtro di input in cui ogni voce ha un formato di {ruleId: <id>, description: <desc>}

Il set attuale di tag supportati è elencato nella seguente tabella:

Esempio 1

In questo esempio, passiamo i tag WCAG 2 A e AA in AxeDevTools.getRules per recuperare solo quelle regole. La chiamata alla 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

Configurare il formato dei dati utilizzati da Axe DevTools. Questo può essere utilizzato per aggiungere nuove regole, che devono essere registrate con la libreria per l'esecuzione.

Descrizione

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

Sinossi

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

Parametri

• configurationOptions - Oggetto delle opzioni dove i nomi dei parametri e i relativi valori validi sono:
  • branding - misto (opzionale) Usato per impostare il branding di helpUrls.
    • brand - stringa (opzionale) imposta la stringa del marchio--predefinito: „worldspace“
    • application - stringa (opzionale) imposta la stringa dell'applicazione--predefinito: „AxeDevToolsAPI“
  • reporter - Usato per impostare il formato di output che la funzione AxeDevTools.run passerà alla funzione di callback
    • v1 per usare il formato della versione precedente: AxeDevTools.configure({ reporter: "v1" });
    • v2 per usare il formato della versione corrente: AxeDevTools.configure({ reporter: "v2" });
  • checks - Usato per aggiungere controlli alla lista di controlli usati dalle regole o per sovrascrivere le proprietà dei controlli esistenti.
    • L'attributo dei controlli è un array di oggetti di controllo.
    • Ogni oggetto di controllo può contenere i seguenti attributi:
    • id - stringa (richiesto). Questo identifica univocamente il controllo. Se il controllo esiste già, qualsiasi proprietà fornita del controllo verrà sovrascritta. Le proprietà sotto indicate con richiesto se nuovo sono opzionali quando il controllo viene sovrascritto.
    • evaluate - funzione (richiesto se nuovo). Questa è la funzione che implementa la funzionalità del controllo.
    • after - funzione (opzionale). Questa funzione viene chiamata per i controlli che operano a livello di pagina per elaborare i risultati dagli iframe.
    • options - misto (opzionale). Questo oggetto options viene passato alla funzione evaluate ed è destinato a configurare i controlli. È la proprietà più comune destinata a essere sovrascritta per i controlli esistenti.
    • matches - stringa (opzionale). Questa stringa del selettore CSS filtrerà i nodi passati nella funzione evaluate.
    • enabled - booleano (opzionale, predefinito true). Indica se il controllo è attivo o disattivato per impostazione predefinita. I controlli disattivati non vengono valutati, anche se inclusi in una regola. Sovrascrivere questo è un modo comune per disabilitare un controllo particolare su più regole.
  • rules - Usato per aggiungere regole al set esistente di regole o sovrascrivere le proprietà delle regole esistenti. L'attributo rules è un array di oggetti rule. Ogni oggetto rule può contenere i seguenti attributi:
    • id - stringa (richiesta). Questo identifica univocamente la regola. Se la regola esiste già, verrà sovrascritta con tutti gli attributi forniti. Gli attributi sotto che sono contrassegnati come richiesti sono richiesti solo per le nuove regole.
    • selector - stringa (opzionale, predefinito *). Un selettore CSS utilizzato per identificare gli elementi passati nella regola per la valutazione.
    • excludeHidden - booleano (opzionale, predefinito true). Questo indica se gli elementi nascosti devono essere passati nella regola per la valutazione.
    • enabled - booleano (opzionale, predefinito true). Indica se la regola è attivata (un attributo comune per sovrascrivere).
    • pageLevel - booleano (opzionale, predefinito false). Indica se la pagina opera solo quando lo scope è l'intera pagina. Un esempio di una regola come questa è la regola salta il link. Non è consigliato sovrascrivere questa proprietà a meno che anche l'implementazione non venga modificata.
    • any - array (opzionale, predefinito []). Questa è la lista di controlli che devono tutti superare o ci sarà una violazione.
    • all - array (opzionale, predefinito []). Questa è la lista di controlli che, se qualcuno fallisce, genererà una violazione.
    • none - array (opzionale, predefinito []). Questa è una lista dei controlli che, se nessuno supera, genererà una violazione.
    • tags - array (opzionale, predefinito []). Una lista dei tag che classifica la regola. In pratica, devi fornire alcuni tag validi, altrimenti la valutazione predefinita non invocherà la regola. La convenzione è quella 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 sono costruiti convertendo tutte le lettere in minuscolo, rimuovendo spazi e punti, e concatenando il risultato. Per esempio, i criteri di successo WCAG 2 A 1.1.1 diventerebbero ["wcag2a", "wcag111"]
    • matches - stringa (opzionale, predefinito *). Un selettore CSS che escluderà gli elementi che non lo rispettano.

Ritorna: Nulla

AxeDevTools.reset

Scopo

Reimposta la configurazione alla configurazione predefinita.

Descrizione

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

Sinossi

AxeDevTools.reset();

Parametri

Nessuno

Ritorna: indefinito

AxeDevTools.run

Scopo

Analizza la pagina attualmente caricata.

Descrizione

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

Sinossi

AxeDevTools.run(context, options, callback);

Parametri per AxeDevTools.run

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

Parametro context

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

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

Oggetti include e exclude

L'oggetto include-exclude è un oggetto JSON con due attributi: include e exclude. Sono richiesti o include o exclude. Se viene specificato solo exclude, include predefinirà l'intero document.

• Un nodo, oppure
• 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 regioni di una pagina all'interno di iframe (o iframe all'interno di iframe all'interno di iframe). In questo caso, i primi n-1 selettori selezionano l'iframe(i), e l'n-esimo seleziona la regione(e) all'interno dell'iframe.

Esempi del parametro context

1. Includi il primo elemento nel NodeList $fixture, ma escludi il suo primo figlio

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

2. Includi l'elemento con l'ID di fix ma escludi qualsiasi div al suo interno

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

3. Includi l'intero documento eccetto qualsiasi struttura il cui genitore contenga la classe exclude1 o exclude2

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

Parametro options

Il parametro options è un modo flessibile per configurare come AxeDevTools.run opera. Le diverse modalità di funzionamento sono:

• Esegui tutte le regole corrispondenti a uno degli standard di accessibilità.
• Esegui tutte le regole definite nel sistema eccetto per l'elenco di regole specificate.
• Esegui un insieme specifico di regole fornite come elenco di ID regola.

Esempi del parametro options

1. Esegui solo Regole per uno standard di accessibilità

   Esistono alcuni standard definiti che possono essere usati per selezionare un set di regole. Gli standard definiti e la stringa del tag sono definiti 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	Tester Fidato v5
   best-practice	Best practice approvate da Deque

   Per eseguire solo le regole di WCAG 2.0 Livello A, specifica options come:

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

   Per eseguire sia le regole di WCAG 2.0 Livello A che Livello AA, devi specificare sia wcag2a che wcag2aa:

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

2. Esegui solo un elenco specifico di Regole

   Se vuoi eseguire solo determinate regole, specifica le opzioni come:

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

   Questo esempio eseguirà solo le regole con l'ID di ruleId1, ruleId2 e ruleId3. Nessuna altra regola verrà eseguita.

3. Esegui tutte le Regole abilitate eccetto un elenco di regole

   L'operazione predefinita per AxeDevTools.run è eseguire tutte le regole di WCAG 2.0 Livello A e Livello AA. Se alcune regole devono essere disabilitate, specifica 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 sottostante.

4. Esegui un set modificato di regole usando tag e attivazione regole

   Un set modificato può essere definito combinando runOnly con type impostato sui tag desiderati e utilizzando l'opzione rules. Questo ti permette di includere regole con tag non specificati ed escludere quelle con tag specificato o tag.

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

   Questo esempio include tutte le regole di livello A eccetto valid-lang, e includerà anche la regola di contrasto colore di livello AA.

5. Esegui solo alcuni tag, ma escludi altri

   L'opzione runOnly può accettare un oggetto con una proprietà include e exclude. Verranno eseguiti solo quei controlli che corrispondono a un tag incluso, eccetto quelli che condividono un tag con la lista di esclusione.

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

   Questo esempio include prima tutte le regole wcag2a e wcag2aa. Tutte le regole etichettate come experimental vengono poi rimosse dalle regole da eseguire.

Parametro callback

Il parametro callback è una funzione che verrà chiamata quando la funzione asincrona AxeDevTools.run sarà completata. Alla funzione callback vengono passati due parametri. Il primo parametro sarà un errore generato all'interno di Axe DevTools se AxeDevTools.run non può concludere. Se Axe DevTools ha completato correttamente, il primo parametro sarà nullo e il secondo parametro sarà l'oggetto dei risultati.

Restituisci Promessa

Se il callback non è stato definito, Axe DevTools restituirà una promessa. Tuttavia, Axe DevTools non fornirà un'implementazione della libreria delle promesse. Pertanto, nei sistemi senza supporto per le promesse, questa funzione non è disponibile. Se non sei sicuro se i sistemi su cui avrai bisogno di Axe DevTools supportano le promesse, ti suggeriamo di utilizzare il callback fornito da AxeDevTools.run invece.

Risultato error

Questo sarà o null o un oggetto che è un'istanza di Error. Se ricevi costantemente errori, ti preghiamo di segnalare questo problema a Deque Systems.

Oggetto results

La funzione di callback passata come terzo parametro di AxeDevTools.a11yCheck si esegue sull'oggetto results. Questo oggetto ha due componenti: un array passes e un array violations. L'array passes tiene traccia di tutti i test superati e delle informazioni dettagliate su ciascun test. Questo porta a test più efficienti, specialmente con i test manuali, poiché l'utente può determinare facilmente i test già superati. Allo stesso modo, l'array violations tiene traccia di tutti i test falliti e delle informazioni dettagliate su ciascuno di essi.

url

L'URL della pagina che è stata testata.

timestamp

La data e l'ora in cui è stata completata l'analisi.

Array passes e violations

• description - Una stringa di testo che descrive cosa fa la regola
• help - Testo di aiuto che descrive il test che è stato eseguito
• helpUrl - Un URL che fornisce maggiori informazioni sui dettagli della violazione. Collegamenti a una pagina sul sito di Deque University.
• id - Un identificativo univoco per la regola; vedere l'elenco delle regole
• impact - La gravità della violazione. Può essere uno di minore, moderato, grave, o critico se la regola ha fallito o null se il controllo è passato.
• tags - Un array di tag assegnati a questa regola. I tag possono essere utilizzati nell'oggetto option per selezionare quali regole eseguire (vedi Parametro Opzioni sopra).
• nodes - Un array di tutti gli elementi che la regola ha testato
  • html - Un frammento di HTML dell'elemento
  • impact - La gravità della violazione. Può essere uno tra minore, moderato, serio o critico se il test è fallito, o null se il controllo è passato.
  • target - Un array di selettori dove ogni elemento corrisponde a un livello di iframe o frame. Se c'è un iframe o frame, dovrebbero esserci due voci in target. Se ci sono tre livelli di iframe, dovrebbero esserci quattro voci in target.
  • any - Un array di controlli dove almeno uno deve essere passato. Ogni voce dell'array contiene:
    • id - Identificatore univoco per questo controllo. Gli ID dei controlli potrebbero essere gli stessi degli ID delle regole.
    • impact - La gravità del controllo. Può essere uno tra minore, moderato, serio o critico. Ogni controllo che fa parte di una regola può avere impatti diversi. L'impatto più alto di tutti i controlli che falliscono viene riportato per la regola.
    • message - La descrizione del motivo per cui questo controllo è passato o fallito.
    • data - Informazioni aggiuntive e opzionali specifiche del tipo di controllo. Per esempio, un controllo del contrasto dei colori includerebbe il colore di primo piano, il colore di sfondo, il rapporto di contrasto, ecc.
    • relatedNodes - Un array opzionale di informazioni su altri nodi correlati a questo controllo. Per esempio, una violazione del controllo degli ID duplicati 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 - Il sorgente HTML del nodo correlato
  • all - Un array di controlli effettuati dove tutti devono essere passati. Ogni voce dell'array contiene le stesse informazioni dell'array any.
  • none - Un array di controlli effettuati dove tutti non devono essere passati. Ogni voce dell'array contiene le stesse informazioni dell'array any.

Esempio Due

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

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

Array passes

• 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 sopra, l'array passes contiene due voci corrispondenti alle due regole testate. Il primo elemento dell'array descrive un controllo del contrasto dei colori. I campi help, helpUrl e id sono restituiti per ogni voce nell'array passes. L'array target contiene un elemento con il valore di:

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

L'elemento selezionato da target[0] è stato controllato per la regola del contrasto dei colori ed è passato.

Ogni voce successiva nell'array dei passaggi ha lo stesso formato ma descriverà le diverse regole eseguite.

Array violations

• 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] ...

The violations array contains one entry for a test that checks if buttons have valid alternate text (the button-name rule). This first entry in the array has the help, helpUrl, and id fields.

The target array demonstrates how we specify the selectors when the node specified is inside an iframe or frame. The first element in the target array (target[0]) specifies the selector to the iframe containing the button. The second element in the target array (target[1]) specifies the selector to the actual button but starts from inside the iframe selected in target[0].

Esempio Tre

In questo esempio, forniremo il selettore per l'intero documento, abiliteremo due ulteriori regole di buone pratiche, e avremo una semplice funzione di callback che registra l'intero oggetto dei risultati nel log della console:

In this example, we pass the selector for the entire document, enable two additional best practice rules, and have a simple callback function that logs the entire results object to the console log:

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