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 do extensão Axe Accessibility Linter para VS Code e do plugin para JetBrains. Se você for um usuário do ponto de extremidade Axe DevTools Linter REST, consulte Verificação de Componentes Customizados com o Terminal REST em vez disso.

Se você gostaria de ler uma visão geral sobre a verificação de componentes personalizados, consulte 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 vermelho ondulado. Por exemplo, o seguinte HTML mostra o uso do elemento img sem um atributo alt, 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 elemento img não tem um atributo alt, você receberá 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 personalizado chamado custom-image. O exemplo a seguir mostra o uso do componente personalizado custom-image:

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

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

Mapeamento de `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, ao abreviar 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 Atributo `alternative-text`

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 componente custom-image use um atributo alternative-text em vez de alt, como 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, como 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 que correspondem aos do 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 de Atributos Especiais: `<text>` e `aria-*`

Suponha que você use um componente custom-button 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, ocultará e mostrará um div.)

Há dois problemas com este uso:

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

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

global-components:
  custom-button: button

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

O Valor Especial `<text>`

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

Para configurar a extensão para que o atributo message 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>

Porque você definiu o atributo message como <text>, você instruiu a extensão a considerar que esse atributo substitui o conteúdo textual do elemento HTML button com o valor do atributo message.

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

Usando `aria-*`

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

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

Este erro ocorre porque o elemento button possui 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 copiar o atributo aria-colindex 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 valor <element> permite que você especifique um atributo no seu componente personalizado que determina o elemento emitido.

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

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

Passando Todos os Atributos Implicitamente

Se você usasse apenas o mapeamento de elementos (onde o mapeamento não usa o array attributes), todos os atributos seriam, por padrão, copiados para o elemento button. 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

Atributos padrão permitem que você defina 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 possui um valor padrão de *menu*, definido no arquivo de configuração, os usuários não precisam especificar um atributo role quando usam 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 usar 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.