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

Je hebt toegang nodig tot ofwel de SaaS-versie of een on-premises versie van Axe DevTools Linter. Zie Een SaaS API-sleutel voor Axe DevTools Linter 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
• headers kan toevoegen (voor de SaaS-versie van Axe DevTools Linter) Authorization
• JSON-verzoekbodies kan aanmaken

Een Stapsgewijze Handleiding voor het Linten van Aangepaste Componenten

Wanneer je Axe DevTools Linter gebruikt om broncode te linten, verstrek je een JSON-body met de bron en configuratie in je HTTP-verzoek. Bijvoorbeeld, de volgende 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, krijg je een toegankelijkheidsfout 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 aangepaste 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 custom-image naar img

Als je een mapping tussen custom-image naar imgbiedt, kan Axe DevTools Linter je aangepaste component als een standaard HTML-element mappen en toegankelijkheidsfouten lokaliseren. Je kunt de mapping specificeren door de global-components configuratie-optie te gebruiken (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

Je kunt een alt attribuut toevoegen aan je custom-image om het toegankelijkheidsprobleem op te lossen (zoals hieronder getoond met het 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 je aangepaste component het vereiste alt attribuut heeft (dat was gekopieerd—met alle andere attributen op de custom-image component—naar het uitgegeven img element):

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

Het attribuut mappen alternative-text

Als je aangepaste afbeeldingscomponent daarentegen een ander attribuut gebruikt om alternatieve tekst aan te geven, kun je dat attribuut in de configuratie specificeren. Stel, je custom-image component gebruikt een alternative-text attribuut in plaats van alt, zoals hieronder getoond:

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

In dat geval kun je een mapping specificeren tussen het alternative-text attribuut en het alt attribuut zoals getoond met de attributes array in de onderstaande JSON-verzoekbody:

{
  "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 je alternative-text attribuut:

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

Je 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 je een custom-button component gebruikt als volgt:

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

(De aangepaste knop zal, met JavaScript en CSS die hier niet zijn opgenomen, een divverbergen en tonen.)

Er zijn twee problemen met dit gebruik:

1. Als je deze custom-button component direct naar een button element er geen tekstinhoud op de knop wordt weergegeven. De intentie van de componentauteur is echter dat het message attribuut als tekstinhoud moet worden gebruikt: <button> waarde van het message attribuut </button>
2. Het uitgezonden 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 reactie:

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

De Speciale <text> Waarde

Om het eerste probleem aan te pakken (tekstinhoud voor het button element afkomstig van een message attribuut), kunt u de speciale <text> waarde gebruiken die een attribuut aan de tekstinhoud van het uitgezonden element koppelt. In dit geval moet de message attribuuttekst worden gekopieerd naar de tekstinhoud van het uitgezonden button element.

Om het verzoek zo te configureren dat Axe DevTools Linter wordt gewaarschuwd 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 sturen:

{
  "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 hebt gedefinieerd als <text>, hebt u Axe DevTools Linter laten weten dat zij dat attribuut moeten beschouwen als vervanging van de tekstinhoud van het HTML- button element met de waarde van het message attribuut.

Helaas, door gebruik van de attributes array, was het enige attribuut dat werd doorgegeven aan het uitgezonden 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.

Het 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 doet zich voor 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 gekopieerd naar het uitgezonden element; dit omvat ook het kopiëren van het ongeldige aria-colindex attribuut.

<element>

Bij complexe componenten wilt u misschien een ander HTML-element uitzenden dan het standaardelement in specifieke gevallen. Bijvoorbeeld, u kunt een knopcomponent hebben die zich meestal als een knop gedraagt en, in andere staten, als een tijdelijke afbeelding. De <element> waarde stelt u in staat een attribuut op uw aangepaste component te specificeren dat het uit te zenden element bepaalt.

{  
  "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 de my-button component aan welk element moet worden uitgezonden. Omdat het uitgezonden img element geen alt attribuut bevat, ontvangt u een foutmelding:

{
  "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 je alleen elementmapping zou gebruiken (waarbij de mapping geen gebruikmaakt van de attributes array), alle attributen standaard zouden worden gekopieerd naar het button element zoals hieronder getoond:

{
  "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 kun je zien dat alle attributen van custom-button worden gecontroleerd op toegankelijkheidsproblemen, en dat er twee fouten worden 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 (en daarmee alle attributen te kopiëren naar het uitgegeven, standaard HTML-element) en vervolgens te bekijken welke attributen aan de configuratie moeten worden toegevoegd (of de attributen van de aangepaste componenten naar andere attributen moeten worden gemapt of dat je <text> of aria-*moet gebruiken).

Standaardattributen

Standaardattributen stellen je in staat om waarden in te stellen voor attributen in je configuratiebestand in plaats van één attribuut naar een ander te mappen. Bijvoorbeeld, de volgende voorbeeldconfiguratie 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 te specificeren wanneer ze de custom-menu component in hun code gebruiken. De implicatie is dat de implementatie van jouw aangepaste component deze attributen maakt op het uitgangselement en de waarden instelt, in plaats van dat gebruikers ze moeten instellen wanneer ze jouw component gebruiken.

Optioneel kan de name waarde in de configuratie worden ingesteld op null , waardoor Axe DevTools Linter alle role attributen negeert die gebruikers hebben gespecificeerd op custom-menu in gelinde code.

Analyseren van Overtredingen in Aangepaste Componenten

Wanneer je veel aangepaste componenten hebt geconfigureerd, kan het moeilijk zijn om te bepalen welke overtredingen in de reactie afkomstig zijn van aangepaste component-mappings versus standaard HTML. Het toevoegen van "properties": ["customName"] aan je aanvraaglichaam zorgt ervoor dat de Axe DevTools Linter een customName eigenschap toevoegt aan elke fout die origineert van een aangepast gemapte component.

Voortbouwend op het custom-image voorbeeld hierboven, door "properties": ["customName"] toe te voegen aan de aanvraag:

{
  "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 in de fout die laat zien welke aangepaste component de overtreding veroorzaakte:

{
  "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 aangeboden.
• Een Axe DevTools Linter SaaS API-sleutel verkrijgen laat zien hoe je een API-sleutel kunt verkrijgen om de Software as a Service (SaaS) versie van Axe DevTools Linter te gebruiken.