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 o 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 utiliza a opção rules para uso com a extensão Axe Accessibility Linter para VS Code, o plugin JetBrains ou o Axe DevTools Linter Connector:

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 embutido 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 estiver sem um atributo lang. (Consulte a regra html-has-lang para mais informações.)

note

Para todos os exemplos em JSON neste artigo, o objeto config é 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.

Ordem de Busca do Arquivo de Configuração

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

important

Os arquivos de configuração encontrados por essa busca não são mesclados. Apenas o primeiro encontrado é utilizado. Para combinar configurações de mais de um arquivo, faça com que o arquivo de configuração herde dos outros com a opção extends.

Os passos para localizar o arquivo de configuração axe-linter.yml a ser usado 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 na etapa 1, procure em diretórios superiores até que um arquivo de configuração axe-linter.yml seja encontrado, parando na sua pasta pessoal se o projeto estiver na árvore de diretórios 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 o 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 é 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 arquivo YAML chamado `axe-linter.yml`	Veja Ordem de Busca do Arquivo de Configuração.
Conector Axe Linter	Um arquivo YAML chamado `axe-linter.yml`	Segue os passos em Ordem de Busca do Arquivo de Configuração quando usado com a opção `--config` 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 do atributo especificado do seu componente. Por exemplo, você pode fazer com que um componente personalizado emita 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 mudar 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 elemento padrão 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 verificado e encontrado com a falta de um atributo alt.

`exclude`

A opção exclude impede que arquivos correspondentes sejam verificados. 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

`enterpriseId`

O campo opcional enterpriseId aceita uma string que é anexada aos eventos de análise de uso para atribuição empresarial. A maioria dos usuários não precisará definir este valor; ele pode ser solicitado por seu representante de conta Deque. Este campo é ignorado para implantações locais.

enterpriseId: 'acme-corp'

`extends`

A opção extends permite que um arquivo axe-linter.yml herde suas configurações de um ou mais arquivos de configuração pai, para que uma base compartilhada possa estar em um único lugar, em vez de ser copiada em todos os projetos. Ela aceita um único caminho de arquivo ou uma matriz de caminhos de arquivo, e está disponível na versão 4.13.0 e posteriores da extensão Axe Accessibility Linter para VS Code, o plug-in JetBrains e o Axe DevTools Linter Connector.

extends: ./axe-linter.base.yml
rules:
  color-contrast: warn

Para herdar de mais de um arquivo, use uma matriz:

extends:
  - ./axe-linter.base.yml
  - ../shared/team-rules.yml

Os caminhos são resolvidos em relação ao arquivo que contém a opção extends, não ao diretório de onde você iniciou o linter. Caminhos absolutos também são aceitos. Arquivos pai não precisam ser nomeados axe-linter.yml, e um arquivo pai pode usar extends para herdar de outro arquivo.

note

Nomes de pacotes simples (como @my-org/axe-linter-config) e URLs remotos (como https://example.com/axe-linter.yml) não são suportados. Somente caminhos de arquivo relativos e absolutos podem ser usados.

Como As Configurações Herdadas São Combinadas

Os arquivos pai são lidos da esquerda para a direita, e sua própria configuração é aplicada por último, portanto, ela resolve qualquer conflito. Cada opção é combinada da seguinte forma:

Opção	Como é combinada
`rules`	Mesclada por ID de regra, e seu valor prevalece. Como cada regra é ativada e relatada como erro por padrão (veja `rules`), um arquivo pai usa essa opção para desativar regras ou relatá-las como avisos, e sua própria configuração pode mudar qualquer uma dessas decisões, incluindo definir uma regra de volta para `true` para restaurar o relatório de erro padrão.
`tags`	Combinada com os valores do pai, com duplicatas removidas.
`exclude`	Combinada com os valores do pai, com duplicatas removidas.
`global-libraries`	Combinada com os valores do pai, com duplicatas removidas.
`global-components`	Mesclada por nome de componente. Uma entrada na sua configuração substitui totalmente uma entrada pai com o mesmo nome, em vez de ser mesclada a ela, então repetir um nome de componente significa repetir todas as configurações desse componente.
`overrides`	Combinada, com as entradas do pai primeiro, seguidas pelas suas.
Qualquer outra opção, como `enterpriseId`	Seu valor prevalece, e o pai fornece o valor para qualquer opção que você deixar de fora.

important

Se um arquivo pai definir enterpriseId e sua própria configuração não, o uso do seu projeto é contado sob o ID empresarial do pai. Defina enterpriseId na sua própria configuração se precisar de um valor diferente.

Limites e Tratamento de Erros

Um arquivo de configuração não pode se estender a si mesmo, seja diretamente ou através de uma cadeia de arquivos pais. As cadeias são limitadas a 10 níveis de profundidade, e uma única configuração pode herdar de no máximo 100 arquivos pais no total.

Se um arquivo pai estiver ausente, não for YAML válido ou contiver uma configuração inválida, o Axe DevTools Linter relata um erro nomeando o arquivo que causou o problema. No VS Code e IDEs JetBrains, uma notificação aparece e a análise continua usando a configuração padrão. O Axe DevTools Linter Connector relata o erro e sai com o código de saída 3 (veja Códigos de Saída).

`global-components`

A opção de configuração global-components orienta o Axe DevTools Linter sobre como mapear seus próprios componentes personalizados ou componentes de bibliotecas de terceiros para elementos HTML nativos, permitindo que você verifique 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 todos os atributos 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 de acessibilidade usando a opção attributes. Você pode listar atributos que o componente suporta, bem como renomear atributos. Existem três valores especiais:

O valor aria-* indica 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> indica 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> indica ao Axe DevTools Linter que o elemento emitido pode adotar 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>"
          }
        ]
      }
    }
  }
}

Apenas atributos relevantes para acessibilidade precisam estar na lista attributes. Nomes de elementos diferenciam maiúsculas de minúsculas. Camel case, conforme mostrado acima, é comumente usado com arquivos .jsx, mas o kebab case (que é usado em Vue, Angular e elementos personalizados HTML) pode ser usado.

Para tutoriais que mostram como usar o mapeamento de componentes personalizados, consulte Linting de Componentes Personalizados. Para um exemplo passo a passo de como construir e verificar uma configuração para uma biblioteca de componentes, incluindo componentes que não renderizam nenhum elemento próprio, consulte Linting de Salesforce Lightning Web Components (LWC).

`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 a verificação de componentes de biblioteca, adicione o nome do pacote NPM da biblioteca ao array global-libraries para arquivos de configuração YAML:

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

note

Você precisa citar @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. Várias substituições no mesmo arquivo são resolvidas na ordem. Ou seja, a última substituição listada tem a maior precedência.

Atualmente, apenas a substituição linter é suportada e é usada para alterar o analisador 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`

Todas as regras são ativadas e reportadas como erro por padrão. Use a opção rules para alterar como regras individuais são tratadas: defina uma regra para false para desativá-la, ou para warn para relatá-la como aviso em vez de erro. Listar uma regra não restringe a análise apenas às regras que você lista, portanto, não há necessidade de listar as regras que deseja manter. Para limitar a análise a um grupo de regras, use tags.

rules:
  some-rule: false      # turn off rule
  color-contrast: warn  # report violations as warnings instead of errors

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

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

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

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

`tags`

Você pode selecionar regras como um grupo, com base no padrão de acessibilidade com o qual estão associadas, usando a opção tags. Uma regra é verificada se possui alguma das etiquetas que você lista, e toda regra que não possui nenhuma delas é desativada:

tags: # Check only WCAG 2.0 A, WCAG 2.0 AA, and best-practice rules.
  - wcag2a
  - wcag2aa
  - best-practice

important

Como listar uma etiqueta desativa todas as regras que não a possuem, um conjunto restrito de etiquetas desativa a maioria das regras. A maioria das regras que o Axe DevTools Linter verifica possui wcag2a, então uma configuração listando apenas etiquetas WCAG 2.1 deixa quase todas desativadas. Para as etiquetas que você pode usar, veja Etiquetas.

Veja Também

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

Configurando o Axe DevTools Linter

Visão Geral

Exemplos de Configuração

Ordem de Busca do Arquivo de Configuração

Resumo da Configuração do Axe DevTools Linter

Opções de Configuração

`element`

`exclude`

`enterpriseId`

`extends`

Como As Configurações Herdadas São Combinadas

Limites e Tratamento de Erros

`global-components`

`global-libraries`

`overrides`

`rules`

`tags`

Veja Também

Is this page helpful?

Help us improve this page

Try

Still need help?