Функция matches

Функция matches является ключевым инструментом для работы с результатами проверок доступности в библиотеке Axe-core. Она позволяет фильтровать и анализировать элементы DOM, которые соответствуют определённым критериям, определённым правилами тестирования доступности.

Назначение и основные возможности

Основная цель matches — определить, какие узлы DOM соответствуют определённой проверке доступности. Она используется внутри движка Axe-core для:

  • Фильтрации элементов по селекторам или условиям.
  • Определения, к каким элементам применимы конкретные правила.
  • Повышения точности отчетов о нарушениях доступности.

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

Синтаксис

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

axe.matches(context, options)

Где:

  • context — узел DOM или массив узлов, к которым применяется проверка. Может быть document, document.body, конкретный HTMLElement или NodeList.

  • options — объект с параметрами фильтрации, которые определяют правила соответствия элементов. Основные свойства:

    • selector — CSS-селектор, для фильтрации элементов.
    • label — фильтрация по текстовым меткам или атрибутам.
    • visible — булево значение, определяющее, учитывать ли только видимые элементы.
    • ignore — селекторы, которые необходимо исключить из проверки.

Функция возвращает массив узлов, соответствующих указанным условиям.

Примеры использования

Фильтрация всех видимых кнопок на странице:

const visibleButtons = axe.matches(document.body, {
  selector: 'button',
  visible: true
});
console.log(visibleButtons); // массив HTMLButtonElement

Исключение определённых элементов:

const inputs = axe.matches(document, {
  selector: 'input',
  ignore: '.ignore-accessibility'
});

В этом случае все элементы с классом ignore-accessibility не попадут в массив результатов.

Использование с правилами Axe-core

Каждое правило Axe-core может определять собственный контекст для проверки. Внутри этих правил matches применяется для фильтрации элементов, к которым будет применена проверка. Пример для правила проверки контраста текста:

const textElements = axe.matches(document.body, {
  selector: 'p, span',
  visible: true
});

textElements.forEach(node => {
  // Применение логики проверки контраста
});

Это позволяет локализовать проверку только на релевантных узлах, избегая лишних вычислений и ложных срабатываний.

Особенности и подводные камни

  1. Контекст имеет значение Если context не задан, по умолчанию используется весь документ. В больших приложениях это может привести к падению производительности, поэтому рекомендуется явно указывать контейнер.

  2. Фильтрация видимости Опция visible учитывает CSS-свойства display: none, visibility: hidden и размеры элемента. Элементы с нулевыми размерами не считаются видимыми.

  3. Селекторы и приоритетность Если указаны одновременно selector и ignore, сначала выбираются все узлы по selector, затем из них исключаются узлы по ignore.

  4. Массовые проверки При работе с NodeList или массивами элементов matches корректно обрабатывает вложенные структуры, возвращая только те узлы, которые полностью удовлетворяют критериям.

Расширенное использование

Для сложных сценариев можно использовать matches с динамическими условиями:

const customMatch = axe.matches(document.body, {
  selector: 'div, section',
  visible: true
}).filter(node => node.getAttribute('role') === 'region');

Здесь комбинируется базовая фильтрация Axe-core и кастомная логика на уровне JavaScript.

Взаимодействие с другими функциями Axe-core

  • querySelectorAll vs matches: обычный querySelectorAll возвращает все элементы по селектору, независимо от видимости и игнор-листов. matches применяет правила Axe-core, что делает его более безопасным для анализа доступности.
  • Совместимость с run: результаты matches могут использоваться как входной контекст для axe.run(), чтобы ограничить проверку только релевантными элементами.
const context = axe.matches(document.body, { selector: 'main', visible: true });
axe.run(context).then(results => {
  console.log(results.violations);
});

Резюме по функциональности

  • Фильтрует элементы по CSS-селекторам, видимости и пользовательским правилам.
  • Исключает нежелательные элементы с помощью ignore.
  • Улучшает точность проверок доступности, избегая ложных срабатываний.
  • Может быть использована в сочетании с другими методами Axe-core для оптимизации тестирования.

Функция matches — это основа для точного и эффективного анализа DOM в контексте доступности, предоставляя разработчикам гибкие возможности фильтрации и кастомизации проверок.

Оглавление