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 no se fusionan. Solo se utiliza el primero que se encuentra.

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 eventos de análisis de uso para la atribución empresarial. La mayoría de los usuarios no necesitarán establecer este valor; puede ser solicitado por su representante de cuenta de Deque. Este campo se ignora en los despliegues locales.

enterpriseId: 'acme-corp'

`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 sobre cómo usar el mapeo de componentes personalizados, consulte 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 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`

Puede permitir o desactivar reglas individualmente con la opción rules en su configuración. Cada regla puede configurarse 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 su solicitud REST JSON:

{
  "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 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`

Puede desactivar reglas como grupo basado en el estándar WCAG con el que están asociadas usando la opción tags:

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 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.