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 la 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 rules opción para usar con la extensión Axe Accessibility Linter para VS Code, el plugin de JetBrains, o el Conector de Axe DevTools Linter:

rules:
  html-has-lang: false

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

{
  "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 el html elemento no tiene un lang atributo. (Vea la regla html-has-lang para más información.)

note

Para todos los ejemplos en JSON de este artículo, el config objeto 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 del Archivo de Configuración

La extensión Axe Accessibility Linter para VS Code, el plugin de JetBrains y el Conector de Axe DevTools Linter (cuando se utiliza con la --config opción sin parámetro) buscarán en el directorio actual y en los directorios principales un axe-linter.yml archivo de configuración en el árbol de directorios de su proyecto y usará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 no se fusionan. Solo se utiliza el primero que se encuentra.

Los pasos para localizar el archivo de axe-linter.yml configuración que se utilizará 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 ninguna configuración en el paso 1, busque en los directorios principales hasta encontrar un axe-linter.yml archivo de configuración, 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.
Utilizar un archivo de axe-linter.yml configuración 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`	Consultá 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 `--config` opción 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	Consultá El objeto de configuración.

Opciones de configuración

`element`

La element opción te permite cambiar el elemento emitido según el valor de atributo especificado de tu componente. Por ejemplo, podrías tener un componente personalizado que 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 de 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 img emitido será luego analizado y se encontrará que le falta un atributo alt .

`exclude`

La exclude opción evita que los archivos coincidentes sean analizados. Puedes utilizar comodines y globs. Su uso es principalmente para la extensión de VS Code o el plugin de JetBrains y es ignorado por el endpoint REST.

exclude: *.tmp

`global-components`

La global-components opción de configuración dirige a Axe DevTools Linter sobre cómo mapear tus propios componentes personalizados o componentes de bibliotecas de terceros a elementos HTML nativos, permitiéndote analizar tus componentes como si fueran elementos HTML nativos. Por ejemplo, la siguiente configuración tratará todos los componentes DqButton personalizados como si fueran elementos HTML nativos button . Esto asigna automáticamente cada atributo en 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 los componentes que no asignan todos los atributos a componentes HTML nativos, puedes enumerar los atributos necesarios para el cumplimiento de accesibilidad usando la opción attributes . Puedes listar los atributos que el componente soporta así como renombrar atributos. Hay tres valores especiales:

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

El siguiente ejemplo de 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 distinguen entre mayúsculas y minúsculas. El camel case, como se muestra arriba, se usa comúnmente con archivos .jsx, pero también se puede usar el kebab case (que se utiliza en Vue, Angular y elementos HTML personalizados).

Para guías que muestren cómo usar el mapeo de componentes personalizados, consulta Linting de Componentes Personalizados.

`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 linting de componentes de biblioteca, agrega el nombre del paquete NPM de la biblioteca al array global-libraries en archivos de configuración YAML:

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

note

Debes citar @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, consulta Bibliotecas de Componentes Preconfiguradas.

`overrides`

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

Actualmente, solo se soporta la anulación linter y se utiliza para cambiar el linter 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`

Puedes permitir o desactivar reglas individualmente con la opción rules en tu configuración. Cada regla puede establecerse como true (habilitada, reportada como error — el valor predeterminado), false (deshabilitada), o warn (habilitada, reportada como advertencia):

rules:
  some-rule: false   # turn off rule
  other-rule: true   # turn on rule (default)
  color-contrast: warn  # report violations as warnings instead of errors

O en el objeto config en tu solicitud JSON REST:

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

Para obtener información sobre el uso de rules con la API REST, consulte La propiedad rules. Si desea utilizar rules con el conector de 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 obtener más información sobre el uso de la tags opción 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, vea Supresión de reglas de linting con directivas en línea.

`tags`

Puede desactivar reglas como grupo basándose en el estándar WCAG con el uso de la tags opción:

tags: # Disallow all rules other than WCAG 2.1 A, WCAG 2.1 AA, and best practices.
  - wcag21a
  - wcag21aa
  - best-practices

Véase también

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