Lintieren von benutzerdefinierten Komponenten mit dem REST-Endpunkt

In diesem Artikel wird gezeigt, wie Sie mit dem axe DevTools Linter REST-Endpunkt Zugänglichkeitsfehler in benutzerdefinierten Komponenten finden.

Voraussetzungen

Sie benötigen Zugriff auf die SaaS-Version oder eine lokale Version von axe DevTools Linter. Weitere Informationen finden Sie unter Erhalten eines axe DevTools Linter SaaS-API-Schlüssels oder Einrichten der On-Premises-Edition von axe DevTools Linter .

Sie benötigen außerdem ein REST-Tool, das:

• Kann POST-Anfragen senden

– Kann Authorization Header hinzufügen (für die SaaS-Version von axe DevTools Linter)

• Ermöglicht die Erstellung von JSON-Anforderungskörpern

Eine exemplarische Vorgehensweise zum Lintieren benutzerdefinierter Komponenten

Wenn Sie axe DevTools Linter zum Linten des Quellcodes verwenden, stellen Sie einen JSON-Text bereit, der die Quelle und Konfiguration in Ihrer HTTP-Anforderung enthält. Beispielsweise zeigt das folgende HTML die Verwendung des img Elements:

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

(Dies ist ein stark vereinfachtes Beispiel, das nur das Lintieren demonstrieren soll, und kein tatsächliches Beispiel aus der Praxis.)

Der JSON-Körper der an axe DevTools Linter zu sendenden Anfrage würde folgendermaßen aussehen:

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

Da dieses img Element kein alt Attribut hat, erhalten Sie vom axe DevTools Linter einen Zugriffsfehler:

{
  "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"
      }
    ]
  }
}

Eine benutzerdefinierte Bildkomponente

Das folgende Beispiel zeigt eine custom-image benutzerdefinierte Komponente:

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

Um das HTML mithilfe einer POST-Anfrage an axe DevTools Linter zu senden, verwenden Sie Folgendes als JSON-Text:

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

Der Server antwortet ohne Zugänglichkeitsfehler, da keine Zuordnung zwischen custom-image und img besteht. Daher kann axe DevTools Linter ein fehlendes alt Attribut nicht kennzeichnen:

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

Zuordnung custom-image zu img

Wenn Sie eine Zuordnung zwischen custom-image und img angeben, kann axe DevTools Linter Ihre benutzerdefinierte Komponente als Standard-HTML-Element zuordnen und Barrierefreiheitsfehler lokalisieren. Sie können die Zuordnung mithilfe der global-components Konfigurationsoption (Teil des config Objekts) angeben:

{
  "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 antwortet jetzt mit Folgendem:

{
  "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"
      }
    ]
  }
}

Sie können dieselbe Zuordnung wie oben auch mit einer der folgenden Syntaxen angeben:

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

Oder alternativ, indem Sie abkürzen element als el:

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

Behebung des Zugänglichkeitsproblems

Sie können ein alt Attribut zu Ihrem custom-image hinzufügen, um das Zugänglichkeitsproblem zu beheben (wie unten mit dem JSON-Anforderungstext gezeigt):

{
  "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"
}

Der Server antwortet mit dem folgenden leeren errors Array, da Ihre benutzerdefinierte Komponente das erforderliche alt Attribut hat (das – zusammen mit allen anderen Attributen der custom-image Komponente – in das ausgegebene img Element kopiert wurde):

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

Zuordnung des alternative-text Attributs

Wenn Ihre benutzerdefinierte Bildkomponente stattdessen ein anderes Attribut zur Angabe von alternativem Text verwendet, können Sie dieses Attribut in der Konfiguration angeben. Angenommen, Ihre custom-image Komponente verwendet ein alternative-text Attribut anstelle von alt, wie unten gezeigt:

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

In diesem Fall könnten Sie eine Zuordnung zwischen dem alternative-text -Attribut und dem alt -Attribut angeben, wie mit dem attributes -Array im unten dargestellten JSON-Anforderungskörper gezeigt:

{
  "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 antwortet mit Folgendem, weil die alt-text Regel durch Ihr alternative-text Attribut erfüllt wurde:

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

Sie können auch als attributes abkürzen attrs:

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

Spezielle Attributwerte: <text>, aria-* and <element>

Angenommen, Sie verwenden eine custom-button Komponente wie folgt:

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

(Die benutzerdefinierte Schaltfläche wird mithilfe von JavaScript und CSS, das hier nicht enthalten ist, ein div ausblenden und anzeigen.)

Diese Verwendung bringt zwei Probleme mit sich:

1. Wenn Sie diese custom-button Komponente direkt einem button Element zuordnen, wird auf der Schaltfläche kein Textinhalt angezeigt. Die Absicht des Komponentenautors besteht jedoch darin, dass das message Attribut als Textinhalt verwendet werden soll: <button> Wert des message Attributs </button>
2. Das ausgegebene button Element hat die implizite Rolle button, daher ist das aria-colindex Attribut falsch und sollte entfernt werden.

Wenn Sie den obigen Code an axe DevTools Linter senden (ohne global-components Mapping), erhalten Sie diese Antwort:

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

Der Besonderer <text> Wert

Um das erste Problem (Textinhalt für das button Element, der von einem message Attribut stammt) zu lösen, können Sie den speziellen <text> Wert verwenden, der ein Attribut dem Textinhalt des ausgegebenen Elements zuordnet. In diesem Fall sollte der Text des message Attributs in den Textinhalt des ausgegebenen button Elements kopiert werden.

Um die Anforderung so zu konfigurieren, dass axe DevTools Linter benachrichtigt wird, dass das message -Attribut als Textinhalt für das HTML- button -Element betrachtet werden soll, können Sie den speziellen <text> -Wert verwenden und die folgende Anforderung senden:

{
  "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"
}

Da Sie das message Attribut als <text> definiert haben, haben Sie axe DevTools Linter angewiesen, dieses Attribut als Ersetzen des Textinhalts des HTML- button Elements durch den Wert des message Attributs zu betrachten.

Leider wurde durch die Verwendung des attributes Arrays nur das button Attribut an das ausgegebene message Element weitergegeben; alle Attribute, die nicht im attributes Array enthalten sind, werden nicht weitergegeben. Dies bedeutet, dass die falsche aria-colindex vom Server nicht erkannt wurde.

Verwenden von aria-*

Sie können den speziellen Wert aria-* verwenden, um alle ARIA-Attribute zu übergeben, wie unten gezeigt:

{
  "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"
}

Der Server antwortet mit:

{
  "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"
      }
    ]
  }
}

Dieser Fehler tritt auf, weil das button Element ein implizites role="button" Element hat und die Verwendung von aria-colindex bei Schaltflächen ungültig ist. Mit dem Attribut „aria-*, all ARIA attributes are copied to the emitted element; this includes copying the invalid aria-colindex“.

<element>

Bei komplexen Komponenten möchten Sie in bestimmten Fällen möglicherweise ein anderes HTML-Element als das Standardelement ausgeben. Sie verfügen beispielsweise möglicherweise über eine Schaltflächenkomponente, die sich normalerweise wie eine Schaltfläche und in anderen Zuständen wie ein Platzhalterbild verhält. Mit dem <element> Wert können Sie ein Attribut für Ihre benutzerdefinierte Komponente angeben, das das ausgegebene Element bestimmt.

{  
  "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 diesem Fall gibt das use Attribut der my-button Komponente das auszugebende Element an. Da das ausgegebene img Element kein alt Attribut enthält, erhalten Sie eine Fehlermeldung:

{
  "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
      }
    ]
  }
}

Implizite Übergabe aller Attribute

Beachten Sie, dass, wenn Sie nur die Elementzuordnung verwendet hätten (wobei die Zuordnung das attributes -Array nicht verwendet), alle Attribute standardmäßig in das button -Element kopiert würden, wie unten gezeigt:

{
  "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"
}

Anhand dieser Serverantwort können Sie erkennen, dass alle Attribute von custom-button auf Barrierefreiheitsprobleme überprüft wurden und dabei zwei Fehler gefunden wurden:

{
  "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"
      }
    ]
  }
}

Das obige Beispiel zeigt, dass ein praktischer erster Schritt beim Linten benutzerdefinierter Komponenten darin besteht, mit einer Elementzuordnung zu beginnen (wobei alle Attribute in das ausgegebene Standard-HTML-Element kopiert werden) und dann zu prüfen, welche Attribute der Konfiguration hinzugefügt werden müssen (ob die Attribute der benutzerdefinierten Komponente anderen Attributen zugeordnet werden sollen oder ob Sie <text> oder aria-* verwenden müssen).

Standardattribute

Mit Standardattributen können Sie Werte für Attribute in Ihrer Konfigurationsdatei festlegen, anstatt ein Attribut einem anderen zuzuordnen. Beispielsweise zeigt die folgende Beispielkonfiguration eine custom-menu Komponente, die einem li Element mit einem role von * Menü zugeordnet ist:*

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

Da das Attribut role den Standardwert Menü hat, der in der Konfigurationsdatei festgelegt ist, müssen Benutzer kein Attribut role angeben, wenn sie die Komponente custom-menu in ihrem Code verwenden. Dies hat zur Folge, dass die Implementierung Ihrer benutzerdefinierten Komponente diese Attribute im Ausgabeelement erstellt und ihre Werte festlegt, anstatt dass Benutzer diese festlegen müssen, wenn sie Ihre Komponente verwenden.

Optional wird der name Wert in der Konfiguration auf null gesetzt, wodurch axe DevTools Linter alle role Attribute ignoriert, die Benutzer im gelinteten Code angegeben haben custom-menu .

Siehe auch

– axe DevTools Linter REST API-Referenz enthält weitere Informationen zur Verwendung der verschiedenen REST-Endpunkte, die von axe DevTools Linter bereitgestellt werden.

• Erhalten eines axe DevTools Linter SaaS-API-Schlüssels zeigt, wie Sie einen API-Schlüssel erhalten, um die Software-as-a-Service-Version (SaaS) von axe DevTools Linter zu verwenden.