Linting de componentes personalizados con el axe Linter de accesibilidad para IDE de VS Code o JetBrains

Link to Linting de componentes personalizados con el axe Linter de accesibilidad para IDE de VS Code o JetBrains copied to clipboard

Tutorial para linting de componentes personalizados en IDE de VS Code o JetBrains

Free Trial

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 complemento para JetBrains para encontrar errores de accesibilidad en sus componentes personalizados.

important

Este artículo está dirigido a los usuarios de la extensión axe Accessibility Linter para VS Code y del complemento para JetBrains. Si es usuario del punto final REST de axe DevTools Linter, consulte Análisis de componentes personalizados con el punto final REST .

Si desea leer una descripción general sobre el análisis de componentes personalizados, consulte Análisis de componentes personalizados.

Para utilizar este tutorial, debe tener instalado lo siguiente:

Para Visual Studio Code:

Para los IDE de JetBrains:

Un ejemplo de error de accesibilidad

Cuando utiliza la extensión para analizar el código fuente, cualquier error de accesibilidad se muestra en su IDE con un subrayado rojo ondulado. 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 muy simplificado para demostrar el funcionamiento del linting en lugar de un ejemplo real).

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

Un componente de imagen personalizado

Para este ejemplo, un desarrollador creó un componente personalizado llamado custom-image. El siguiente ejemplo muestra el uso del componente personalizado: custom-image

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

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

Mapeo de `custom-image` a `img`

Si proporciona una asignación entre custom-image y img, axe DevTools Linter puede asignar su componente personalizado como un elemento HTML estándar y localizar errores de accesibilidad. Puede especificar la asignación mediante la opción de configuración en un archivo de configuración: global-components axe-linter.yml

global-components:
  custom-image: img

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

También puede indicar la misma asignación que la anterior 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 se utiliza una asignación de elementos, todos los atributos del componente personalizado se copian al elemento emitido, y ese elemento emitido se somete a análisis lint.

Cómo solucionar el problema de la accesibilidad

Puede agregar un alt atributo a custom-image su para solucionar el problema de accesibilidad:

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

Ya no hay ningún error, por lo que su IDE ya no muestra la línea ondulada roja (como se muestra en VS Code):

Asignación de un `alternative-text` atributo

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

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

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

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

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

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

important

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

También puede abreviar attributes como attrs:

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

Valores de atributos especiales: `<text>` y `aria-*`

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

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

(El botón personalizado, utilizando JavaScript y CSS que no están incluidos aquí, ocultará y mostrará un div.)

Hay dos problemas con este uso:

Si asigna este componente directamente a un elemento, no se mostrará ningún contenido de texto en el botón. custom-button button Sin embargo, la intención del autor del componente es que el atributo message se utilice como contenido de texto: <button> *valor del atributo message * </button>
El elemento emitido tiene una función implícita de un, por lo que el atributo es incorrecto y debe eliminarse. button button aria-colindex

Como es el valor predeterminado, este HTML no generará un error porque no hay ninguna correspondencia entre custom-button y button. Sin embargo, si crea una asignación 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 (contenido de texto para el button elemento que proviene de un message atributo, identificado anteriormente como button-name en la información sobre herramientas de su IDE), puede usar el <text> valor especial que asigna un atributo al contenido de texto del elemento emitido. En este caso, el texto del atributo debe copiarse al contenido de texto del elemento emitido. message button

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

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

Debido a que definió el atributo message como <text>, le indicó a la extensión que considere ese atributo como reemplazo del contenido textual del elemento HTML button con el valor del atributo message .

Desafortunadamente, al usar el array, el único atributo que se pasó al elemento emitido fue el único atributo; cualquier atributo que no esté en el array no se pasa. attributes button message attributes Esto significa que la extensión no detectó el error. aria-colindex

Usando `aria-*`

Puede utilizar 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 se produce porque el elemento button tiene un role="button" implícito y usar aria-colindex no es válido con botones. Con atributo aria-*, all ARIA attributes are copied to the emitted element; this includes copying the invalid aria-colindex.

`<element>`

Con componentes complejos, es posible que desees emitir un elemento HTML diferente al elemento predeterminado en casos específicos. Por ejemplo, es posible que tenga 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> le permite especificar un atributo en su componente personalizado que determina 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 alt un atributo, recibirá un error:

![VS Code que muestra un componente personalizado con un atributo alt faltante].(../images/element-example.png)

Pasar todos los atributos implícitamente

Si hubieras utilizado solo la asignación de elementos (donde la asignación no utiliza la matriz), todos los atributos se copiarían, de manera predeterminada, al elemento. attributes button La configuración para este caso se mostró anteriormente:

global-components:
  custom-button: button

Junto con el error que se muestra en su IDE (VS Code se muestra aquí):

![Captura de pantalla de VS Code que muestra una asignación de elementos simple que hace que todos los atributos se copien al elemento de salida, lo que genera los dos errores que se muestran].(../images/example5-vscode.png)

El ejemplo anterior muestra que un primer paso práctico al comenzar a lintear 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 deben agregarse a la configuración:

Si alguno de los atributos del componente personalizado debe asignarse a atributos diferentes.
Ya sea que necesites usar <text> o aria-*.

Atributos predeterminados

Los atributos predeterminados le permiten establecer valores para los atributos en su archivo de configuración en lugar de asignar un atributo a otro. Por ejemplo, la siguiente configuración de muestra muestra un componente asignado a un elemento con un tipo de menú: custom-menu li role **

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 su componente personalizado crea estos atributos en el elemento de salida y establece sus valores en lugar de requerir que los usuarios los establezcan cuando usan su componente.

Opcionalmente, el valor name se establece en nulo en la configuración, lo que hace que axe DevTools Linter ignore cualquier role atributo que los usuarios hayan especificado en custom-menu el código analizado.

note

El valor especificado con default debe ser una cadena.