Регистрация правила

Библиотека Axe-core представляет собой инструмент для автоматизированной проверки доступности веб-приложений. Одной из ключевых возможностей является расширение набора правил, что позволяет проверять специфические требования к доступности, характерные для конкретного проекта. Регистрация нового правила осуществляется через API библиотеки и требует точного понимания структуры правил и объектов, которые Axe-core использует для анализа DOM.

Структура правила

Каждое правило в Axe-core определяется объектом с набором обязательных и необязательных свойств. Основные ключи объекта правила:

  • id — уникальный идентификатор правила. Используется для ссылки на правило при запуске проверок.
  • context — CSS-селектор или функция, определяющая область применения правила. Правило будет применяться ко всем элементам, соответствующим контексту.
  • enabled — логическое значение, указывающее, включено ли правило по умолчанию.
  • tags — массив тегов, определяющий категорию правила (например, wcag2a, wcag2aa, best-practice).
  • description — текстовое описание цели проверки.
  • help — краткая подсказка для пользователя о том, как исправить найденные нарушения.
  • helpUrl — ссылка на документацию или рекомендации по исправлению.
  • check — функция, выполняющая фактическую проверку элемента. Именно здесь реализуется логика анализа доступности.

Пример минимального объекта правила:

const customRule = {
  id: 'custom-button-label',
  context: 'button',
  enabled: true,
  tags: ['wcag2a', 'best-practice'],
  description: 'Проверяет, что кнопка имеет текстовую метку',
  help: 'Добавить текстовую метку к кнопке для доступности',
  helpUrl: 'https://www.w3.org/WAI/WCAG21/Techniques/html/H37',
  check: function(node, options) {
    return {
      result: node.textContent.trim() !== ''
    };
  }
};

Метод регистрации правила

Для регистрации собственного правила используется метод axe.registerRule(rule). Он принимает один объект правила или массив правил. Пример:

axe.registerRule(customRule);

После регистрации правило становится доступным при последующих вызовах axe.run. Важно учитывать, что правила регистрируются глобально для текущего контекста библиотеки и могут быть отключены или модифицированы через дополнительные настройки.

Контекст и селекторы

Контекст правила задаёт, к каким элементам будет применяться проверка. Возможны следующие варианты:

  1. CSS-селекторы — строки, аналогичные стандартным селекторам querySelectorAll:
context: 'input[type="text"]'
  1. Функции — функция принимает элемент и возвращает true или false:
context: function(node) {
  return node.tagName === 'IMG' && node.alt === '';
}

Использование функций позволяет реализовать сложные условия, зависящие от атрибутов, структуры DOM или других свойств элемента.

Реализация функции check

Функция check является ядром правила. Она принимает два параметра:

  • node — текущий DOM-элемент, соответствующий контексту.
  • options — дополнительные параметры, передаваемые при запуске проверки.

Функция должна возвращать объект с обязательным ключом result:

  • result: true — элемент прошёл проверку.
  • result: false — элемент нарушает правило.

Дополнительно можно возвращать информацию о нарушении:

return {
  result: node.hasAttribute('aria-label'),
  message: 'Элемент должен иметь атрибут aria-label'
};

Сообщение message будет отображаться в отчётах Axe-core, облегчая анализ проблем доступности.

Регистрация нескольких правил одновременно

Axe-core поддерживает регистрацию массива правил:

axe.registerRule([rule1, rule2, rule3]);

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

Управление включением и отключением правил

Каждое правило может быть включено или отключено с помощью свойства enabled:

const rule = {
  id: 'image-alt-required',
  enabled: false,
  context: 'img',
  check: function(node) {
    return { result: node.hasAttribute('alt') };
  }
};

Даже зарегистрированное правило не будет выполняться при enabled: false. Дополнительно, при вызове axe.run можно передавать объект rules, чтобы локально переопределить состояние конкретного правила:

axe.run(document, {
  rules: {
    'image-alt-required': { enabled: true }
  }
});

Теги и категории правил

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

  • wcag2a, wcag2aa, wcag2aaa
  • best-practice
  • experimental

Использование тегов упрощает фильтрацию и генерацию отчётов, а также интеграцию с CI/CD, когда требуется проверять только определённые категории доступности.

Использование кастомных правил в практике

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

axe.run(document).then(results => {
  results.violations.forEach(v => {
    console.log(`${v.id}: ${v.description}`);
  });
});

Кастомные правила появляются в списке violations и позволяют детально отслеживать нарушения, специфичные для проекта, включая нестандартные компоненты, собственные виджеты и динамически создаваемые элементы.

Особенности и рекомендации

  • Проверки должны быть максимально лёгкими и быстрыми, чтобы не замедлять анализ больших страниц.
  • Использование функций контекста даёт гибкость, но требует аккуратности при обходе DOM.
  • check можно расширять дополнительными полями, такими как any, all, none, для комплексной логики проверки.
  • Каждое правило должно иметь уникальный id и информативное help, чтобы его легко идентифицировать в отчётах.

Регистрация кастомных правил в Axe-core обеспечивает мощный инструмент для контроля доступности, позволяя адаптировать библиотеку под любые специфические требования проекта.

Оглавление