Aangepaste Regelsets

Het commando axe ruleset genereert JSON-regelsetbestanden die bepalen welke toegankelijkheidsregels axe uitvoert en hoe ze zich gedragen. Er zijn twee werkstromen:

• Standaard richtlijnconfiguraties: Genereer een vooraf gebouwde configuratie gefilterd op een specifieke toegankelijkheidsstandaard (WCAG 2.2, Section 508, enzovoort).
• Aangepaste regelsets: Wijzig of breid bestaande axe-core regels uit (of definieer nieuwe) door uw wijzigingen te beschrijven in een changes.json invoerbestand. De vereiste bestandsnaam changes.json bepaalt hoe axe ruleset uw wijzigingen lokaliseert.

Beide werkstromen produceren een uitvoer-JSON-bestand. Om het toe te passen tijdens het scannen, geeft u het door aan de --custom vlag van het scancommando:

# 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

Standaard Richtlijnconfiguraties

Deze vlaggen genereren een JSON-bestand dat vooraf is geconfigureerd voor een specifieke toegankelijkheidsstandaard. Het optionele [filename] argument stelt de uitvoerbestandsnaam in; als deze wordt weggelaten, wordt het bestand <standard>.json genoemd (bijvoorbeeld, wcag22.json). Bestanden worden naar de huidige directory geschreven tenzij u een bestemming specificeert met -d, --destination.

Het uitvoeren van axe ruleset zonder een van deze vlaggen genereert individuele configuratiebestanden voor alle ondersteunde standaarden tegelijk.

--all [filename]

Genereert een enkel JSON-bestand dat alle axe-core regels en controles bevat, waarbij elke regel is ingesteld op enabled: false. Gebruik dit als beginpunt wanneer u een opt-in configuratie wilt. Elke regel is standaard uitgeschakeld en u schakelt alleen de regels in die u kiest door het bestand aan te passen.

Opties voor Standaardconfiguratie

-d, --destination <path>

Uitvoerlocatie voor het gegenereerde JSON-bestand. De standaardwaarde is de huidige directory.

-f, --format [format]

Uitvoerformaat: json (standaard) of js.

-l, --log

Druk een lijst af van alle regels die in het gegenereerde bestand zijn opgenomen naar de console.

-a, --axe-source <path>

Pad naar een aangepaste axe-core bronbestand. Gebruik dit als u configuraties tegen een specifieke of aangepaste versie van axe-core moet genereren.

Aangepaste Regelsets

Een aangepaste regelset stelt u in staat om te wijzigen hoe bestaande axe-core regels zich gedragen of volledig nieuwe regels te definiëren. Wijzigingen worden beschreven in een changes.json bestand, dat hetzelfde formaat gebruikt als het object dat wordt doorgegeven aan axe.configure().

Enkele van de dingen die u met aangepaste regelsets kunt doen, zijn onder andere:

• De impactniveau van de resultaten van een controle wijzigen (bijvoorbeeld het degraderen van serious naar minor)
• Regels uitschakelen die niet van toepassing zijn op uw context
• Nieuwe regels maken om het toegankelijkheidsbeleid van uw organisatie af te dwingen
• Beperken welke technieken worden geaccepteerd voor een bepaalde eis (bijvoorbeeld title als een toegankelijke naam voor afbeeldingen verbieden)
• Contrastdrempels wijzigen in de color-contrast regel
• Bijwerken welke ARIA-rollen en -eigenschappen worden ondersteund

Een Aangepaste Regelset Genereren

Om een aangepaste regelset te genereren, maakt u een changes.json bestand dat uw wijzigingen beschrijft, en voert u axe ruleset --custom <directory> uit, waarbij <directory> de map is die uw changes.json bevat. Als u --custom weglaat, wordt de huidige directory gebruikt.

Het changes.json bestand kan wijzigingen specificeren aan bestaande axe-core regels en controles, evenals nieuwe regels of controles.

Let op dat impact is een eigenschap van controles, niet van regels. Hoewel de gegenereerde axe-ruleset.json-uitvoer een impact-veld op elke regel toont, is dit een opgelost waarde berekend uit de onderliggende controles van de regel; het is niet iets dat je op een regel in changes.json instelt. Het direct plaatsen van impact op een regel in je invoerbestand zal een fout veroorzaken.

Om de waargenomen ernst van de bevindingen van een regel te veranderen, wijzig de impact op de onderliggende controle. Bijvoorbeeld, om de valid-lang-controle te veranderen van serious naar minor:

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

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

Sla dit op als changes.json in een map en voer uit:

axe ruleset --custom ./my-changes/

Gebruik van Regels en Controles Mappen

Voor complexere aanpassingen kun je nieuwe regels en controles organiseren in afzonderlijke rules/ en checks/ directories naast changes.json. Elke regel of controle is een eigen JSON-bestand. Dit verandert de gegenereerde output niet, maar maakt het eenvoudiger om meerdere aangepaste regels en controles te beheren.

Bijvoorbeeld, om een nieuwe regel genaamd h1-no-duplicate te maken die controleert op meer dan één <h1> op een pagina:

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

Omdat de regel en controle in afzonderlijke bestanden worden gedefinieerd, is changes.json een leeg object:

{}

Het h1-no-duplicate.json-regelbestand definieert welke controles moeten worden uitgevoerd:

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

Het page-no-duplicate-h1.json-controlebestand definieert de controle en zijn resultaatberichten:

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

De evaluate en after velden verwijzen naar JavaScript-functie-ID's die de controlelogica implementeren. Voor controles die een bestaande axe-core controle wijzigen, gebruik je de ID van een bestaande axe-core evaluate of after functie. Voor volledig nieuwe controles moet je de bijbehorende JavaScript-functies ook registreren bij axe-core. Zie de axe-core API-documentatie voor details.

Na het uitvoeren van axe ruleset --custom, combineert het gegenereerde JSON-bestand de regel- en controledefinities in een enkel bestand (relevant gedeelte getoond):

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

Opties voor Aangepaste Regels

-c, --custom [path]

Pad naar de directory die je changes.json-bestand bevat (en optionele rules/ en checks/ submappen). Standaard is de huidige directory.

-t, --tags <list>

Kommagescheiden lijst van axe-core tags die worden gebruikt om te filteren welke regels uit de standaard axe-core regels worden opgenomen in de output.

-x, --disable-other-rules

Schakelt alle axe-core regels uit die niet expliciet zijn opgenomen in de rules eigenschap van changes.json of de rules/-map. Standaard ingeschakeld, zodat het gegenereerde regels de volledige axe-core regels vervangen in plaats van deze uit te breiden; alleen je aangepaste regels worden uitgevoerd. Gebruik --no-disable-other-rules om alle standaard axe-core regels naast je aangepaste toe te voegen.

--only-changes

Alleen geldig met --custom. Genereer alleen de beschreven wijzigingen en toevoegingen in changes.json, zonder de volledige axe-core regel- en controledefinities. Produceert een kleiner bestand geschikt voor gebruik als overlay bovenop een bestaand regels.

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

Zie Standaard Configuratieopties. Deze opties gelden ook voor aangepaste regels.

Een Regeldataset Laden

Er zijn drie manieren om een gegenereerde regels toe te passen bij een scan. Ze worden in deze volgorde gecontroleerd:

1. Omgevingsvariabele: Stel AXE_RULESET_PATH in op het pad van het regelsbestand. Dit heeft voorrang boven alle andere methoden en geldt voor alle runs in die omgeving.

2. --custom-vlag: Geef het regelsbestand expliciet door met de --custom-vlag op axe <url>, axe spec, of axe bulk-spec.

3. Lokaal bestand: Plaats een bestand genaamd axe-ruleset.json in de directory waar axe uitvoert. Het wordt automatisch gebruikt als geen van de bovenstaande is ingesteld.

Als geen van deze zijn gespecificeerd, of als Axe DevTools het gespecificeerde bestand niet kan laden, wordt de wcag2.1 standaardregels gebruikt.

Ondersteuning

Het maken van aangepaste regels vereist een aanzienlijke kennis van axe-core. Voor details, zie de axe-core API-documentatie. Als je ondersteuning wilt bij het maken en onderhouden van je aangepaste regels, neem dan contact op met je Deque-vertegenwoordiger.