Объекты include и exclude

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

Основные принципы работы

  • include — определяет элементы, которые будут включены в проверку.
  • exclude — определяет элементы, которые будут исключены из проверки.

Эти объекты принимают массивы CSS-селекторов, DOM-элементов или массивы комбинаций селекторов и элементов.

Важно: если include не указан, Axe-core по умолчанию проверяет весь DOM страницы. Если указан exclude, все элементы из этого списка будут пропущены, даже если они попадают под include.

Синтаксис объектов

const options = {
  runOnly: {
    type: 'tag',
    values: ['wcag2a', 'wcag2aa']
  },
  include: [['#main-content'], document.querySelector('.important-section')],
  exclude: ['.ads', '#hidden-section']
};

  • include может содержать:

    • CSS-селекторы ('#main-content', '.important-section')
    • DOM-элементы (document.querySelector('.header'))
    • Массивы селекторов и элементов для группового включения

  • exclude поддерживает:

    • CSS-селекторы
    • DOM-элементы
    • Их комбинации

Важные нюансы использования

  1. Приоритеты включения и исключения Если один элемент находится в include и одновременно в exclude, исключение имеет приоритет. Это позволяет точно отсеивать нежелательные области.

  2. Вложенные элементы Axe-core проверяет всех потомков включённых элементов, если они не находятся в exclude. Это упрощает работу с крупными контейнерами.

  3. Динамические страницы При работе с SPA или элементами, подгружаемыми через AJAX, объекты include и exclude должны ссылаться на элементы, существующие в момент вызова axe.run(). Иначе они будут проигнорированы.

  4. Использование с context В последних версиях Axe-core можно передавать объект context, который сочетает include и exclude:

const context = {
  include: ['#content', '.article'],
  exclude: ['.ad-banner', '.popup']
};

axe.run(context, options).then(results => {
  console.log(results.violations);
});

Примеры практического применения

  • Изоляция основной статьи на странице с боковыми панелями:
axe.run({
  include: ['.article-body'],
  exclude: ['.sidebar', '.newsletter']
});
  • Проверка только модальных окон:
const modal = document.querySelector('#login-modal');
axe.run({ include: [modal] });
  • Исключение сторонних виджетов:
axe.run({
  exclude: ['.third-party-widget', '.tracking-banner']
});

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

  • Неправильный селектор Если указанный CSS-селектор не соответствует ни одному элементу, он игнорируется. Проверка не выдаст ошибку, но этот участок DOM останется не проверенным.

  • Смешение DOM-элементов и селекторов Axe-core корректно обрабатывает оба варианта, но массив должен быть плоским. Вложенные массивы могут привести к некорректной работе.

  • Асинхронная подгрузка контента В SPA часто необходимо вызывать axe.run() после полной загрузки контента, иначе элементы из include могут отсутствовать в DOM.

Рекомендации по структурированию include и exclude

  • Всегда включать только те элементы, которые необходимо проверить, чтобы снизить время анализа.
  • Исключать динамические или сторонние виджеты, которые генерируют ложные нарушения.
  • Использовать DOM-элементы вместо селекторов для более точного контроля, если селекторы могут совпадать с множеством элементов.

Итоговое понимание

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

  • Сократить время выполнения тестов
  • Исключить ложные срабатывания
  • Сконцентрироваться на критически важных участках интерфейса

Эффективная комбинация этих объектов обеспечивает высокую точность и предсказуемость анализа доступности на страницах любой сложности.

Оглавление