Configurando o axe DevTools Linter

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

Um guia de referência para configurar o axe DevTools Linter

Not for use with personal data

Este artigo fornece uma referência para as opções de configuração do Axe DevTools Linter.

Visão Geral

O endpoint da API REST usa JSON para configuração, e a extensão Axe Accessibility Linter para VS Code, o plugin JetBrains, e o conector Axe DevTools Linter usam YAML para configuração. Exemplos de configurações do Axe DevTools Linter em JSON e YAML são mostrados neste guia.

Exemplos de Configuração

O exemplo YAML a seguir demonstra uma configuração simples que usa a opção rules para uso com a extensão Axe Accessibility Linter para VS Code, o plugin JetBrains ou o conector Axe DevTools Linter:

rules:
  html-has-lang: false

O exemplo a seguir demonstra a mesma configuração como um objeto de solicitação completo com a opção rules para o serviço REST do Axe DevTools Linter com seu objeto incorporado config destacado:

{
  "source": "<html></html>",
  "filename": "file.html",
  "config": {    "rules": {      "html-has-lang": false    },    "exclude": [],
    "tags": []
  }
}

Em ambos os casos, essas configurações fazem com que o Axe DevTools Linter ignore erros de acessibilidade quando o elemento html está faltando um atributo lang . (Veja a regra html-has-lang para mais informações.)

note

Para todos os exemplos de JSON neste artigo, o objeto config está incluído para fornecer um local de referência para a configuração.

As seções a seguir descrevem cada opção de configuração e dão exemplos de seu uso.

Múltiplos Arquivos de Configuração

A extensão Axe Accessibility Linter para VS Code, o plugin JetBrains e o conector Axe DevTools Linter (quando usados com a opção --config sem parâmetro) procurarão o diretório atual e diretórios pai por axe-linter.yml arquivos de configuração na árvore de diretórios do projeto e usarão o primeiro que encontrarem. Uma prática útil é colocar um arquivo de configuração na raiz do seu projeto contendo sua configuração padrão e sobrescrevê-la (se necessário) com arquivos de configuração em diferentes subdiretórios. Você também pode colocar um arquivo de configuração em seu diretório pessoal que será usado por padrão se não houver arquivos de configuração em seu projeto.

Os passos utilizados para localizar axe-linter.yml arquivos de configuração são:

Use o arquivo de configuração no diretório atual (o diretório contendo o arquivo que está sendo editado com VS Code, uma IDE JetBrains, ou o diretório atual do prompt de comando com o conector Axe DevTools Linter).
Se nenhuma configuração for encontrada no passo 1, procure em diretórios pai até encontrar um arquivo de configuração axe-linter.yml , parando na sua pasta pessoal se o projeto estiver na árvore do seu diretório pessoal ou no diretório raiz se estiver fora da sua pasta pessoal.
Use um arquivo de configuração axe-linter.yml localizado no seu diretório pessoal (mesmo que seu projeto esteja localizado em um diretório fora da sua pasta pessoal ou em outra unidade no Windows). Por exemplo, estes são os arquivos típicos usados:
- /home/nome_de_usuário/axe-linter.yml (Linux)
- /Users/nome_de_usuário/axe-linter.yml (macOS)
- C:\Users\nome_de_usuário\axe-linter.yml (Windows)

A busca para quando o primeiro arquivo axe-linter.yml for encontrado.

Resumo da Configuração do Axe DevTools Linter

Produto	Tipo de Configuração	Descrição
Extensão Axe Accessibility Linter para VS Code ou o plugin JetBrains	Um ou mais arquivos YAML chamados `axe-linter.yml`	Veja Múltiplas Configurações.
Conector Axe Linter	Um ou mais arquivos YAML chamados `axe-linter.yml`	Siga os passos em Múltiplas Configurações quando usado com a `--config` opção sem parâmetro.
Conector Axe Linter	Um arquivo YAML chamado nome do arquivo	Quando usado com `--config` nome do arquivo.
API REST Axe Linter	Objeto de configuração JSON	Veja O Objeto de Configuração.

Opções de Configuração

`element`

A opção element permite que você altere o elemento emitido com base no valor de atributo especificado de seu componente. Por exemplo, você poderia ter um componente personalizado que emite um elemento img em certos casos e um elemento button em outros casos, permitindo casos de uso mais complexos.

A configuração de exemplo abaixo especifica que o atributo as no componente my-button pode alterar o elemento emitido do padrão de button:

YAML:

global-components:
  my-button:
    element: button
    attributes:
      - as: <element>

JSON:

{
  "config": {
    "global-components": {
      "my-button": {
        "element": "button",
        "attributes": [
          {
            "as": "<element>"
          }
        ]
      }
    }
  }
}

O uso de exemplo abaixo emite um elemento img em vez do padrão de elemento button porque o atributo as especifica o elemento de saída:

<my-button as="img"></my-button>

O elemento de saída img será então analisado e encontrado sem um atributo alt .

`exclude`

A opção exclude impede que arquivos correspondentes sejam analisados. Você pode usar curingas e globs. Seu uso é principalmente para a extensão VS Code ou plugin JetBrains e é ignorado pelo endpoint REST.

exclude: *.tmp

`global-components`

A opção de configuração global-components direciona a ferramenta Axe DevTools Linter sobre como mapear seus próprios componentes personalizados ou componentes de bibliotecas de terceiros para elementos HTML nativos, permitindo que você analise seus componentes como se fossem elementos HTML nativos. Por exemplo, a configuração a seguir tratará todos os componentes personalizados DqButton como se fossem elementos HTML nativos button . Isso mapeia automaticamente cada atributo em DqButton para button, exigindo assim um nome acessível para todos os componentes DqButton .

YAML:

global-components:
  DqButton: button

JSON:

{
  "config": {
    "global-components" {
      "DqButton": "button"
    }
  }
}

Alternativamente, para componentes que não mapeiam todos os atributos para componentes HTML nativos, você pode listar os atributos necessários para conformidade com acessibilidade usando a opção attributes . Você pode listar os atributos que o componente suporta, bem como renomear atributos. Existem três valores especiais:

O valor aria-* informa ao Axe DevTools Linter que todos os atributos que começam com aria- são mapeados para o elemento HTML nativo como estão. Note que o valor termina com um asterisco.
O valor <text> informa ao Axe DevTools Linter que uma propriedade é usada para definir o conteúdo (o valor entre as tags de abertura e fechamento) do elemento HTML nativo.
O valor <element> informa ao Axe DevTools Linter que o elemento emitido pode assumir o valor deste atributo, o que permite mudar o elemento emitido dependendo do valor do atributo especificado.

O exemplo YAML a seguir mostra todos os valores que podem ser usados com global-components:

global-components:
  DqButton:
    element: button
    # Ignore all attributes on <DqButton> except the following:
    attributes:
      - role # Map the role attribute from <DqButton /> to <button />
      - aria-* # Map all attributes starting with aria-
      - action: type # <DqButton action="submit" /> maps to <button type="submit" />
      - label: <text> #  <DqButton label="ABC" /> emits <button>ABC</button>
      - as: <element> # <DqButton as="img" /> emits <img> instead of <button>. (You don't have to use *as* for the attribute name.)

Uma versão equivalente em JSON (dentro do objeto config ) é a seguinte:

{
  "config": {
    "global-components": {
      "DqButton": {
        "element": "button",
        "attributes": [
          "role",
          "aria-*",
          {
            "action": "type"
          },
          {
            "label": "<text>"
          },
          {
            "as": "<element>"
          }
        ]
      }
    }
  }
}

Somente atributos relevantes para a acessibilidade precisam estar na lista attributes . Os nomes dos elementos diferenciam maiúsculas de minúsculas. O camel case, como mostrado acima, é comumente usado com arquivos .jsx, mas o kebab case (usado em Vue, Angular e em elementos HTML personalizados) também pode ser utilizado.

Para tutoriais que mostram como usar o mapeamento de componentes personalizados, veja Linting Custom Components.

`global-libraries`

O Axe DevTools Linter possui suporte integrado para várias bibliotecas e frameworks de componentes populares.

As seguintes bibliotecas são atualmente suportadas:

react-native
@mui/material
@deque/cauldron-react

Para habilitar o linting de componentes da biblioteca, adicione o nome do pacote NPM da biblioteca ao array global-libraries em arquivos de configuração YAML:

global-libraries:
  - '@mui/material'
  - '@deque/cauldron-react'
  - react-native

note

Você precisa colocar entre aspas @mui/material e @deque/cauldron-react no YAML, porque @ é interpretado como um caractere reservado.

Ou a configuração equivalente em JSON é mostrada abaixo:

{
  "config": {
    "global-libraries": [
      "@mui/material"
    ]
  }
}

Qualquer componente com o mesmo nome que um componente da biblioteca global será tratado como aquele componente da biblioteca, permitindo reexportar e redefinir componentes sem perder seu mapeamento.

Para mais informações, veja Preconfigured Component Libraries.

`overrides`

Você pode alterar como o Axe DevTools Linter é configurado por arquivo usando a opção de configuração overrides . Múltiplas sobreposições no mesmo arquivo são resolvidas em ordem. Ou seja, a última sobreposição listada tem a maior precedência.

Atualmente, apenas a sobreposição linter é suportada e é usada para mudar o linter utilizado nos arquivos correspondentes.

overrides:
  - files: # An array or single string of filename(s) or glob pattern(s) that match this override setting
      - vue/**/*.html
    linter: vue # Specify that all files that match the pattern should be linted as Vue
  - files: php/**/*.html
    linter: null # Disable Axe Linter for these files

`rules`

Você pode permitir ou desativar regras individualmente com a opção rules na sua configuração. Cada regra pode ser configurada para true (ativada, relatada como um erro — padrão), false (desativada) ou warn (ativada, relatada como um aviso):

rules:
  some-rule: false   # turn off rule
  other-rule: true   # turn on rule (default)
  color-contrast: warn  # report violations as warnings instead of errors

Ou no objeto config na sua solicitação JSON REST:

{
  "config": {
    "rules": {
      "some-rule": false,
      "other-rule": true,
      "color-contrast": "warn"
    }
  }
}

Para informações sobre como usar rules com a API REST, veja A propriedade rules. Se você quiser usar rules com o conector do Axe DevTools Linter, veja Arquivo de Configuração. Para ver as regras que o Axe DevTools Linter segue, consulte Regras de Acessibilidade. Veja tags abaixo para mais informações sobre o uso da opção tags para excluir coleções de regras do processamento.

Para suprimir regras para linhas específicas em um arquivo fonte sem modificar este arquivo de configuração, consulte Suprimindo Regras de Linting com Diretivas Inline.

`tags`

Você pode proibir regras como um grupo com base no padrão WCAG ao qual estão associadas usando a tags opção:

tags: # Disallow all rules other than WCAG 2.1 A, WCAG 2.1 AA, and best practices.
  - wcag21a
  - wcag21aa
  - best-practices

Veja Também

Para uma referência às APIs REST fornecidas pelo Axe DevTools Linter, consulte Referência da API REST do Axe DevTools Linter.
Para tutoriais sobre a criação de mapeamentos de componentes personalizados, consulte Linting de Componentes Personalizados.
Para baixar a extensão para VS Code, veja Axe Accessibility Linter.
Para mais informações sobre o plugin JetBrains, consulte Usando o Plugin com JetBrains IDEs.