Verificación de Componentes Personalizados con el Linter de Accesibilidad Axe para VS Code o IDEs de 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

Una guía para verificar componentes personalizados en VS Code o IDEs de JetBrains

Not for use with personal data

Este artículo muestra cómo configurar la extensión Axe Accessibility Linter para Visual Studio Code (VS Code) o el plugin para JetBrains para encontrar errores de accesibilidad en tus componentes personalizados.

important

Este artículo es para usuarios de la extensión Axe Accessibility Linter para VS Code y el plugin para JetBrains. Si eres usuario del endpoint REST del Linter de Axe DevTools, consulta Verificación de Componentes Personalizados con el Endpoint REST en su lugar.

Si deseas leer una visión general sobre la verificación de componentes personalizados, consulta Verificación de Componentes Personalizados.

Para utilizar esta guía, deberías tener instalado lo siguiente:

Para Visual Studio Code:

Para IDEs de JetBrains:

Un Ejemplo de Error de Accesibilidad

Cuando usas la extensión para verificar el código fuente, cualquier error de accesibilidad se muestra en tu IDE con un subrayado ondulado rojo. Por ejemplo, el siguiente HTML muestra el uso del elemento img sin un atributo alt, lo que es un error de accesibilidad (mostrado en VS Code).

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

(Este es un ejemplo simplificado para demostrar la verificación más que un ejemplo real del mundo.)

La extensión resalta la línea con error y proporciona un tooltip cuando pasas el cursor del ratón sobre el error. Debido a que este elemento img no tiene un atributo alt, obtendrás un error de accesibilidad de la extensión en tu IDE (se muestra VS Code):

Un Componente de Imagen Personalizado

Para este ejemplo, un desarrollador creó un componente personalizado llamado custom-image. La siguiente muestra de código muestra un ejemplo de uso del componente personalizado custom-image:

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

Para este ejemplo, el componente custom-image crea un elemento img con un atributo path (que se asigna a un atributo src por la implementación del control personalizado). La extensión no muestra error porque la extensión no tiene una asignación entre custom-image y img aunque el elemento img resultante falta un atributo alt:

Asignando `custom-image` a `img`

Si proporcionas una asignación entre custom-image y img, el Linter de Axe DevTools puede mapear tu componente personalizado como un elemento HTML estándar y localizar errores de accesibilidad. Puedes especificar la asignación utilizando la opción de configuración global-components en un archivo de configuración axe-linter.yml:

global-components:
  custom-image: img

La extensión ahora resalta el error de accesibilidad y proporciona un tooltip cuando mueves el cursor sobre el error:

También puedes indicar la misma asignación que arriba con cualquiera de estas sintaxis:

global-components:
  custom-image:
    element: img

O, alternativamente, abreviando element como el:

global-components:
  custom-image:
    el: img

important

Cuando utilizas una asignación de elementos, todos los atributos del componente personalizado se copian al elemento emitido, y ese elemento emitido se verifica.

Corrigiendo el Problema de Accesibilidad

Puedes añadir un atributo alt a tu custom-image para solucionar el problema de accesibilidad:

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

Ya no hay un error, por lo que tu IDE ya no muestra el subrayado ondulado rojo (se muestra VS Code):

Asignando un Atributo `alternative-text`

Si tu componente de imagen personalizado utiliza un atributo diferente para indicar texto alternativo, puedes especificar ese atributo en la configuración. Por ejemplo, supongamos que tu componente custom-image utiliza un atributo alternative-text en lugar de alt, como se muestra a continuación:

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

En este caso, podrías especificar una asignación entre el atributo alternative-text y el atributo alt como se muestra con el arreglo attributes en un archivo axe-linter.yml como se muestra a continuación:

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

Esta configuración global-components es ligeramente diferente de la asignación anterior de un componente personalizado a un elemento HTML. Con solo elementos, utilizas una asignación de una clave (custom-image) a un valor (img). Con la inclusión del arreglo attributes, ahora es necesario usar la propiedad element (o el) para especificar el elemento HTML emitido.

Este cambio corrige el error, y no se muestra el subrayado ondulado rojo en tu IDE (se muestra VS Code).

important

Debido a que especificaste la matriz attributes en la configuración, cuando la extensión mapea de custom-image a img, solo los atributos que coinciden con los de la matriz attributes se copian al elemento HTML emitido.

También puedes abreviar attributes como attrs:

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

Valores Especiales de Atributos: `<text>` y `aria-*`

Supongamos que usas un componente custom-button de la siguiente manera:

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

(El botón personalizado, usando JavaScript y CSS que no se incluyen aquí, ocultará y mostrará un div.)

Hay dos problemas con este uso:

Si mapeas este componente custom-button directamente a un elemento button, no habrá contenido de texto para mostrar en el botón. Sin embargo, la intención del autor del componente es que el atributo message se use como contenido de texto: <button> valor del atributo message </button>
El elemento button emitido tiene un rol implícito de button, por lo que el atributo aria-colindex es incorrecto y debe eliminarse.

Como es por defecto, este HTML no resultará en un error porque no hay un mapeo entre custom-button y button. Sin embargo, si creas un mapeo simple entre custom-button y button como se muestra a continuación:

global-components:
  custom-button: button

Recibirás dos errores de tu IDE (se muestra VS Code):

El Valor Especial `<text>`

Para abordar el primer problema (el contenido de texto para el elemento button que proviene de un atributo message, identificado anteriormente como nombre-del-botón en la información sobre herramientas de tu IDE), puedes usar el valor especial <text> que mapea un atributo al contenido de texto del elemento emitido. En este caso, el texto del atributo message debe copiarse al contenido de texto del elemento button emitido.

Para configurar la extensión de modo que el atributo message se considere como contenido de texto para el elemento HTML button, puedes usar el valor especial <text> en un archivo de configuración axe-linter.yml:

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

Debido a que definiste el atributo message como <text>, indicabas a la extensión que considerara ese atributo como reemplazante del contenido textual del elemento HTML button con el valor del atributo message.

Desafortunadamente, al usar el array attributes, el único atributo que se pasó al elemento button emitido fue solo el atributo message; cualquier atributo no presente en el array attributes no se transfiere. Esto significa que el incorrecto aria-colindex no fue detectado por la extensión.

Uso de `aria-*`

Puedes usar el valor especial aria-* para pasar todos los atributos ARIA, como se muestra a continuación:

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

Este error ocurre porque el elemento button tiene un role="button" implícito y usar aria-colindex no es válido con los botones. Con aria-*, todos los atributos ARIA se copian al elemento emitido; esto incluye copiar el atributo aria-colindex no válido.

`<element>`

Con componentes complejos, es posible que desees emitir un elemento HTML diferente al elemento predeterminado en casos específicos. Por ejemplo, podrías tener un componente de botón que normalmente se comporta como un botón y, en otros estados, como una imagen de marcador de posición. El valor <element> te permite especificar un atributo en tu componente personalizado que determine el elemento emitido.

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

En este caso, el atributo use en el componente my-button indica el elemento a emitir. Debido a que el elemento img emitido no contiene un atributo alt, recibirás un error:

Pasar Todos los Atributos Implícitamente

Si hubieras usado solo el mapeo de elementos (donde el mapeo no usa el array attributes), todos los atributos se copiarían, por defecto, al elemento button. La configuración para este caso se mostró anteriormente:

global-components:
  custom-button: button

Junto con el error mostrado en tu IDE (aquí se muestra VS Code):

El ejemplo anterior muestra que un primer paso práctico al comenzar a analizar componentes personalizados sería comenzar con un mapeo de elementos (copiando así todos los atributos al elemento HTML estándar emitido) y luego ver qué atributos necesitan ser agregados a la configuración:

Si alguno de los atributos del componente personalizado debe mapearse a diferentes atributos.
Si necesitas usar <text> o aria-*.

Atributos Predeterminados

Los atributos predeterminados te permiten establecer valores para los atributos en tu archivo de configuración en lugar de mapear un atributo a otro. Por ejemplo, la siguiente configuración de muestra muestra un componente custom-menu mapeado a un elemento li con un role de menú:

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

Debido a que el atributo role tiene un valor predeterminado de menú, establecido en el archivo de configuración, los usuarios no necesitan especificar un atributo role cuando usan el componente custom-menu en su código. La implicación es que la implementación de tu componente personalizado crea estos atributos en el elemento de salida y configura sus valores en lugar de requerir que los usuarios los configuren cuando usan tu componente.

Opcionalmente, el valor name está configurado a nulo en la configuración, lo que hace que Axe DevTools Linter ignore cualquier atributo role que los usuarios hayan especificado en custom-menu en el código analizado.

note

El valor especificado con default debe ser una cadena.