Configuración de 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

Una guía de referencia para configurar Axe DevTools Linter

Not for use with personal data

Este artículo proporciona una referencia para las opciones de configuración de Axe DevTools Linter.

Visión general

El endpoint de la API REST utiliza JSON para la configuración, y el extensión Axe Accessibility Linter para VS Code, el plugin de JetBrains y el Conector de Axe DevTools Linter utilizan YAML para la configuración. En esta guía se muestran ejemplos de configuraciones de Axe DevTools Linter tanto en JSON como en YAML.

Ejemplos de Configuración

El siguiente ejemplo en YAML demuestra una configuración simple que utiliza la opción rules para su uso con la extensión Axe Accessibility Linter para VS Code, el plugin de JetBrains o el conector Axe DevTools Linter:

rules:
  html-has-lang: false

El siguiente ejemplo demuestra la misma configuración como un objeto de solicitud completo con la opción rules para el servicio REST de Axe DevTools Linter, con su objeto config resaltado:

{
  "source": "<html></html>",
  "filename": "file.html",
  "config": {    "rules": {      "html-has-lang": false    },    "exclude": [],
    "tags": []
  }
}

En ambos casos, estas configuraciones hacen que Axe DevTools Linter ignore los errores de accesibilidad cuando al elemento html le falta un atributo lang. (Consulte la regla regla html-has-lang para más información.)

note

Para todos los ejemplos de JSON en este artículo, el objeto config se incluye para proporcionar una ubicación de referencia para la configuración.

Las siguientes secciones describen cada opción de configuración y dan ejemplos de su uso.

Orden de búsqueda de archivos de configuración

La extensión Axe Accessibility Linter para VS Code, el plugin de JetBrains, y el conector Axe DevTools Linter (cuando se usa con la opción --config sin parámetro) buscarán en el directorio actual y en los directorios de nivel superior un archivo de configuración axe-linter.yml en el árbol de directorios de su proyecto y utilizarán el primero que encuentren. Una práctica útil es colocar un archivo de configuración en la raíz de su proyecto que contenga su configuración predeterminada, y reemplazarlo (si es necesario) con archivos de configuración en diferentes subdirectorios. También puede colocar un archivo de configuración en su directorio de inicio que se usará por defecto si no hay archivos de configuración en su proyecto.

important

Los archivos de configuración encontrados por esta búsqueda no se combinan entre sí. El primero que se encuentra es el único que se utiliza. Para combinar configuraciones de más de un archivo, haga que el archivo de configuración herede de los otros con la opción extends.

Los pasos para localizar el archivo de configuración axe-linter.yml que se va a usar son:

Usar el archivo de configuración en el directorio actual (el directorio que contiene el archivo que se está editando con VS Code, un IDE de JetBrains o el directorio actual del comando prompt con el Conector de Axe DevTools Linter).
Si no se encuentra una configuración en el paso 1, busque en los directorios de nivel superior hasta encontrar un archivo de configuración axe-linter.yml, deteniéndose en su carpeta de inicio si el proyecto está en su árbol de directorios de inicio o en el directorio raíz si está fuera de su carpeta de inicio.
Use un archivo de configuración axe-linter.yml ubicado en su directorio de inicio (incluso si su proyecto se encuentra en un directorio fuera de su carpeta de inicio o en otra unidad en Windows). Por ejemplo, estos son los archivos típicos utilizados:
- /home/nombredeusuario/axe-linter.yml (Linux)
- /Users/nombredeusuario/axe-linter.yml (macOS)
- C:\Users\nombredeusuario\axe-linter.yml (Windows)

La búsqueda se detiene cuando se encuentra el primer archivo axe-linter.yml.

Resumen de la Configuración de Axe DevTools Linter

Producto	Tipo de Configuración	Descripción
Extensión Axe Accessibility Linter para VS Code o el plugin de JetBrains	Un archivo YAML llamado `axe-linter.yml`	Consulte Orden de búsqueda de archivos de configuración.
Conector del Linter de Axe	Un archivo YAML llamado `axe-linter.yml`	Sigue los pasos en Orden de búsqueda de archivos de configuración cuando se usa con la opción `--config` sin parámetro.
Conector del Linter de Axe	Un archivo YAML llamado nombre de archivo	Cuando se usa con `--config` nombre de archivo.
API REST del Linter de Axe	Objeto de configuración JSON	Consulte El objeto de configuración.

Opciones de configuración

`element`

La opción element le permite cambiar el elemento emitido basado en el valor de atributo especificado de su componente. Por ejemplo, podría hacer que un componente personalizado emita un elemento img en ciertos casos y un elemento button en otros casos, permitiendo casos de uso más complejos.

La configuración de ejemplo a continuación especifica que el atributo as en el componente my-button puede cambiar el elemento emitido del valor predeterminado de button:

YAML:

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

JSON:

{
  "config": {
    "global-components": {
      "my-button": {
        "element": "button",
        "attributes": [
          {
            "as": "<element>"
          }
        ]
      }
    }
  }
}

El uso del ejemplo a continuación emite un elemento img en lugar del elemento predeterminado button porque el atributo as especifica el elemento de salida:

<my-button as="img"></my-button>

El elemento de salida img será entonces analizado y se encontrará que le falta un atributo alt.

`exclude`

La opción exclude impide que se realice el análisis en los archivos coincidentes. Puede usar comodines y globs. Su uso es principalmente para la extensión VS Code o el plugin de JetBrains y es ignorado por el punto final REST.

exclude: *.tmp

`enterpriseId`

El campo opcional enterpriseId acepta una cadena que se adjunta a los eventos de análisis de uso para la atribución empresarial. La mayoría de los usuarios no necesitarán establecer este valor; su representante de cuenta de Deque podría solicitarlo. Este campo se ignora para implementaciones locales.

enterpriseId: 'acme-corp'

`extends`

La opción extends permite que un archivo axe-linter.yml herede sus configuraciones de uno o más archivos de configuración principales, de modo que una base compartida pueda residir en un solo lugar en lugar de copiarse en cada proyecto. Acepta una ruta de archivo única o una matriz de rutas de archivo, y está disponible en la versión 4.13.0 y posteriores de la extensión Axe Accessibility Linter para VS Code, el plugin de JetBrains y Axe DevTools Linter Connector.

extends: ./axe-linter.base.yml
rules:
  color-contrast: warn

Para heredar de más de un archivo, use un array:

extends:
  - ./axe-linter.base.yml
  - ../shared/team-rules.yml

Las rutas se resuelven en relación con el archivo que contiene la opción extends, no con el directorio desde el cual inició el linter. También se aceptan rutas absolutas. Los archivos principales no tienen que llamarse axe-linter.yml, y un archivo principal puede usar extends para heredar de otro archivo.

note

No se admiten nombres de paquetes simples (como @my-org/axe-linter-config) ni URLs remotas (como https://example.com/axe-linter.yml). Solo se pueden usar rutas de archivo relativas y absolutas.

Cómo se combinan las configuraciones heredadas

Los archivos principales se leen de izquierda a derecha, y su propia configuración se aplica al final, por lo que prevalece en cualquier conflicto. Cada opción se combina de la siguiente manera:

Opción	Cómo se combina
`rules`	Se fusionan por ID de regla, y su valor prevalece. Debido a que cada regla está habilitada y reportada como un error por defecto (ver `rules`), un archivo principal usa esta opción para deshabilitar reglas o reportarlas como advertencias, y su propia configuración puede cambiar cualquiera de esas decisiones, incluyendo establecer una regla de nuevo a `true` para restaurar el reporte de errores predeterminado.
`tags`	Se combinan con los valores del principal, eliminando duplicados.
`exclude`	Se combinan con los valores del principal, eliminando duplicados.
`global-libraries`	Se combinan con los valores del principal, eliminando duplicados.
`global-components`	Se fusionan por nombre de componente. Una entrada en su configuración sustituye completamente a una entrada principal con el mismo nombre en lugar de fusionarse en ella, por lo que repetir un nombre de componente significa repetir todas las configuraciones de ese componente.
`overrides`	Se combinan, con las entradas del principal primero, seguidas de las suyas.
Cualquier otra opción, como `enterpriseId`	Su valor prevalece, y el principal proporciona el valor para cualquier opción que omita.

important

Si un archivo principal establece enterpriseId y su propia configuración no lo hace, el uso de su proyecto se contabiliza bajo el ID de empresa del principal. Establezca enterpriseId en su propia configuración si necesita un valor diferente.

Límites y Manejo de Errores

Un archivo de configuración no puede extenderse a sí mismo, ya sea directa o indirectamente a través de una cadena de archivos principales. Las cadenas están limitadas a 10 niveles de profundidad, y una configuración única puede heredar de no más de 100 archivos principales en total.

Si falta un archivo principal, no es un YAML válido o contiene una configuración inválida, Axe DevTools Linter informa un error nombrando el archivo que causó el problema. En VS Code y JetBrains IDEs, aparece una notificación y el análisis continúa usando la configuración predeterminada. Axe DevTools Linter Connector informa el error y sale con el código de salida 3 (ver Códigos de salida).

`global-components`

La opción de configuración global-components indica a Axe DevTools Linter cómo mapear sus propios componentes personalizados o componentes de bibliotecas de terceros a elementos HTML nativos, permitiéndole analizar sus componentes como si fueran elementos HTML nativos. Por ejemplo, la siguiente configuración tratará todos los componentes DqButton personalizados como si fueran elementos HTML button nativos. Esto automáticamente mapea cada atributo de DqButton a button, requiriendo así un nombre accesible para todos los componentes DqButton.

YAML:

global-components:
  DqButton: button

JSON:

{
  "config": {
    "global-components" {
      "DqButton": "button"
    }
  }
}

Alternativamente, para componentes que no mapean todos los atributos a componentes HTML nativos, puede listar los atributos requeridos para la conformidad de accesibilidad usando la opción attributes. Puede listar atributos que el componente soporta así como renombrar atributos. Hay tres valores especiales:

El valor aria-* le indica a Axe DevTools Linter que todos los atributos que comienzan con aria- se mapean al elemento HTML nativo tal cual. Tenga en cuenta que el valor termina con un asterisco.
El valor <text> le dice a Axe DevTools Linter que se usa una propiedad para establecer el contenido (el valor entre las etiquetas de apertura y cierre) del elemento HTML nativo.
El valor <element> le dice a Axe DevTools Linter que el elemento emitido puede tomar el valor de este atributo, lo cual le permite cambiar el elemento emitido dependiendo del valor del atributo especificado.

El siguiente ejemplo en YAML muestra todos los valores que se pueden usar con 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.)

Una versión equivalente en JSON (dentro del objeto config) es la siguiente:

{
  "config": {
    "global-components": {
      "DqButton": {
        "element": "button",
        "attributes": [
          "role",
          "aria-*",
          {
            "action": "type"
          },
          {
            "label": "<text>"
          },
          {
            "as": "<element>"
          }
        ]
      }
    }
  }
}

Solo los atributos relevantes para la accesibilidad necesitan estar en la lista attributes. Los nombres de los elementos son sensibles a mayúsculas y minúsculas. La notación camello, como se muestra arriba, se utiliza comúnmente con archivos .jsx, pero se puede usar la notación kebab (que se usa en Vue, Angular, y elementos personalizados de HTML).

Para guías detalladas que muestren cómo usar el mapeo de componentes personalizados, consulte Linting de componentes personalizados. Para un ejemplo paso a paso de cómo construir y verificar una configuración para una biblioteca de componentes, incluidos componentes que no renderizan ningún elemento propio, consulte Comprobación de componentes web Lightning de Salesforce (LWC).

`global-libraries`

Axe DevTools Linter tiene soporte integrado para varias bibliotecas y frameworks de componentes populares.

Las siguientes bibliotecas están actualmente soportadas:

react-native
@mui/material
@deque/cauldron-react

Para habilitar el análisis de los componentes de la biblioteca, agrega el nombre del paquete NPM de la biblioteca al array global-libraries para los archivos de configuración YAML:

global-libraries:
  - '@mui/material'
  - '@deque/cauldron-react'
  - react-native

note

Necesita entrecomillar @mui/material y @deque/cauldron-react en YAML porque @ se interpreta como un carácter reservado.

O la configuración equivalente en JSON se muestra a continuación:

{
  "config": {
    "global-libraries": [
      "@mui/material"
    ]
  }
}

Cualquier componente con el mismo nombre que un componente de la biblioteca global será tratado como ese componente de la biblioteca, permitiendo la reexportación y redefinición de componentes sin perder su mapeo.

Para más información, consulte Bibliotecas de Componentes Preconfiguradas.

`overrides`

Puede cambiar cómo se configura Axe DevTools Linter por archivo usando la opción de configuración overrides. Las múltiples sobreescrituras en el mismo archivo se resuelven en orden. Es decir, la última sobreescritura listada tiene la máxima precedencia.

Actualmente, solo se soporta la sobreescritura linter y se utiliza para cambiar el analizador usado en los archivos coincidentes.

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`

Todas las reglas están habilitadas y se reportan como error por defecto. Usa la opción rules para cambiar cómo se manejan las reglas individuales: establece una regla en false para desactivarla, o en warn para reportarla como advertencia en lugar de error. Listar una regla no restringe el análisis a las reglas que enumeras, así que no es necesario listar las reglas que deseas mantener. Para limitar el análisis a un grupo de reglas, usa etiquetas en su lugar.

rules:
  some-rule: false      # turn off rule
  color-contrast: warn  # report violations as warnings instead of errors

O en el objeto config en su solicitud REST JSON:

{
  "config": {
    "rules": {
      "some-rule": false,
      "color-contrast": "warn"
    }
  }
}

Para obtener información sobre el uso de rules con la API REST, consulte La propiedad rules. Si desea usar rules con el conector Axe DevTools Linter, consulte Archivo de configuración. Para ver las reglas que sigue Axe DevTools Linter, consulte Reglas de Accesibilidad. Consulte etiquetas a continuación para más información sobre el uso de la opción tags para excluir colecciones de reglas de ser procesadas.

Para suprimir reglas para líneas específicas en un archivo fuente sin modificar este archivo de configuración, consulte Supresión de reglas de linting con directivas en línea.

`tags`

Puedes seleccionar reglas como grupo, basándote en el estándar de accesibilidad con el que están asociadas, usando la opción tags. Una regla se verifica si lleva alguna de las etiquetas que enumeras, y toda regla que no lleve ninguna de ellas queda desactivada:

tags: # Check only WCAG 2.0 A, WCAG 2.0 AA, and best-practice rules.
  - wcag2a
  - wcag2aa
  - best-practice

important

Debido a que listar una etiqueta desactiva cada regla que no la lleva, un conjunto reducido de etiquetas desactiva la mayoría de las reglas. La mayoría de las reglas que Axe DevTools Linter verifica llevan wcag2a, por lo que una configuración que solo enumere etiquetas de WCAG 2.1 deja casi todas desactivadas. Para las etiquetas que puedes usar, consulta Etiquetas.

Véase también

Para una referencia de las APIs REST proporcionadas por Axe DevTools Linter, consulte La referencia de la API REST de Axe DevTools Linter.
Para guías sobre cómo crear mapeos de componentes personalizados, consulte Linting de componentes personalizados.
Para descargar la extensión para VS Code, consulte Axe Accessibility Linter.
Para más información sobre el plugin de JetBrains, consulte Uso del plugin con JetBrains IDEs.

Configuración de Axe DevTools Linter

Visión general

Ejemplos de Configuración

Orden de búsqueda de archivos de configuración

Resumen de la Configuración de Axe DevTools Linter

Opciones de configuración

`element`

`exclude`

`enterpriseId`

`extends`

Cómo se combinan las configuraciones heredadas

Límites y Manejo de Errores

`global-components`

`global-libraries`

`overrides`

`rules`

`tags`

Véase también

Is this page helpful?

Help us improve this page

Try

Still need help?