Metadata правила

В библиотеке axe-core metadata играет ключевую роль при создании и кастомизации правил доступности. Metadata позволяет описывать правила, их условия срабатывания, категории, теги, влияние на пользователей и рекомендации по исправлению нарушений. Использование metadata обеспечивает более точный контроль над тем, как проверка доступности выполняется в приложении.

Структура metadata

Каждое правило в axe-core может содержать объект meta, который включает следующие основные поля:

  • id – уникальный идентификатор правила. Используется для ссылок и отчетов.
  • impact – уровень влияния нарушения: critical, serious, moderate, minor.
  • title – краткое описание цели правила.
  • description – детальное объяснение, что проверяет правило и почему это важно для доступности.
  • help – текст с рекомендацией по исправлению нарушения.
  • helpUrl – ссылка на документацию или руководство.
  • tags – массив категорий и тегов, к которым относится правило (например, wcag2a, wcag2aa, experimental).

Пример metadata для пользовательского правила:

const customRule = {
  id: "custom-color-contrast",
  impact: "serious",
  title: "Проверка контраста текста",
  description: "Текст на странице должен иметь достаточный контраст с фоном для обеспечения читаемости.",
  help: "Использовать цвета с достаточным контрастом согласно WCAG 2.1",
  helpUrl: "https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html",
  tags: ["wcag2aa", "color-contrast", "accessibility"]
};

Влияние impact

Поле impact определяет, насколько серьезным считается нарушение для пользователей с ограничениями:

  • critical – блокирующее нарушение, которое делает элемент полностью недоступным.
  • serious – серьезное нарушение, которое может существенно ухудшить пользовательский опыт.
  • moderate – умеренное нарушение, которое снижает комфорт взаимодействия.
  • minor – незначительное нарушение, скорее рекомендация по улучшению.

Impact используется в отчетах axe-core для фильтрации и приоритизации ошибок.

Категории и теги

Теги помогают структурировать правила и связывать их с конкретными стандартами доступности, например:

  • wcag2a, wcag2aa, wcag21aa – соответствие требованиям WCAG разных уровней.
  • experimental – экспериментальные или нестандартные проверки.
  • best-practice – рекомендации по улучшению пользовательского опыта.

Теги позволяют запускать сканирование выборочно, активируя только необходимые категории правил.

Поле help и helpUrl

help содержит практическую инструкцию по исправлению нарушений, а helpUrl даёт ссылку на официальные источники. Это важно для автоматизированных тестов и генерации отчетов, так как разработчик получает не только факт нарушения, но и рекомендации по исправлению.

Кастомизация правил через metadata

При создании пользовательских правил metadata обязателен. Это позволяет:

  • Добавлять новые теги и категории, расширяя стандартные проверки.
  • Настраивать impact для соответствия внутренним политикам компании.
  • Предоставлять понятные сообщения для команд разработки и QA.

Пример регистрации кастомного правила:

import axe from 'axe-core';

axe.registerRule({
  id: "custom-alt-text",
  selector: "img",
  evaluate: (node) => node.hasAttribute("alt") ? null : { message: "Отсутствует alt-текст" },
  meta: {
    impact: "critical",
    title: "Проверка alt-текста для изображений",
    description: "Все изображения должны иметь атрибут alt для поддержки скринридеров.",
    help: "Добавить атрибут alt к изображению с описанием содержимого.",
    helpUrl: "https://www.w3.org/WAI/tutorials/images/decision-tree/",
    tags: ["wcag2a", "images", "accessibility"]
  }
});

Динамическая модификация metadata

В некоторых случаях необходимо изменять metadata во время выполнения, например, для разных страниц приложения или специфических компонентов:

axe.run(document, {
  rules: {
    "custom-alt-text": {
      enabled: true,
      impact: "serious" // временно понижаем уровень влияния
    }
  }
});

Это позволяет гибко настраивать проверки без изменения исходного кода правил.

Взаимодействие metadata с отчетами

Все поля metadata автоматически включаются в отчеты axe-core. В отчете можно увидеть:

  • rule id и title для идентификации нарушения.
  • impact для приоритизации исправлений.
  • description, help и helpUrl для понимания сути проблемы.
  • tags для фильтрации нарушений по стандартам.

Использование корректной и полной metadata делает отчеты максимально полезными для команд разработки и QA.

Практические рекомендации по metadata

  1. Уникальные id – не допускать дублирования, чтобы избежать конфликтов в отчетах.
  2. Полные описания – объяснять не только что проверяется, но и зачем.
  3. Корректный impact – реалистично оценивать влияние на пользователей.
  4. Ссылки на стандарты – включать helpUrl с актуальными руководствами.
  5. Использование тегов – структурировать правила по категориям для удобного управления.

Metadata является фундаментальным инструментом axe-core для поддержания прозрачности, точности и гибкости проверки доступности. Правильное использование metadata обеспечивает высокое качество автоматизированного тестирования и удобство работы с отчетами.

Оглавление