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 não são mesclados. O primeiro encontrado é o único utilizado.

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 a eventos de análises de uso para atribuição empresarial. A maioria dos usuários não precisará definir este valor; ele pode ser solicitado pelo seu representante de conta Deque. Este campo é ignorado em implantações locais.

enterpriseId: 'acme-corp'

`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 mostrando como usar o mapeamento de componentes personalizados, veja Linting de Componentes Personalizados.

`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`

Você pode permitir ou desativar regras individualmente com a opção rules na sua configuração. Cada regra pode ser configurada como true (ativada, relatada como erro — padrão), false (desativada) ou warn (ativada, relatada como 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 em sua solicitação REST JSON:

{
  "config": {
    "rules": {
      "some-rule": false,
      "other-rule": true,
      "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 desativar regras como um grupo com base no padrão WCAG ao qual estão associadas, usando a opção tags:

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, 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.