Verificação de Componentes Customizados com o Linter de Acessibilidade Axe para VS Code ou IDEs JetBrains

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 passo a passo para verificar componentes customizados no VS Code ou IDEs JetBrains

Not for use with personal data

Este artigo mostra como configurar a extensão Axe Accessibility Linter para Visual Studio Code (VS Code) ou o plugin para JetBrains para encontrar erros de acessibilidade nos seus componentes customizados.

important

Este artigo é para usuários da extensão Axe Accessibility Linter para VS Code e do plugin para JetBrains. Se você for um usuário do terminal REST do Axe DevTools Linter, veja Verificação de Componentes Customizados com o Terminal REST em vez disso.

Se você gostaria de ler uma visão geral sobre verificação de componentes customizados, veja Verificação de Componentes Customizados.

Para usar este passo a passo, você deve ter instalado o seguinte:

Para Visual Studio Code:

Para IDEs JetBrains:

Um Exemplo de Erro de Acessibilidade

Quando você usa a extensão para verificar o código-fonte, quaisquer erros de acessibilidade são mostrados em seu IDE com um sublinhado ondulado vermelho. Por exemplo, o HTML a seguir mostra o uso do img elemento sem um alt atributo, o que é um erro de acessibilidade (mostrado no VS Code).

<img src="path/to/image.jpg"/>

(Este é um exemplo excessivamente simplificado para demonstrar a verificação ao invés de um exemplo real).

A extensão destaca a linha com erro e fornece uma dica de ferramenta quando você passa o cursor do mouse sobre o erro. Como este img elemento não possui um alt atributo, você obterá um erro de acessibilidade da extensão em seu IDE (VS Code mostrado):

Um Componente de Imagem Customizado

Para este exemplo, um desenvolvedor criou um componente customizado chamado custom-image. O exemplo a seguir mostra a utilização do componente customizado custom-image :

<custom-image path="images/image.jpg"></custom-image>

Para este exemplo, o custom-image componente cria um img elemento com um path atributo (que é mapeado para um src atributo pela implementação do controle customizado). A extensão não mostra erro porque não há mapeamento entre custom-image e img embora o img elemento de saída esteja faltando um alt atributo:

Mapeamento `custom-image` para `img`

Se você fornecer um mapeamento entre custom-image para img, o Axe DevTools Linter pode mapear seu componente personalizado como um elemento HTML padrão e localizar erros de acessibilidade. Você pode especificar o mapeamento usando a opção de configuração global-components em um arquivo de configuração axe-linter.yml :

global-components:
  custom-image: img

A extensão agora destaca o erro de acessibilidade e fornece uma dica de ferramenta quando você passa o cursor sobre o erro:

Você também pode indicar o mesmo mapeamento acima com qualquer uma dessas sintaxes:

global-components:
  custom-image:
    element: img

Ou, alternativamente, abreviando element como el:

global-components:
  custom-image:
    el: img

important

Quando você usa um mapeamento de elementos, todos os atributos do componente personalizado são copiados para o elemento emitido, e esse elemento emitido é verificado.

Corrigindo o Problema de Acessibilidade

Você pode adicionar um atributo alt ao seu custom-image para corrigir o problema de acessibilidade:

<custom-image path="images/image.jpg" alt="alt text"></custom-image>

Não há mais erro, então seu IDE não exibe mais o sublinhado vermelho ondulado (mostrado no VS Code):

Mapeando um `alternative-text` Atributo

Se o seu componente de imagem personalizado usar um atributo diferente para indicar texto alternativo, você pode especificar esse atributo na configuração. Por exemplo, suponha que seu custom-image componente use um atributo alternative-text em vez de alt, conforme mostrado abaixo:

<custom-image path="images/image.jpg" alternative-text="alt text"></custom-image>

Nesse caso, você poderia especificar um mapeamento entre o atributo alternative-text e o atributo alt conforme mostrado com o array attributes em um arquivo axe-linter.yml conforme mostrado abaixo:

global-components:
  custom-image:
    element: img
    attributes:
      - alternative-text: alt

Esta configuração global-components é ligeiramente diferente do mapeamento anterior de um componente personalizado para um elemento HTML. Com apenas elementos, você usa um mapeamento de uma chave (custom-image) para um valor (img). Com a inclusão do array attributes , agora é necessário usar a propriedade element (ou el) para especificar o elemento HTML emitido.

Esta alteração corrige o erro, e não há sublinhado vermelho ondulado mostrado no seu IDE (VS Code é mostrado).

important

Porque você especificou o array attributes na configuração, quando a extensão mapeia de custom-image para img , *somente* os atributos correspondentes àqueles no array attributes são copiados para o elemento HTML emitido.

Você também pode abreviar attributes como attrs:

global-components:
  custom-image:
    element: img
    attrs:
      - alternative-text: alt

Valores Especiais de Atributos: `<text>` e `aria-*`

Suponha que você use um custom-button componente da seguinte forma:

<custom-button aria-controls="expand-region" aria-expanded="false" aria-colindex="1" message="Show Region"></custom-button>

(O botão personalizado, usando JavaScript e CSS que não estão incluídos aqui, esconderá e mostrará um div.)

Há dois problemas com este uso:

Se você mapear este custom-button componente diretamente para um button elemento, não haverá conteúdo textual para ser exibido no botão. A intenção do autor do componente, no entanto, é que o message atributo deve ser usado como conteúdo do texto: <button> valor do message atributo </button>
O button elemento emitido possui um papel implícito de button então o aria-colindex atributo está incorreto e deve ser removido.

Como padrão, este HTML não resultará em um erro porque não há mapeamento entre custom-button e button. No entanto, se você criar um mapeamento simples entre custom-button e button como mostrado abaixo:

global-components:
  custom-button: button

Você receberá dois erros do seu IDE (VS Code está mostrado):

O Valor `<text>` Especial

Para resolver o primeiro problema (conteúdo do texto para o button elemento vindo de um message atributo, identificado acima como button-name na dica do IDE), você pode usar o valor <text> especial que mapeia um atributo para o conteúdo de texto do elemento emitido. Neste caso, o texto do message atributo deve ser copiado para o conteúdo de texto do button elemento emitido.

Para configurar a extensão para que o message atributo seja considerado como conteúdo de texto para o elemento HTML button , você pode usar o valor especial <text> em um arquivo de configuração axe-linter.yml :

global-components:
  custom-button:
    element: button
    attributes:
      - message: <text>

Como você definiu o message atributo como <text>, você informou à extensão para considerar esse atributo como substituindo o conteúdo textual do elemento HTML button com o valor do message atributo.

Infelizmente, ao usar o attributes array, o único atributo que foi passado para o elemento emitido button foi apenas o message ; quaisquer atributos que não estão no attributes array não são passados. Isso significa que o incorreto aria-colindex não foi detectado pela extensão.

Usando `aria-*`

Você pode usar o valor especial aria-* valor para passar todos os atributos ARIA, conforme mostrado abaixo:

global-components:
  custom-button:
    element: button
    attributes:
      - message: <text>
      - aria-*

Este erro ocorre porque o button elemento tem um role="button" implícito e usar aria-colindex é inválido com botões. Com aria-*, todos os atributos ARIA são copiados para o elemento emitido; isso inclui a cópia do aria-colindex atributo inválido.

`<element>`

Com componentes complexos, você pode querer emitir um elemento HTML diferente do elemento padrão em casos específicos. Por exemplo, você pode ter um componente de botão que normalmente se comporta como um botão e, em outros estados, como uma imagem de espaço reservado. O <element> valor permite especificar um atributo no seu componente personalizado que determina o elemento emitido.

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

Nesse caso, o use atributo no componente my-button indica o elemento a ser emitido. Como o elemento emitido img não contém um atributo alt , você receberá um erro:

Passando Todos os Atributos Implicitamente

Se você tivesse usado apenas o mapeamento de elementos (onde o mapeamento não usa o attributes array), todos os atributos seriam, por padrão, copiados para o button elemento. A configuração para este caso foi mostrada anteriormente:

global-components:
  custom-button: button

Junto com o erro mostrado no seu IDE (VS Code é mostrado aqui):

O exemplo acima mostra que um primeiro passo prático ao começar a verificar componentes personalizados seria começar com um mapeamento de elementos (assim copiando todos os atributos para o elemento HTML padrão emitido) e então ver quais atributos precisam ser adicionados à configuração:

Se algum dos atributos do componente personalizado deve ser mapeado para atributos diferentes.
Se você precisa usar <text> ou aria-*.

Atributos Padrão

Os atributos padrão permitem definir valores para atributos em seu arquivo de configuração em vez de mapear um atributo para outro. Por exemplo, a configuração de exemplo a seguir mostra um componente custom-menu mapeado para um elemento li com um role de *menu*:

global-components:
  custom-menu:
    element: li
    attributes:
      - role:
          name: null
          default: menu

Como o atributo role tem um valor padrão de *menu*, definido no arquivo de configuração, os usuários não precisam especificar um atributo role ao usarem o componente custom-menu em seu código. A implicação é que a implementação do seu componente personalizado cria esses atributos no elemento de saída e define seus valores, em vez de exigir que os usuários os definam ao usarem o seu componente.

Opcionalmente, o valor name é definido como *null* na configuração, o que faz com que o Axe DevTools Linter ignore quaisquer atributos role que os usuários tenham especificado em custom-menu no código verificado.

note

O valor especificado com default deve ser uma string.