Free Trial

Linting benutzerdefinierter Komponenten mit dem REST-Endpunkt

This page is not available in the language you requested. You have been redirected to the English version of the page.
Link to this page copied to clipboard

Eine Anleitung zur Verwendung des Axe DevTools Linter zum Linten benutzerdefinierter Komponenten mit dem REST-Endpunkt

Free Trial
Not for use with personal data

Dieser Artikel zeigt, wie man den Axe DevTools Linter REST-Endpunkt verwendet, um Barrierefreiheitsfehler in benutzerdefinierten Komponenten zu finden.

important

Dieser Artikel richtet sich an Nutzer des Axe DevTools Linter REST-Endpunkts. Wenn Sie die Axe Accessibility Linter-Erweiterung für VS Code oder das Plugin für JetBrains verwenden, sehen Sie Linting benutzerdefinierter Komponenten mit der Axe Accessibility Linter-Erweiterung für VS Code oder dem Plugin für JetBrains für weitere Informationen.

Voraussetzungen

Sie benötigen entweder Zugang zur SaaS-Version oder zur On-Premises-Version von Axe DevTools Linter. Siehe Bezug eines SaaS-API-Schlüssels für Axe DevTools Linter oder Einrichtung der On-Premises-Edition von Axe DevTools Linter für weitere Informationen.

Sie benötigen auch ein REST-Tool, das:

  • POST-Anfragen senden kann
  • Authorization-Header hinzufügen kann (für die SaaS-Version von Axe DevTools Linter)
  • die Erstellung von JSON-Anfragekörpern ermöglicht

Ein Leitfaden zum Linten benutzerdefinierter Komponenten

Wenn Sie Axe DevTools Linter zum Linten von Quellcode verwenden, stellen Sie einen JSON-Körper bereit, der den Quellcode und die Konfiguration in Ihrer HTTP-Anfrage enthält. Zum Beispiel zeigt das folgende HTML die Verwendung des img-Elements:

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

(Dies ist ein stark vereinfachtes Beispiel, das lediglich die Lintersuche anstelle eines tatsächlichen Beispiels aus der Praxis demonstrieren soll.)

Der JSON-Körper der Anfrage, die an Axe DevTools Linter gesendet werden soll, würde folgendermaßen aussehen:

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

Sie senden dieses JSON als REST-POST-Anfrage an den /linter-source-Endpunkt von Axe DevTools Linter. Für weitere Informationen sehen Sie Der Lint-Endpunkt in der Referenzdokumentation.

Um diesem Leitfaden zu folgen, können Sie jedes REST-Tool verwenden, das POST-Anfragen mit JSON-Anfragekörpern senden kann. Die folgenden Beispiele zeigen den an Axe DevTools Linter gesendeten Anfragekörper und den JSON-Antwortkörper, der die von Axe DevTools Linter gefundenen Barrierefreiheitsfehler anzeigt.

Da dieses img-Element kein alt-Attribut hat, erhalten Sie einen Barrierefreiheitsfehler von 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"
      }
    ]
  }
}

Eine benutzerdefinierte Bildkomponente

Das folgende Beispiel zeigt eine custom-image-benutzerdefinierte Komponente:

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

Um das HTML mit einer POST-Anfrage an Axe DevTools Linter zu senden, verwenden Sie das Folgende als JSON-Körper:

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

Der Server antwortet ohne Barrierefreiheitsfehler, weil es keine Zuordnung zwischen custom-image und img gibt, sodass Axe DevTools Linter kein fehlendes alt-Attribut markieren kann:

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

Zuordnung von custom-image zu img

Wenn Sie eine Zuordnung zwischen custom-image und img bereitstellen, kann Axe DevTools Linter Ihre benutzerdefinierte Komponente als standardmäßiges HTML-Element zuordnen und Barrierefreiheitsfehler erkennen. Sie können die Zuordnung über die 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 mit einer der folgenden Notationen angeben:

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

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

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

Wenn Sie eine Elementzuordnung wie oben gezeigt verwenden, werden alle Attribute von der benutzerdefinierten Komponente auf das ausgegebene Element kopiert, und dieses Element wird gelintet.

Behebung des Barrierefreiheitsproblems

Sie können ein alt-Attribut zu Ihrem custom-image hinzufügen, um das Barrierefreiheitsproblem zu beheben (wie unten mit dem JSON-Körper der Anfrage 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 folgendem leeren errors-Array, weil Ihre benutzerdefinierte Komponente das erforderliche alt-Attribut hat (das zusammen mit alle weiteren Attributen auf der custom-image-Komponente auf das ausgegebene img-Element kopiert wurde):

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

Zuordnung des alternative-text-Attributs

Wenn Ihre benutzerdefinierte Bildkomponente stattdessen ein anderes Attribut verwendet, um alternativen Text anzugeben, 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 gezeigten JSON-Anfragekö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"
}
note

Beachten Sie, dass sich die global-components-Konfiguration leicht von der früheren Zuordnung einer benutzerdefinierten Komponente zu einem HTML-Element unterscheidet. Mit nur Elementen verwenden Sie eine Zuordnung von einer Zeichenkette ("custom-image") zu einer anderen Zeichenkette ("img"). Mit der Aufnahme des attributes-Arrays sind Sie nun verpflichtet, die element- (oder el-) Eigenschaft zu verwenden, um das ausgegebene HTML-Element anzugeben.

Axe DevTools Linter antwortet folgendermaßen, weil die alt-text-Regel durch Ihr alternative-text-Attribut erfüllt wurde:

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

Da Sie das attributes-Array in der Konfiguration angegeben haben, werden bei der Zuordnung vom custom-image zu img die nur die im attributes-Array angegebenen Attribute auf das ausgegebene HTML-Element kopiert.

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

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

Spezielle Attributwerte: <text>, aria-* und <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>

(Der benutzerdefinierte Button wird unter Verwendung von hier nicht enthaltenem JavaScript und CSS ein div ausblenden und anzeigen.)

Es gibt zwei Probleme mit dieser Verwendung:

  1. Wenn Sie diese custom-button-Komponente direkt einem button-Element zuordnen, wird kein Textinhalt auf dem Button angezeigt. Die Absicht des Komponentenautors ist jedoch, dass das message-Attribut als Textinhalt verwendet werden sollte: <button> Wert des message-Attributs </button>
  2. Das ausgegebene button-Element hat eine implizite Rolle von 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-Zuordnung), erhalten Sie folgende Antwort:

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

Der spezielle <text>-Wert

Um das erste Problem zu adressieren (Textinhalt für das button-Element, der von einem message-Attribut stammt), 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 darüber informiert wird, dass das message-Attribut als Textinhalt für das HTML-Element button 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 mitgeteilt, dass dieses Attribut dafür betrachtet werden soll, den Textinhalt des HTML-Elements button durch den Wert des message-Attributs zu ersetzen.

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

Verwendung von aria-*

Sie können den speziellen aria-*-Wert verwenden, um alle ARIA-Attribute zu übertragen, 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, da das button-Element eine implizite role="button" hat und die Verwendung von aria-colindex mit Schaltflächen ungültig ist. Mit aria-* werden alle ARIA-Attribute auf das ausgegebene Element kopiert; dies schließt das Kopieren des ungültigen aria-colindex-Attributs ein.

<element>

Bei komplexen Komponenten möchten Sie möglicherweise in bestimmten Fällen ein anderes HTML-Element als das Standard-Element ausgeben. Beispielsweise könnten Sie eine Schaltflächenkomponente haben, die sich normalerweise wie eine Schaltfläche verhält und in anderen Zuständen wie ein Platzhalterbild. Der <element>-Wert ermöglicht es Ihnen, ein Attribut auf Ihrer benutzerdefinierten Komponente festzulegen, 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 zeigt das use-Attribut auf der my-button-Komponente an, welches Element ausgegeben werden soll. Da das ausgegebene img-Element kein alt-Attribut enthält, erhalten Sie einen Fehler:

{
  "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 Attribute implizit übergeben

Beachten Sie, dass, wenn Sie nur die Elementzuordnung verwendet hätten (bei der die Zuordnung nicht das attributes-Array verwendet), alle Attribute standardmäßig auf das button-Element kopiert worden wären, 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"
}

Bei dieser Serverantwort können Sie sehen, dass alle Attribute von custom-button auf Barrierefreiheitsprobleme überprüft werden und zwei Fehler gefunden werden:

{
  "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 sinnvoller erster Schritt beim Beginn der Überprüfung benutzerdefinierter Komponenten darin besteht, mit einer Elementzuordnung zu beginnen (dabei werden alle Attribute auf das ausgegebene, standardmäßige HTML-Element kopiert) und dann zu sehen, welche Attribute zur Konfiguration hinzugefügt werden müssen (ob die Attribute der benutzerdefinierten Komponente verschiedenen Attributen zugeordnet werden sollen oder ob Sie <text> oder aria-* verwenden müssen).

Standardattribute

Standardattribute ermöglichen es Ihnen, Werte für Attribute in Ihrer Konfigurationsdatei festzulegen, anstatt ein Attribut einem anderen zuzuordnen. Zum Beispiel zeigt die folgende Beispielkonfiguration eine custom-menu-Komponente, die auf ein li-Element mit einem role von Menü zugeordnet ist.

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

Da das role-Attribut einen im Konfigurationsfile festgelegten Standardwert von Menü hat, müssen Benutzer kein role-Attribut angeben, wenn sie die custom-menu-Komponente in ihrem Code verwenden. Die Implikation ist, dass die Implementierung Ihrer benutzerdefinierten Komponente diese Attribute auf dem Ausgangselement erstellt und deren Werte festlegt, anstatt die Benutzer zu zwingen, sie beim Gebrauch Ihrer Komponente festzulegen.

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

note

Der mit default angegebene Wert sollte eine Zeichenfolge sein.

Analyse von Verstößen benutzerdefinierter Komponenten

Wenn Sie viele benutzerdefinierte Komponenten konfiguriert haben, kann es schwierig sein zu erkennen, welche Verstöße in der Antwort von benutzerdefinierten Komponenten-Zuordnungen im Vergleich zu standardmäßigen HTML-Elementen stammen. Das Hinzufügen von "properties": ["customName"] zu Ihrer Anforderungsstelle führt dazu, dass Axe DevTools Linter eine customName-Eigenschaft bei jedem Fehler einfügt, der von einer benutzerdefinierten zugeordneten Komponente stammt.

Aufbauend auf dem obigen custom-image-Beispiel, indem "properties": ["customName"] zur Anforderung hinzugefügt wird:

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

Die Antwort enthält nun eine customName-Eigenschaft für den Fehler, der zeigt, welche benutzerdefinierte Komponente den Verstoß ausgelöst hat:

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

Fehler von Komponenten, die nicht Teil einer benutzerdefinierten Zuordnung sind, haben keine customName-Eigenschaft.

Siehe auch

Is this page helpful?

Help us improve this page

Still need help?