Browser JavaScript API-referentie voor Axe DevTools voor Web

Inleiding

De Axe DevTools API is ontworpen als een verbetering ten opzichte van de vorige generatie toegankelijkheids-API's. Het biedt de volgende voordelen:

• Werkt in elke moderne browser
• Ontworpen om te werken met bestaande testinfrastructuur
• Werkt lokaal; er is geen verbinding met een externe server nodig
• Voert schendingcontroles uit op meerdere niveaus van geneste iframes
• Biedt een lijst van regels en elementen die de toegankelijkheidscontrole hebben doorstaan, waarmee wordt gewaarborgd dat regels op het gehele document zijn toegepast

Aan de slag

Dit gedeelte beschrijft kort hoe de Axe DevTools API's kunnen worden gebruikt om de inhoud van webpagina's te analyseren en een JSON-object terug te geven dat eventuele gevonden toegankelijkheidsschendingen opsomt.

De Axe DevTools API kan worden gebruikt als onderdeel van een breder proces dat op veel, zo niet alle, pagina's van een website wordt uitgevoerd. De API analyseert de inhoud van webpagina's en geeft een JSON-object terug dat eventuele gevonden toegankelijkheidsschendingen opsomt. Zo kun je beginnen:

1. Laad pagina in het testsysteem
2. Stel optioneel configuratie-opties in voor de JavaScript-API (AxeDevTools.configure)
3. Roep de analyse JavaScript-API aan (AxeDevTools.run)
4. Voer een check uit tegen de resultaten of bewaar ze voor latere verwerking

API-referentie

Overzicht

De Axe DevTools API's worden geleverd in het JavaScript-bestand axe-devtools.js. Het moet in de webpagina onder test worden opgenomen. Parameters worden verzonden als parameters van de JavaScript-functie. Resultaten worden geretourneerd in JSON-formaat.

API-opmerkingen

• Een regeltest bestaat uit subtests. Elke subtest wordt geretourneerd in een array van 'checks'
• De "helpUrl" in het resultatenobject leidt naar een bredere beschrijving van het toegankelijkheidsprobleem en de voorgestelde oplossing. Alle links verwijzen naar de help-pagina's van Deque University.

AxeDevTools.init

Doel

Initialiseer de Axe DevTools API om een van de ingebouwde standaardregelsets te gebruiken.

Beschrijving

Initialiseert de Axe DevTools-engine, overschrijft de standaardregelset en stelt een van de standaardregelsubsets in.

Samenvatting

AxeDevTools.init(ruleSetID);

Parameters

• ruleSetID - optioneel String die de regelset identificeert. Huidige geldige waarden zijn:

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

Retourneert: undefined

AxeDevTools.ruleSets

Doel

Een reeks van de standaardregelsetdefinities

Beschrijving

Geeft directe toegang tot de array met standaardregelsetdefinities. De array bestaat uit JavaScript-objecten met de volgende structuur:

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

Voorbeeld Een

Hoe het array te filteren om de definitie van WCAG 2 niveau A en AA regelset te vinden.

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

AxeDevTools.getRules

Doel

Om informatie te verkrijgen over alle regels in het systeem

Beschrijving

Geeft een lijst terug van alle regels met hun ID en beschrijving.

Samenvatting

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

Parameters

• tags - optioneel Array van tags die worden gebruikt om de geretourneerde regels te filteren. Indien weggelaten, worden alle regels teruggestuurd.

Retourneert: Array van regels die overeenkomen met de invoerfilter waarbij elke invoer het formaat heeft van {ruleId: <id>, description: <desc>}

De huidige set ondersteunde tags staat in de volgende tabel:

Voorbeeld 1

In dit voorbeeld geven we de WCAG 2 A en AA tags door aan AxeDevTools.getRules om alleen die regels op te halen. De functieaanroep retourneert een array van regels.

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

Geretourneerde gegevens:

[
  { 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

Doel

Om het formaat van de gegevens die door Axe DevTools worden gebruikt te configureren. Dit kan worden gebruikt om nieuwe regels toe te voegen, die moeten worden geregistreerd in de bibliotheek om te worden uitgevoerd.

Beschrijving

De gebruiker specificeert het formaat van de JSON-structuur die wordt doorgegeven aan de callback van AxeDevTools.run.

Samenvatting

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

Parameters

• configurationOptions - Opties-object waarin de geldige naam/waarde-paren zijn:
  • branding - gemengd (optioneel) Gebruikt om de branding van de helpUrls in te stellen.
    • brand - string (optioneel) stelt de merknaam in--standaard: „worldspace“
    • application - string (optioneel) stelt de applicatiestring in--standaard: „AxeDevToolsAPI“
  • reporter - Gebruikt om het uitvoerformaat in te stellen dat de AxeDevTools.run functie zal doorgeven aan de callback-functie
    • v1 om het formaat van de vorige versie te gebruiken: AxeDevTools.configure({ reporter: "v1" });
    • v2 om het formaat van de huidige versie te gebruiken: AxeDevTools.configure({ reporter: "v2" });
  • checks - Gebruikt om controles toe te voegen aan de lijst van controles die door regels worden gebruikt of om de eigenschappen van bestaande controles te overschrijven.
    • De controles-attribuut is een array van controle-objecten.
    • Elk controle-object kan de volgende attributen bevatten:
    • id - string (vereist). Dit identificeert de controle uniek. Als de controle al bestaat, zullen alle verstrekte controle-eigenschappen worden overschreven. De onderstaande eigenschappen gemarkeerd vereist als nieuw zijn optioneel wanneer de controle wordt overschreven.
    • evaluate - functie (vereist als nieuw). Dit is de functie die de functionaliteit van de controle implementeert.
    • after - functie (optioneel). Deze functie wordt aangeroepen voor controles die op pagina-niveau opereren om de resultaten van de iframes te verwerken.
    • options - gemengd (optioneel). Dit options object wordt doorgegeven aan de evaluate functie en is bedoeld om te gebruiken bij het configureren van controles. Het is de meest gebruikelijke eigenschap die wordt overschreven voor bestaande controles.
    • matches - string (optioneel). Deze CSS-selectorstring zal de knooppunten filteren die aan de evaluate functie worden doorgegeven.
    • enabled - boolean (optioneel, standaard true). Dit geeft aan of de controle standaard aan of uit staat. Controles die uit staan, worden niet geëvalueerd, zelfs niet als ze in een regel zijn opgenomen. Het overschrijven hiervan is een gebruikelijke manier om een bepaalde controle uit te schakelen over meerdere regels.
  • rules - Gebruikt om regels toe te voegen aan de bestaande set regels of om de eigenschappen van bestaande regels te overschrijven. Het rules attribuut is een array van rule objecten. Elk rule object kan de volgende attributen bevatten:
    • id - string (vereist). Dit identificeert de regel uniek. Als de regel al bestaat, zal het worden overschreven met alle verstrekte attributen. De hieronder gemarkeerde attributen die als vereist zijn gemarkeerd, zijn alleen vereist voor nieuwe regels.
    • selector - string (optioneel, standaard *). Een CSS-selector die wordt gebruikt om de elementen te identificeren die aan de regel worden doorgegeven voor evaluatie.
    • excludeHidden - boolean (optioneel, standaard true). Dit geeft aan of verborgen elementen aan de regel moeten worden doorgegeven voor evaluatie.
    • enabled - boolean (optioneel, standaard true). Of de regel aan staat (een veelvoorkomend attribuut voor overschrijving).
    • pageLevel - boolean (optioneel, standaard false). Dit geeft aan of de pagina alleen werkt wanneer de scope de hele pagina is. Een voorbeeld van zo'n regel is de link overslaan regel. Het wordt niet aanbevolen om deze eigenschap te overschrijven, tenzij de implementatie ook wordt gewijzigd.
    • any - array (optioneel, standaard []). Dit is de lijst van controles die allemaal moeten slagen, anders is er een overtreding.
    • all - array (optioneel, standaard []). Dit is de lijst van controles die, als er een mislukt, een overtreding zullen genereren.
    • none - array (optioneel, standaard []). Dit is een lijst van de controles die, als er geen slagen, een overtreding zullen genereren.
    • tags - array (optioneel, standaard []). Een lijst van de tags die classificeren de regel. In de praktijk moet u enkele geldige tags opgeven, anders zal de standaard evaluatie de regel niet aanroepen. De conventie is om de standaard (WCAG 2 en/of sectie 508), het WCAG 2-niveau, de paragraaf van Sectie 508, en de succescriteria van WCAG 2 op te nemen. Tags worden geconstrueerd door alle letters naar kleine letters om te zetten, spaties en punten te verwijderen, en het resultaat samen te voegen. Bijvoorbeeld, WCAG 2 A succescriteria 1.1.1 wordt [„wcag2a“, „wcag111“]
    • matches - string (optioneel, standaard *). Een CSS-selector die elementen uitsluit die er niet mee overeenkomen.

Geeft terug: Niets

AxeDevTools.reset

Doel

Herstel de configuratie naar de standaardconfiguratie.

Beschrijving

Overschrijf alle eerdere aanroepen van AxeDevTools.configure of AxeDevTools.reset en herstel de configuratie naar de standaardconfiguratie.

Samenvatting

AxeDevTools.reset();

Parameters

Geen

Geeft terug: ongedefinieerd

AxeDevTools.run

Doel

Analyseer de huidige geladen pagina.

Beschrijving

Voert verschillende regels uit tegen de verstrekte HTML-pagina en retourneert de resulterende lijst van problemen.

Samenvatting

AxeDevTools.run(context, options, callback);

Parameters voor AxeDevTools.run

• context: (optioneel) Definieert de reikwijdte van de analyse—het deel van de DOM dat u wilt analyseren. Dit zal doorgaans de document of een specifieke selector zoals klasse naam, ID, selector, etc. zijn.
• options: (optioneel) Set aan opties die worden doorgegeven aan regels of controles, die deze tijdelijk wijzigen. Dit staat in contrast met AxeDevTools.configure, dat permanenter is. Zie hierboven voor meer informatie
• callback: (optioneel) De terugroepfunctie die ofwel null of een foutresultaat als eerste parameter ontvangt, en de resultatenobject wanneer de analyse succesvol is voltooid of undefined als dat niet het geval was.

context Parameter

Standaard zal AxeDevTools.run het gehele document testen. Het context object is een optionele parameter die specificeert welk element wel en welk niet moet worden getest. Het kan een van de volgende ontvangen:

1. Een elementreferentie die het deel van het document vertegenwoordigt dat moet worden geanalyseerd
   • Voorbeeld: Om de analyse te beperken tot het <div id="content"> element: document.getElementById("content")
2. Een NodeList zoals geretourneerd door document.querySelectorAll.
3. Een CSS-selector die het deel van het document selecteert dat moet worden geanalyseerd. Dit omvat:
   • Een CSS-selector als een klasse naam (bijv. .classname)
   • Een CSS-selector als een nodenaam (bijv. div)
   • Een CSS-selector van een element-ID (bijv. #tag)
4. Een include-exclude object (zie hieronder)

include en exclude Objecten

Het include-exclude object is een JSON-object met twee attributen: include en exclude. Ofwel include of exclude is vereist. Als alleen exclude is gespecificeerd, zal include standaard het gehele document zijn.

• Een node, of
• Een array van arrays van CSS-selectors

In de meeste gevallen zullen de arrays slechts één CSS-selector bevatten. Meerdere CSS-selectors zijn alleen nodig als u regio's van een pagina wilt opnemen of uitsluiten die zich binnen iframes bevinden (of iframes binnen iframes binnen iframes). In dit geval selecteren de eerste n-1 selectors de iframe(s), en de n-de selector selecteert de regio('s) binnen de iframe.

context Parameter Voorbeelden

1. Neem het eerste item in de $fixture NodeList op, maar sluit het eerste kind uit

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

2. Neem het element met de ID van fix op, maar sluit alle divs binnenin uit

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

3. Neem het hele document op, behalve structuren waarvan de ouder de klasse exclude1 of exclude2 bevat

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

options Parameter

De options-parameter is een flexibele manier om te configureren hoe AxeDevTools.run functioneert. De verschillende modi van werking zijn:

• Voer alle regels uit die overeenkomen met een van de toegankelijkheidsnormen.
• Voer alle regels uit die in het systeem zijn gedefinieerd behalve de lijst met gespecificeerde regels.
• Voer een specifieke set regels uit die wordt verstrekt als een lijst van regel-ID's.

options Parameter Voorbeelden

1. Voer alleen Regels voor een toegankelijkheidsnorm uit

   Er zijn bepaalde normen gedefinieerd die kunnen worden gebruikt om een set regels te selecteren. De gedefinieerde normen en tagstrings worden als volgt gedefinieerd:

   Tagnaam	Toegankelijkheidsnorm
   wcag2a	WCAG 2.0 Niveau A
   wcag2aa	WCAG 2.0 Niveau AA
   wcag2aaa	WCAG 2.0 Niveau AAA
   wcag21a	WCAG 2.1 Niveau A
   wcag21aa	WCAG 2.1 Niveau AA
   wcag21aaa	WCAG 2.1 Niveau AAA
   wcag22a	WCAG 2.2 Niveau A
   wcag22aa	WCAG 2.2 Niveau AA
   wcag22aaa	WCAG 2.2 Niveau AAA
   section508	Sectie 508
   EN-301-549	EN 301 549
   TTv5	Trusted Tester v5
   beste-praktijken	Beste praktijken ondersteund door Deque

   Om alleen WCAG 2.0 Niveau A-regels uit te voeren, specificeer options als:

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

   Om zowel WCAG 2.0 Niveau A als Niveau AA-regels uit te voeren, moet je zowel wcag2a als wcag2aa specificeren:

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

2. Voer alleen een opgegeven lijst met regels uit

   Als je alleen bepaalde regels wilt uitvoeren, specificeer dan opties als:

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

   Dit voorbeeld zal alleen de regels uitvoeren met de id van ruleId1, ruleId2 en ruleId3. Geen enkele andere regel wordt uitgevoerd.

3. Voer alle ingeschakelde regels uit behalve een lijst met regels

   De standaardoperatie voor AxeDevTools.run is om alle WCAG 2.0 Niveau A en Niveau AA-regels uit te voeren. Als bepaalde regels niet moeten worden uitgevoerd, specificeer dan options als:

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

   Dit voorbeeld schakelt de regels met de color-contrast of valid-lang ID uit. Alle andere regels worden uitgevoerd. De lijst van geldige regel-ID's is gespecificeerd in de onderstaande sectie.

4. Voer een gewijzigde set regels uit met behulp van tags en regel inschakelen

   Een gewijzigde set kan worden gedefinieerd door runOnly te combineren met type ingesteld op de gewenste tags en gebruikmakend van de rules optie. Hiermee kun je regels met niet-gespecificeerde tags opnemen en regels met de gespecificeerde tag of tags uitsluiten.

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

   Dit voorbeeld omvat alle Niveau A-regels behalve voor valid-lang, en het zal ook de Niveau AA kleurcontrastregel omvatten.

5. Voer alleen enkele tags uit, maar sluit andere uit

   De runOnly optie kan een object accepteren met een include en exclude eigenschap. Alleen die controles die overeenkomen met een opgenomen tag worden uitgevoerd, behalve die die een tag delen uit de uitsluitlijst.

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

   Dit voorbeeld omvat eerst alle wcag2a en wcag2aa regels. Alle regels die getagd zijn als experimental worden vervolgens verwijderd uit de uit te voeren regels.

callback Parameter

De callback parameter is een functie die wordt aangeroepen wanneer de asynchrone AxeDevTools.run functie voltooid is. De callback functie krijgt twee parameters mee. De eerste parameter zal een fout zijn die binnen Axe DevTools wordt gegooid als AxeDevTools.run niet kan worden voltooid. Als Axe DevTools correct is voltooid, zal de eerste parameter null zijn, en de tweede parameter zal het resultatenobject zijn.

Retourneer Promise

Als de callback niet was gedefinieerd, zal Axe DevTools in plaats daarvan een belofte teruggeven. Axe DevTools vult echter niet de beloftebibliotheek aan. Dus, op systemen zonder ondersteuning voor beloftes, is deze functie niet beschikbaar. Als je niet zeker weet of de systemen waarop je Axe DevTools nodig hebt belofteondersteuning hebben, raden we je aan om in plaats daarvan de callback te gebruiken die door AxeDevTools.run wordt geboden.

error Resultaat

Dit zal ofwel null zijn of een object dat een instantie van Error is. Als je consequent fouten ontvangt, rapporteer dit probleem dan aan Deque Systems.

results Object

De callbackfunctie die wordt doorgegeven als de derde parameter van AxeDevTools.a11yCheck draait op het results object. Dit object heeft twee componenten: een passes array en een violations array. De passes array houdt bij van alle geslaagde tests en gedetailleerde informatie over elke test. Dit leidt tot efficiënter testen, vooral bij handmatige tests, omdat de gebruiker eenvoudig kan bepalen welke tests al geslaagd zijn. Op dezelfde manier houdt de violations array bij van alle mislukte tests en gedetailleerde informatie over elk daarvan.

url

De URL van de pagina die werd getest.

timestamp

De datum en tijd waarop de analyse is voltooid.

passes en violations array

• description - Een tekststring die beschrijft wat de regel doet
• help - Hulpetekst die de test beschrijft die werd uitgevoerd
• helpUrl - Een URL die meer informatie geeft over de details van de overtreding. Linkt naar een pagina op de Deque University-site.
• id - Een unieke identifier voor de regel; zie de lijst met regels
• impact - De ernst van de overtreding. Kan een van klein, matig, ernstig of kritisch zijn als de regel gefaald heeft of null als de controle geslaagd is.
• tags - Een array van tags die aan deze regel zijn toegewezen. De tags kunnen in het option object worden gebruikt om te selecteren welke regels worden uitgevoerd (zie Opties Parameter hierboven).
• nodes - Een array van alle elementen die de regel heeft getest
  • html - Een fragment van HTML van het element
  • impact - De ernst van de overtreding. Kan een van klein, gematigd, ernstig of kritiek zijn als de test is mislukt of null als de controle is geslaagd.
  • target - Een array van selectors waarbij elk element overeenkomt met één niveau van een iframe of frame. Als er één iframe of frame is, moeten er twee items in target zijn. Als er drie iframe-niveaus zijn, moeten er vier items in target zijn.
  • any - Een array van controles waarbij er ten minste één geslaagd moet zijn. Elk item in de array bevat:
    • id - Unieke identificatie voor deze controle. Controle-ID's kunnen hetzelfde zijn als regel-ID's.
    • impact - De ernst van de controle. Kan een van klein, gematigd, ernstig of kritiek zijn. Elke controle die deel uitmaakt van een regel kan verschillende impacts hebben. De hoogste impact van alle mislukte controles wordt gerapporteerd voor de regel.
    • message - De beschrijving waarom deze controle is geslaagd of mislukt.
    • data - Aanvullende, optionele informatie specifiek voor het type controle. Bijvoorbeeld, een kleurcontrastcontrole zou de voorgrondkleur, achtergrondkleur, contrastratio, etc. bevatten.
    • relatedNodes - Een optionele array van informatie over andere knooppunten die betrekking hebben op deze controle. Bijvoorbeeld, een overtreding van de controle op dubbele ID zou de andere selectors met dezelfde dubbele ID opsommen. Elk item in de array bevat de volgende informatie:
      • target - Een array van selectors voor het gerelateerde knooppunt
      • html - De HTML-bron van het gerelateerde knooppunt
  • all - Een array van controles die zijn uitgevoerd waarbij allemaal geslaagd moeten zijn. Elk item in de array bevat dezelfde informatie als de any array.
  • none - Een array van controles die zijn uitgevoerd waarbij allemaal niet geslaagd moeten zijn. Elk item in de array bevat dezelfde informatie als de any array.

Voorbeeld Twee

In dit voorbeeld zullen we de selector voor het hele document doorgeven, geen opties doorgeven, wat betekent dat alle ingeschakelde regels worden uitgevoerd, en een eenvoudige callback-functie hebben die het volledige resultaatobject naar de console logt:

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

passes array

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

In het bovenstaande voorbeeld bevat de passes array twee items die overeenkomen met de twee geteste regels. Het eerste element in de array beschrijft een kleurcontrastcontrole. De velden help, helpUrl en id worden geretourneerd voor elk item in de passes array. De target array heeft één element met een waarde van:

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

Het door target[0] geselecteerde element is gecontroleerd voor de kleurcontrastregel en is geslaagd.

Elk volgend item in de geslaagde array heeft hetzelfde formaat, maar beschrijft de verschillende regels die zijn uitgevoerd.

violations array

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

De violations array bevat één item voor een test die controleert of knoppen geldige alternatieve teksten hebben (de button-name regel). Dit eerste item in de array heeft de velden help, helpUrl en id.

De target array demonstreert hoe we de selectors specificeren wanneer het gespecificeerde knooppunt zich binnen een iframe of frame bevindt. Het eerste element in de target array (target[0]) specificeert de selector naar de iframe die de knop bevat. Het tweede element in de target array (target[1]) specificeert de selector naar de daadwerkelijke knop, maar start van binnen de in target[0] geselecteerde iframe.

Elk volgend item in de overtredingen array heeft hetzelfde formaat, maar beschrijft de regels die toegankelijkheidsovertredingen genereerden.

Voorbeeld Drie

In dit voorbeeld geven we de selector voor het hele document door, inschakelen van twee extra best practice-regels, en hebben een eenvoudige callback-functie die het volledige resultaatobject naar de console logt:

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