Regole personalizzate

Il comando axe ruleset genera file JSON di regole che controllano quali regole di accessibilità axe esegue e come si comportano. Ci sono due flussi di lavoro:

• Configurazioni standard delle linee guida: Genera una configurazione pre-costruita filtrata in base a uno specifico standard di accessibilità (WCAG 2.2, Sezione 508, ecc.).
• Regole personalizzate: Modifica o estendi le regole esistenti di axe-core (o definisci nuove regole) descrivendo le tue modifiche in un file di input changes.json. Il nome di file richiesto changes.json è come axe ruleset individua le tue modifiche.

Entrambi i flussi di lavoro producono un file JSON in output. Per applicarlo durante la scansione, passalo al flag --custom del comando di scansione:

# 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

Configurazioni Standard delle Linee Guida

Questi flag generano un file JSON preconfigurato per uno specifico standard di accessibilità. L'argomento opzionale [filename] imposta il nome del file di output; se omesso, il file viene chiamato <standard>.json (ad esempio, wcag22.json). I file vengono scritti nella directory corrente a meno che non specifichi una destinazione con -d, --destination.

Eseguendo axe ruleset senza nessuno di questi flag vengono generati file di configurazione individuali per tutti gli standard supportati contemporaneamente.

--all [filename]

Genera un file JSON unico contenente tutte le regole e verifiche axe-core, con ogni regola impostata su enabled: false. Usalo come punto di partenza quando vuoi una configurazione opt-in. Ogni regola è disattivata di default e abiliti solo le regole che scegli modificando il file.

Opzioni di Configurazione Standard

-d, --destination <path>

Directory di output per il file JSON generato. Predefinita sulla directory corrente.

-f, --format [format]

Formato di output: json (predefinito) o js.

-l, --log

Stampa un elenco di tutte le regole incluse nel file generato nella console.

-a, --axe-source <path>

Percorso verso un file sorgente axe-core personalizzato. Usalo se devi generare configurazioni per una versione specifica o modificata di axe-core.

Regole Personalizzate

Un insieme di regole personalizzato ti permette di modificare il comportamento delle regole axe-core esistenti o di definire nuove regole completamente. Le modifiche sono descritte in un file changes.json, che usa lo stesso formato dell'oggetto passato a axe.configure().

Alcune delle cose che puoi fare con le regole personalizzate includono:

• Cambiare il livello di impatto dei risultati di un controllo (ad esempio, degradando serious a minor)
• Disabilitare regole che non si applicano al tuo contesto
• Creare nuove regole per applicare la politica di accessibilità della tua organizzazione
• Limitare quali tecniche sono accettate per un dato requisito (ad esempio, non consentendo title come nome accessibile per le immagini)
• Modificare le soglie di contrasto nella regola color-contrast
• Aggiornare quali ruoli e proprietà ARIA sono supportati

Generare un Insieme di Regole Personalizzato

Per generare un insieme di regole personalizzato, crea un file changes.json che descrive le tue modifiche, quindi esegui axe ruleset --custom <directory>, dove <directory> è la cartella contenente il tuo changes.json. Se ometti --custom, viene utilizzata la directory corrente.

Il file changes.json può specificare modifiche alle esistenti regole e verifiche di axe-core, oltre a nuove regole o verifiche.

Nota che l'impatto è una proprietà dei controlli, non delle regole. Sebbene l'output generato axe-ruleset.json mostri un campo impact su ogni regola, si tratta di un valore risolto calcolato dai controlli sottostanti della regola; non è qualcosa che si imposta su una regola in changes.json. Posizionare impact direttamente su una regola nel file di input provocherà un errore.

Per cambiare la severità percepita dei risultati di una regola, modifica l'impatto sul controllo sottostante. Ad esempio, per cambiare il controllo valid-lang da serious a minor:

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

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

Salva questo come changes.json in una directory ed esegui:

axe ruleset --custom ./my-changes/

Utilizzo delle directory di Regole e Controlli

Per personalizzazioni più complesse, puoi organizzare nuove regole e controlli in directory separate rules/ e checks/ accanto a changes.json. Ogni regola o controllo è un proprio file JSON. Questo non cambia l'output generato, ma rende più facile gestire molteplici regole e controlli personalizzati.

Ad esempio, per creare una nuova regola chiamata h1-no-duplicate che controlla più di un <h1> su una pagina:

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

Poiché la regola e il controllo sono definiti in file separati, changes.json è un oggetto vuoto:

{}

Il file della regola h1-no-duplicate.json definisce quali controlli eseguire:

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

Il file del controllo page-no-duplicate-h1.json definisce il controllo e i suoi messaggi di risultato:

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

I campi evaluate e after fanno riferimento agli ID delle funzioni JavaScript che implementano la logica del controllo. Per i controlli che modificano un controllo axe-core esistente, utilizza l'ID di una funzione di valutazione o after di axe-core esistente. Per controlli completamente nuovi, è necessario anche registrare le funzioni JavaScript corrispondenti con axe-core. Vedi la documentazione API di axe-core per i dettagli.

Dopo aver eseguito axe ruleset --custom, il JSON generato combina le definizioni di regola e controllo in un unico file (parte rilevante mostrata):

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

Opzioni per i set di regole personalizzati

-c, --custom [path]

Percorso alla directory contenente il tuo file changes.json (e opzionalmente le sottodirectory rules/ e checks/). Di default è la directory corrente.

-t, --tags <list>

Elenco separato da virgole di tag di axe-core utilizzato per filtrare quali regole dal set di regole standard di axe-core sono incluse nell'output.

-x, --disable-other-rules

Disabilita tutte le regole di axe-core che non sono esplicitamente incluse nella proprietà rules di changes.json o nella directory rules/. Abilitato di default, quindi il set di regole generato sostituisce il set di regole completo di axe-core anziché estenderlo; solo le regole personalizzate vengono eseguite. Passa --no-disable-other-rules per includere tutte le regole standard di axe-core insieme a quelle personalizzate.

--only-changes

Valido solo con --custom. Genera solo le modifiche e le aggiunte descritte in changes.json, senza le definizioni complete di regole e controlli di axe-core. Produce un file più piccolo adatto per essere utilizzato come un overlay sopra un set di regole esistente.

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

Vedi Opzioni di configurazione standard. Queste opzioni si applicano anche ai set di regole personalizzati.

Caricamento di un set di regole

Ci sono tre modi per applicare un set di regole generato durante la scansione. Vengono controllati in questo ordine:

1. Variabile d'ambiente: Imposta AXE_RULESET_PATH sul percorso del file del set di regole. Questo ha la precedenza su tutti gli altri metodi e si applica a tutte le esecuzioni in quell'ambiente.

2. Flag --custom: Passa esplicitamente il file del set di regole utilizzando il flag --custom su axe <url>, axe spec o axe bulk-spec.

3. File locale: Posiziona un file chiamato axe-ruleset.json nella directory in cui viene eseguito axe. Verrà utilizzato automaticamente se nessuno dei precedenti è impostato.

Se nessuno di questi è specificato, o se Axe DevTools non può caricare il file specificato, viene utilizzato il set di regole predefinito wcag2.1.

Supporto

Creare set di regole personalizzati richiede una comprensione significativa di axe-core. Per i dettagli, vedi la documentazione API di axe-core. Se desideri supporto nella creazione e manutenzione del tuo set di regole personalizzato, contatta il tuo rappresentante Deque.