Benutzerdefinierte Regelwerke

Der axe ruleset-Befehl generiert JSON-Regelwerkdateien, die steuern, welche Barrierefreiheitsregeln axe ausführt und wie sie sich verhalten. Es gibt zwei Arbeitsabläufe:

• Standardrichtlinien-Konfigurationen: Erstellen Sie eine vorgefertigte Konfiguration, die nach einem bestimmten Barrierefreiheitsstandard gefiltert ist (WCAG 2.2, Section 508 usw.).
• Benutzerdefinierte Regelwerke: Modifizieren oder erweitern Sie bestehende axe-core-Regeln (oder definieren Sie neue), indem Sie Ihre Änderungen in einer changes.json-Eingabedatei beschreiben. Der erforderliche Dateiname changes.json ist, wie axe ruleset Ihre Änderungen lokalisiert.

Beide Arbeitsabläufe erzeugen eine Ausgabe-JSON-Datei. Um sie beim Scannen anzuwenden, übergeben Sie sie an das --custom-Flag des Scan-Befehls:

# Standard config workflow
axe ruleset --wcag22                          # generates wcag22.json
axe <url> --custom wcag22.json

# Custom ruleset workflow
axe ruleset --custom ./my-changes/            # reads changes.json from the directory, generates axe-ruleset.json
axe <url> --custom axe-ruleset.json

Standardrichtlinien-Konfigurationen

Diese Flags erzeugen eine JSON-Datei, die für einen bestimmten Barrierefreiheitsstandard vorkonfiguriert ist. Das optionale [filename]-Argument legt den Ausgabedateinamen fest; wenn es weggelassen wird, wird die Datei <standard>.json genannt (zum Beispiel wcag22.json). Dateien werden im aktuellen Verzeichnis gespeichert, es sei denn, Sie geben ein Zielverzeichnis mit -d, --destination an.

Das Ausführen von axe ruleset ohne diese Flags generiert einzelne Konfigurationsdateien für alle unterstützten Standards gleichzeitig.

--all [filename]

Es wird eine einzige JSON-Datei erzeugt, die alle axe-core-Regeln und -Prüfungen enthält, wobei jede Regel auf enabled: false gesetzt ist. Verwenden Sie diese als Ausgangspunkt, wenn Sie eine Opt-in-Konfiguration wünschen. Jede Regel ist standardmäßig deaktiviert, und Sie aktivieren nur die Regeln, die Sie durch Modifizieren der Datei auswählen.

Standardkonfigurationsoptionen

-d, --destination <path>

Ausgabeverzeichnis für die generierte JSON-Datei. Standardmäßig das aktuelle Verzeichnis.

-f, --format [format]

Ausgabeformat: json (Standard) oder js.

-l, --log

Drucken Sie eine Liste aller in der generierten Datei enthaltenen Regeln in die Konsole.

-a, --axe-source <path>

Pfad zu einer benutzerdefinierten axe-core-Quelldatei. Verwenden Sie dies, wenn Sie Konfigurationen gegen eine bestimmte oder gepatchte Version von axe-core erstellen müssen.

Benutzerdefinierte Regelwerke

Ein benutzerdefiniertes Regelwerk ermöglicht es Ihnen, das Verhalten bestehender axe-core-Regeln zu ändern oder ganz neue Regeln zu definieren. Änderungen werden in einer changes.json-Datei beschrieben, die dasselbe Format wie das Objekt verwendet, das an axe.configure() übergeben wird.

Einige der Dinge, die Sie mit benutzerdefinierten Regelwerken tun können, umfassen:

• Ändern Sie das Einflussniveau der Ergebnisse einer Prüfung (zum Beispiel das Herabstufen von serious auf minor)
• Deaktivieren Sie Regeln, die in Ihrem Kontext nicht zutreffen
• Erstellen Sie neue Regeln, um die Barrierefreiheitsrichtlinien Ihrer Organisation durchzusetzen
• Beschränken Sie, welche Techniken für eine bestimmte Anforderung akzeptiert werden (zum Beispiel das Verbot von title als zugänglicher Name für Bilder)
• Modifizieren Sie die Kontrastschwellenwerte in der color-contrast-Regel
• Aktualisieren Sie, welche ARIA-Rollen und -Eigenschaften unterstützt werden

Generierung eines benutzerdefinierten Regelwerks

Um ein benutzerdefiniertes Regelwerk zu erstellen, erstellen Sie eine changes.json-Datei, die Ihre Änderungen beschreibt, und führen Sie dann axe ruleset --custom <directory> aus, wobei <directory> der Ordner ist, der Ihre changes.json enthält. Wenn Sie --custom weglassen, wird das aktuelle Verzeichnis verwendet.

Die changes.json-Datei kann Änderungen an bestehenden axe-core-Regeln und -Prüfungen sowie neue Regeln oder Prüfungen angeben.

Beachten Sie, dass Auswirkung ist eine Eigenschaft von Prüfungen, nicht von Regeln. Obwohl die generierte axe-ruleset.json-Ausgabe ein impact-Feld bei jeder Regel anzeigt, ist dies ein berechneter Wert, der aus den zugrunde liegenden Prüfungen der Regel abgeleitet wird; es ist nichts, was Sie in changes.json auf eine Regel anwenden. Das direkte Platzieren von impact auf einer Regel in Ihrer Eingabedatei führt zu einem Fehler.

Um die wahrgenommene Schwere der Befunde einer Regel zu ändern, modifizieren Sie die Auswirkung auf die zugrunde liegende Prüfung. Zum Beispiel, um die valid-lang-Prüfung von serious auf minor zu ändern:

{
    "checks": [{
        "id": "valid-lang",
        "metadata": {
            "impact": "minor"
        }
    }]
}

{
    "rules": [{
        "id": "valid-lang",
        "impact": "minor"
    }]
}

Speichern Sie dies als changes.json in einem Verzeichnis und führen Sie aus:

axe ruleset --custom ./my-changes/

Verwendung von Regel- und Prüfungsverzeichnissen

Für komplexere Anpassungen können Sie neue Regeln und Prüfungen in separate rules/- und checks/-Verzeichnisse neben changes.json organisieren. Jede Regel oder Prüfung ist eine eigene JSON-Datei. Dies ändert nichts an der generierten Ausgabe, erleichtert jedoch die Verwaltung mehrerer benutzerdefinierter Regeln und Prüfungen.

Zum Beispiel, um eine neue Regel namens h1-no-duplicate zu erstellen, die überprüft, ob mehr als eine <h1> auf einer Seite vorhanden sind:

directory
 ├ changes.json
 ├ rules
 │  └ h1-no-duplicate.json
 └ checks
    └ page-no-duplicate-h1.json

Da die Regel und die Prüfung in separaten Dateien definiert sind, ist changes.json ein leeres Objekt:

{}

Die h1-no-duplicate.json-Regeldatei definiert, welche Prüfungen ausgeführt werden sollen:

{
    "id": "h1-no-duplicate",
    "selector": "h1:not([role]), [role=heading][aria-level=1]",
    "tags": ["cat.semantics", "best-practice"],
    "metadata": {
        "description": "Ensures the document has at most one h1 element",
        "help": "Document must not have more than one h1 element"
    },
    "all": [],
    "any": ["page-no-duplicate-h1"],
    "none": []
}

Die page-no-duplicate-h1.json-Prüfungsdatei definiert die Prüfung und ihre Ergebnismeldungen:

{
    "id": "page-no-duplicate-h1",
    "evaluate": "page-no-duplicate-evaluate",
    "after": "page-no-duplicate-after",
    "options": {
        "selector": "h1:not([role]), [role=heading][aria-level=1]"
    },
    "metadata": {
        "impact": "moderate",
        "messages": {
            "pass": "Document does not have more than one h1 element",
            "fail": "Document has more than one h1 element"
        }
    }
}

Die Felder evaluate und after verweisen auf JavaScript-Funktions-IDs, die die Logik der Prüfung implementieren. Für Prüfungen, die eine bestehenden axe-core-Prüfung ändern, verwenden Sie die ID einer vorhandenen axe-core-Bewerten- oder Nachher-Funktion. Für völlig neue Prüfungen müssen Sie die entsprechenden JavaScript-Funktionen auch bei axe-core registrieren. Weitere Informationen finden Sie in der axe-core API-Dokumentation.

Nach dem Ausführen von axe ruleset --custom kombiniert das generierte JSON die Regel- und Prüfungsdefinitionen in einer einzigen Datei (relevanter Abschnitt gezeigt):

{
    "rules": [{
        "id": "h1-no-duplicate",
        "selector": "h1:not([role]), [role=heading][aria-level=1]",
        "tags": ["cat.semantics", "best-practice"],
        "metadata": {
            "description": "Ensures the document has at most one h1 element",
            "help": "Document must not have more than one h1 element"
        },
        "all": [],
        "any": ["page-no-duplicate-h1"],
        "none": [],
        "enabled": true
    }],
    "checks": [{
        "id": "page-no-duplicate-h1",
        "evaluate": "page-no-duplicate-evaluate",
        "after": "page-no-duplicate-after",
        "options": {
            "selector": "h1:not([role]), [role=heading][aria-level=1]"
        },
        "metadata": {
            "impact": "moderate",
            "messages": {
                "pass": "Document does not have more than one h1 element",
                "fail": "Document has more than one h1 element"
            }
        },
        "enabled": true
    }]
}

Benutzerdefinierte Ruleset-Optionen

-c, --custom [path]

Pfad zu dem Verzeichnis, das Ihre changes.json-Datei (und optional rules/- und checks/-Unterverzeichnisse) enthält. Standardmäßig das aktuelle Verzeichnis.

-t, --tags <list>

Durch Kommas getrennte Liste von axe-core-Tags, die verwendet wird, um zu filtern, welche Regeln aus dem Standard-axe-core-Regelsatz in die Ausgabe aufgenommen werden.

-x, --disable-other-rules

Deaktiviert alle axe-core-Regeln, die nicht explizit im rules-Eigenschaft von changes.json oder im rules/-Verzeichnis enthalten sind. Standardmäßig aktiviert, sodass das generierte Ruleset den vollständigen axe-core-Regelsatz ersetzt und nicht erweitert; nur Ihre benutzerdefinierten Regeln werden ausgeführt. Verwenden Sie --no-disable-other-rules, um alle Standard-axe-core-Regeln neben Ihren benutzerdefinierten Regeln einzuschließen.

--only-changes

Nur gültig mit --custom. Erzeugt nur die in changes.json beschriebenen Änderungen und Ergänzungen, ohne die vollständigen axe-core Regel- und Prüfungsdefinitionen. Produziert eine kleinere Datei, die als Overlay auf einem bestehenden Regelwerk geeignet ist.

-d, --destination <path>, -f, --format, -l, --log, -a, --axe-source <path>

Siehe Standardkonfigurationsoptionen. Diese Optionen gelten auch für benutzerdefinierte Regelwerke.

Ein Regelwerk laden

Es gibt drei Möglichkeiten, ein generiertes Regelwerk beim Scannen anzuwenden. Sie werden in folgender Reihenfolge überprüft:

1. Umgebungsvariable: Setzen Sie AXE_RULESET_PATH auf den Pfad der Regelwerksdatei. Dies hat Vorrang vor allen anderen Methoden und gilt für alle Läufe in dieser Umgebung.

2. --custom-Flag: Übergeben Sie die Regelwerksdatei ausdrücklich mit dem --custom-Flag auf axe <url>, axe spec oder axe bulk-spec.

3. Lokale Datei: Legen Sie eine Datei namens axe-ruleset.json in das Verzeichnis, in dem axe ausgeführt wird. Sie wird automatisch verwendet, wenn keine der obigen Einstellungen gesetzt sind.

Wenn keine dieser Einstellungen angegeben sind oder Axe DevTools die angegebene Datei nicht laden kann, wird das wcag2.1-Standardregelwerk verwendet.

Support

Die Erstellung benutzerdefinierter Regelwerke erfordert ein signifikantes Verständnis von axe-core. Für Details siehe die axe-core API-Dokumentation. Wenn Sie Unterstützung bei der Erstellung und Pflege Ihres benutzerdefinierten Regelwerks wünschen, wenden Sie sich an Ihren Deque-Ansprechpartner.