Linten van Aangepaste Componenten met het REST-eindpunt

Dit artikel laat zien hoe je het Axe DevTools Linter REST-eindpunt kunt gebruiken om toegankelijkheidsfouten in aangepaste componenten te vinden.

Vereisten

U heeft toegang nodig tot ofwel de SaaS-versie of een on-premises versie van Axe DevTools Linter. Zie Een Axe DevTools Linter SaaS API-sleutel verkrijgen of De On-Premises Editie van Axe DevTools Linter instellen voor meer informatie.

Je hebt ook een REST-tool nodig die:

• POST-verzoeken kan verzenden
• Kan Authorization headers toevoegen (voor de SaaS-versie van Axe DevTools Linter)
• JSON-verzoekbodies kan aanmaken

Een Stapsgewijze Handleiding voor het Linten van Aangepaste Componenten

Wanneer u Axe DevTools Linter gebruikt om broncode te linten, verstrekt u een JSON-body met de broncode en configuratie in uw HTTP-verzoek. Bijvoorbeeld, de onderstaande HTML toont het gebruik van het img element:

<img src="path/to/image.jpg"/>

(Dit is een sterk vereenvoudigd voorbeeld alleen om linten te demonstreren in plaats van een daadwerkelijke real-world voorbeeld.)

De JSON-body van het verzoek dat naar Axe DevTools Linter moet worden gestuurd, zou er als volgt uitzien:

{ 
  "source": "<img src=\"path/to/image.jpg\"/>",
  "filename": "image-demo.html"
}

Omdat dit img element geen alt attribuut heeft, zult u een toegankelijkheidsfout krijgen van Axe DevTools Linter:

{
  "report": {
    "errors": [
      {
        "column": 1,
        "description": "Ensures <img> elements have alternate text or a role of none or presentation",
        "endColumn": 31,
        "helpURL": "https://dequeuniversity.com/rules/axe/4.4/image-alt?application=axe-linter",
        "lineContent": "<img src=\"path/to/image.jpg\"/>",
        "lineNumber": 1,
        "linterType": "html",
        "ruleId": "image-alt"
      }
    ]
  }
}

Een Aangepaste Afbeelding Component

Het volgende voorbeeld toont een voorbeeld van een custom-image aangepast component:

<custom-image src="path/to/image.jpg"></custom-image>

Om de HTML naar Axe DevTools Linter te sturen met een POST-verzoek, gebruik je het volgende als de JSON-body:

{
  "source": "<custom-image src=\"path/to/image.jpg\"></custom-image>",
  "filename": "custom-image.html"
}

De server reageert zonder toegankelijkheidsfouten omdat er geen mapping is tussen custom-image en img, dus Axe DevTools Linter kan geen ontbrekend alt attribuut markeren:

{
  "report": {
    "errors": []
  }
}

Mapping van custom-image naar img

Als u een mapping tussen custom-image en img levert, kan Axe DevTools Linter uw aangepaste component als een standaard HTML-element mappen en toegankelijkheidsfouten lokaliseren. U kunt de mapping specificeren met behulp van de global-components configuratieoptie (onderdeel van het config object):

{
  "config": {
    "global-components": {
      "custom-image": "img"
    }
  },
  "filename": "c-image.html",
  "source": "<custom-image src=\"path/to/image.jpg\"></custom-image>\n\n"
}

Axe DevTools Linter reageert nu met het volgende:

{
  "report": {
    "errors": [
      {
        "column": 1,
        "description": "Ensures <img> elements have alternate text or a role of none or presentation",
        "endColumn": 54,
        "helpURL": "https://dequeuniversity.com/rules/axe/4.4/image-alt?application=axe-linter",
        "lineContent": "<custom-image src=\"path/to/image.jpg\"></custom-image>",
        "lineNumber": 1,
        "linterType": "html",
        "ruleId": "image-alt"
      }
    ]
  }
}

Je kunt dezelfde mapping ook aangeven als hierboven met een van deze syntaxes:

{
  "config": {
    "global-components": {
      "custom-image": {
        "element": "img"
      }
    }
  }
}

Of, als alternatief, door element af te korten als el:

{
  "config": {
    "global-components": {
      "custom-image": {
        "el": "img"
      }
    }
  }
}

De toegankelijkheidsproblemen oplossen

U kunt een alt attribuut toevoegen aan uw custom-image om het toegankelijkheidsprobleem op te lossen (zoals hieronder wordt getoond met de JSON-body van het verzoek):

{
  "config": {
    "global-components": {
      "custom-image": "img"
    }
  },
  "filename": "c-image.html",
  "source": "<custom-image src=\"path/to/image.jpg\" alt=\"alt text\"></custom-image>\n\n"
}

De server reageert met de volgende lege errors array omdat uw aangepaste component het vereiste alt attribuut heeft (dat werd gekopieerd—met alle andere attributen op het custom-image component—naar het uitgegeven img element):

{
  "report": {
    "errors": []
  }
}

Mapping van het alternative-text attribuut

Als uw aangepaste afbeeldingscomponent in plaats daarvan een ander attribuut gebruikt om alternatieve tekst aan te geven, kunt u dat attribuut in de configuratie specificeren. Stel bijvoorbeeld dat uw custom-image component een alternative-text attribuut gebruikt in plaats van alt, zoals hieronder wordt getoond:

<custom-image src="path/to/image.jpg" alternative-text="alt text"></custom-image>

In dit geval kunt u een mapping specificeren tussen het alternative-text attribuut en het alt attribuut, zoals weergegeven met de attributes array in de JSON-verzoekbody hieronder:

{
  "config": {
    "global-components": {
      "custom-image": {
        "element": "img",
        "attributes": [
          {
            "alternative-text": "alt"
          }
        ]
      }
    }
  },
  "filename": "c-image.html",
  "source": "<custom-image src=\"path/to/image.jpg\" alternative-text=\"alt text\"></custom-image>\n\n"
}

Axe DevTools Linter reageert met het volgende omdat de alt-text regel is voldaan door uw alternative-text attribuut:

{
  "report": {
    "errors": []
  }
}

U kunt ook attributes afkorten als attrs:

{
  "config": {
    "global-components": {
      "custom-image": {
        "attrs": [
          {
            "alternative-text": "alt"
          }
        ],
        "element": "img"
      }
    }
  }
}

Speciale Attribuutwaarden: <text>, aria-* en <element>

Stel dat u een custom-button component als volgt gebruikt:

<custom-button aria-controls="expand-region" aria-expanded="false" aria-colindex="1" message="Show Region"></custom-button>

(De aangepaste knop, gebruikmakend van JavaScript en CSS die hier niet is inbegrepen, zal een div verbergen en tonen.)

Er zijn twee problemen met dit gebruik:

1. Als u dit custom-button component direct naar een button element zou mappen, zou er geen tekstinhoud zijn om op de knop weer te geven. De bedoeling van de component-auteur is echter dat het message attribuut als tekstinhoud moet worden gebruikt: <button> waarde van het message attribuut </button>
2. Het uitgegeven button element heeft een impliciete rol van button, dus het aria-colindex attribuut is onjuist en moet worden verwijderd.

Als u de bovenstaande code naar Axe DevTools Linter stuurt (zonder global-components mapping), ontvangt u deze respons:

{
  "report": {
    "errors": []
  }
}

De Speciale <text> Waarde

Om het eerste probleem op te lossen (tekstinhoud voor het button element afkomstig van een message attribuut), kunt u de speciale <text> waarde gebruiken die een attribuut naar de tekstinhoud van het uitgegeven element toewijst. In dit geval moet de tekst van het message attribuut worden gekopieerd naar de tekstinhoud van het uitgegeven button element.

Om het verzoek zodanig te configureren dat Axe DevTools Linter wordt gealarmeerd dat het message attribuut als tekstinhoud voor het HTML button element moet worden beschouwd, kunt u de speciale <text> waarde gebruiken en het volgende verzoek verzenden:

{
  "config": {
    "global-components": {
      "custom-button": {
        "attributes": [
          {
            "message": "<text>"
          }
        ],
        "element": "button"
      }
    }
  },
  "filename": "aria-button.html",
  "source": "<custom-button aria-controls=\"expand-region\" aria-expanded=\"false\" aria-colindex=\"1\" message=\"Show Region\"></custom-button>\n"
}

Omdat u het message attribuut als <text> hebt gedefinieerd, hebt u Axe DevTools Linter verteld dat attribuut te beschouwen als vervangende tekstinhoud van het HTML button element met de waarde van het message attribuut.

Helaas, door de attributes array te gebruiken, was het enige attribuut dat werd doorgegeven aan het uitgegeven button element alleen het message attribuut; alle attributen die niet in de attributes array staan, worden niet doorgegeven. Dit betekent dat de onjuiste aria-colindex niet door de server werd opgemerkt.

Gebruik van aria-*

U kunt de speciale aria-* waarde gebruiken om alle ARIA-attributen door te geven, zoals hieronder wordt getoond:

{
  "config": {
    "global-components": {
      "custom-button": {
        "attributes": [
          {
            "message": "<text>"
          },
          "aria-*"
        ],
        "element": "button"
      }
    }
  },
  "filename": "aria-button.html",
  "source": "<custom-button aria-controls=\"expand-region\" aria-expanded=\"false\" aria-colindex=\"1\" message=\"Show Region\"></custom-button>\n"
}

De server reageert met:

{
  "report": {
    "errors": [
      {
        "column": 1,
        "description": "Ensures ARIA attributes are allowed for an element's role",
        "endColumn": 124,
        "helpURL": "https://dequeuniversity.com/rules/axe/4.4/aria-allowed-attr?application=axe-linter",
        "lineContent": "<custom-button aria-controls=\"expand-region\" aria-expanded=\"false\" aria-colindex=\"1\" message=\"Show Region\"></custom-button>",
        "lineNumber": 1,
        "linterType": "html",
        "ruleId": "aria-allowed-attr"
      }
    ]
  }
}

Deze fout treedt op omdat het button element een impliciete role="button" heeft en het gebruik van aria-colindex ongeldig is bij knoppen. Met aria-* worden alle ARIA-attributen naar het uitgegeven element gekopieerd; dit omvat ook het kopiëren van het ongeldige aria-colindex attribuut.

<element>

Bij complexe componenten wilt u wellicht in specifieke gevallen een ander HTML-element dan het standaard element uitgeven. Bijvoorbeeld, u heeft een knopcomponent die typisch als knop fungeert en, in andere staten, als een tijdelijke afbeelding. De <element> waarde stelt u in staat een attribuut op uw aangepaste component aan te geven dat bepaalt welk element wordt uitgegeven.

{  
  "config": {
    "global-components": {
      "my-button": {
        "element": "button",
        "attributes": [
         {
          "use": "<element>"
         },
         'src',
         'alt'
        ]
      } 
    }
  },

  "filename": "aria-button.html",
  "source": "<my-button use=\"img\" src=\"globe.jpg\"></my-button>"
}

In dit geval geeft het use attribuut op het my-button component aan welk element moet worden uitgegeven. Omdat het uitgegeven img element geen alt attribuut bevat, krijgt u een fout:

{
  "report": {
    "errors": [
      {
        "ruleId": "image-alt",
        "helpURL": "https://dequeuniversity.com/rules/axe/4.10/image-alt?application=axe-linter",
        "description": "Images must have alternative text",
        "lineNumber": 1,
        "column": 1,
        "linterType": "html",
        "lineContent": "<my-button use=\"img\" src=\"globe.jpg\"></my-button>",
        "endColumn": 50
      }
    ]
  }
}

Alle Attributen Impliciet Doorvoeren

Merk op dat als u alleen elementmapping zou gebruiken (waarbij de mapping de attributes array niet gebruikt), standaard alle attributen worden gekopieerd naar het button element zoals hieronder wordt weergegeven:

{
  "config": {
    "global-components": {
      "custom-button": "button"
    }
  },
  "filename": "aria-button.html",
  "source": "<custom-button aria-controls=\"expand-region\" aria-expanded=\"false\" aria-colindex=\"1\" message=\"Show Region\"></custom-button>\n"
}

Met deze serverreactie kunt u zien dat alle attributen van custom-button worden gecontroleerd op toegankelijkheidsproblemen, en er worden twee fouten gevonden:

{
  "report": {
    "errors": [
      {
        "column": 1,
        "description": "Ensures ARIA attributes are allowed for an element's role",
        "endColumn": 124,
        "helpURL": "https://dequeuniversity.com/rules/axe/4.4/aria-allowed-attr?application=axe-linter",
        "lineContent": "<custom-button aria-controls=\"expand-region\" aria-expanded=\"false\" aria-colindex=\"1\" message=\"Show Region\"></custom-button>",
        "lineNumber": 1,
        "linterType": "html",
        "ruleId": "aria-allowed-attr"
      },
      {
        "column": 1,
        "description": "Ensures buttons have discernible text",
        "endColumn": 124,
        "helpURL": "https://dequeuniversity.com/rules/axe/4.4/button-name?application=axe-linter",
        "lineContent": "<custom-button aria-controls=\"expand-region\" aria-expanded=\"false\" aria-colindex=\"1\" message=\"Show Region\"></custom-button>",
        "lineNumber": 1,
        "linterType": "html",
        "ruleId": "button-name"
      }
    ]
  }
}

Het bovenstaande voorbeeld laat zien dat een praktische eerste stap bij het beginnen met het linten van aangepaste componenten zou zijn om te beginnen met een elementmapping (waardoor alle attributen worden gekopieerd naar het uitgegeven, standaard HTML-element) en vervolgens te zien welke attributen aan de configuratie moeten worden toegevoegd (of de attributen van het aangepaste component moeten worden gemapt naar andere attributen of dat u <text> of aria-* moet gebruiken).

Standaardattributen

Standaardattributen laten u waarden instellen voor attributen in uw configuratiebestand in plaats van één attribuut naar een ander te mappen. Bijvoorbeeld, de volgende configuratie toont een custom-menu component gemapt naar een li element met een role van *menu*:

{
  "config": {
    "global-components": {
      "custom-menu": {
        "element": "li",
        "attributes": [
          {
            "role": {
              "name": null,
              "default": "menu"
            }
          }
        ]
      }
    }
  }
}

Omdat het role attribuut een standaardwaarde van *menu* heeft, ingesteld in het configuratiebestand, hoeven gebruikers geen role attribuut op te geven wanneer ze het custom-menu component in hun code gebruiken. De implicatie is dat de implementatie van uw aangepaste component deze attributen op het uitvoerelement aanmaakt en hun waarden instelt in plaats van gebruikers te verplichten ze in te stellen wanneer ze uw component gebruiken.

Optioneel wordt de name waarde ingesteld op null in de configuratie, wat ervoor zorgt dat Axe DevTools Linter alle door gebruikers gespecificeerde role attributen op custom-menu in gelinte code negeert.

Analyseren van Overtredingen in Aangepaste Componenten

Wanneer u veel aangepaste componenten hebt geconfigureerd, kan het moeilijk zijn om te zien welke overtredingen in de reactie afkomstig zijn van aangepaste componentmappings versus standaard HTML. Door "properties": ["customName"] aan uw aanvraagbody toe te voegen, zorgt u ervoor dat Axe DevTools Linter een customName eigenschap toevoegt aan elke fout die afkomstig is van een aangepast gemapt component.

Voortbouwend op het bovenstaande custom-image voorbeeld, door "properties": ["customName"] aan het verzoek toe te voegen:

{
  "properties": ["customName"],
  "config": {
    "global-components": {
      "custom-image": "img"
    }
  },
  "filename": "c-image.html",
  "source": "<custom-image src=\"path/to/image.jpg\"></custom-image>\n\n"
}

De reactie bevat nu een customName eigenschap op de fout die aangeeft welk aangepast component de overtreding heeft veroorzaakt:

{
  "report": {
    "errors": [
      {
        "column": 1,
        "customName": "custom-image",
        "description": "Ensures <img> elements have alternate text or a role of none or presentation",
        "endColumn": 54,
        "helpURL": "https://dequeuniversity.com/rules/axe/4.4/image-alt?application=axe-linter",
        "lineContent": "<custom-image src=\"path/to/image.jpg\"></custom-image>",
        "lineNumber": 1,
        "linterType": "html",
        "ruleId": "image-alt"
      }
    ]
  }
}

Fouten van componenten die geen deel uitmaken van een aangepaste mapping zullen geen customName eigenschap hebben.

Zie Ook

• Axe DevTools Linter REST API Referentie bevat meer informatie over het gebruik van de verschillende REST-eindpunten die door Axe DevTools Linter worden geleverd.
• Een Axe DevTools Linter SaaS API-sleutel verkrijgen toont hoe je een API-sleutel kunt verkrijgen om de Software as a Service (SaaS)-versie van Axe DevTools Linter te gebruiken.