requireContextRole

Библиотека Aria-query предназначена для работы с ARIA-атрибутами и ролями в DOM, обеспечивая соответствие стандартам доступности (accessibility). Одним из ключевых инструментов для проверки совместимости ролей и контекста является функция requireContextRole. Она позволяет определить, какие родительские роли необходимы для корректного использования конкретной роли ARIA.

Основные понятия

Роль (role) — это атрибут ARIA, который описывает назначение элемента интерфейса. Контекст (context) — структура DOM, где элемент с определённой ролью может корректно использоваться. Некоторые роли требуют, чтобы их родительские элементы имели определённые роли для обеспечения правильного взаимодействия с ассистивными технологиями.

Функция requireContextRole отвечает за проверку этих требований и возвращает список ролей, которые являются допустимыми родителями для конкретной роли.

Импорт и подключение

Для использования функции необходимо импортировать соответствующий модуль из Aria-query:

const { requireContextRole } = require('aria-query');

Модуль поставляется вместе с базой данных ролей и их зависимостей, что позволяет работать с актуальной информацией из спецификации WAI-ARIA.

Синтаксис функции

requireContextRole(roleName: string): Set<string> | null
  • roleName — строка, имя ARIA-роли, для которой необходимо определить допустимый контекст.
  • Возвращаемое значение — множество (Set) допустимых ролей родителя. Если контекст не требуется, возвращается null.

Пример:

const allowedParents = requireContextRole('listitem');
console.log(allowedParents); // Set { 'list', 'menu', 'group' }

Здесь видно, что элемент с ролью listitem корректно может находиться внутри list, menu или group.

Практическое использование

Валидация структуры DOM

Основное применение requireContextRole — проверка правильности структуры DOM при динамическом рендеринге компонентов. Например, в React или Vue можно создавать функцию валидации:

function validateRoleContext(element, parentRole) {
  const allowedParents = requireContextRole(element.role);
  if (allowedParents && !allowedParents.has(parentRole)) {
    console.warn(
      `Роль ${element.role} не должна находиться внутри ${parentRole}`
    );
  }
}

// Пример проверки
validateRoleContext({ role: 'listitem' }, 'table'); 
// Выведет предупреждение, так как 'table' не входит в Set допустимых родителей

Генерация документации

При создании UI-библиотек можно автоматически генерировать рекомендации по использованию ролей. Функция requireContextRole позволяет получить полный список подходящих родительских ролей для каждой роли ARIA.

const roles = ['button', 'menuitem', 'option'];
roles.forEach(role => {
  console.log(`${role} может находиться в:`, requireContextRole(role));
});

Работа с множественными контекстами

Некоторые роли поддерживают несколько вариантов контекста. requireContextRole возвращает все допустимые роли в виде множества. Это удобно для компонентов с вариативной структурой:

const contexts = requireContextRole('option');
contexts.forEach(contextRole => {
  console.log(`Option может находиться в ${contextRole}`);
});

Пример вывода: listbox, menu, tree.

Особенности и ограничения

  • Если роль может находиться в любом месте, возвращается null. Это сигнализирует о том, что контекст не обязателен.
  • Роль должна существовать в спецификации ARIA. Для неизвестной роли функция возвращает null.
  • Множество возвращаемых ролей не гарантирует, что все элементы в DOM будут корректны с точки зрения всех аспектов доступности. Оно определяет только требуемый родительский контекст.

Совмещение с другими модулями Aria-query

Для комплексной проверки доступности рекомендуется использовать requireContextRole вместе с:

  • roles — для получения полной информации о роли, её свойствах и поддерживаемых атрибутах.
  • elementRoles — для сопоставления HTML-элементов с ARIA-ролями.
  • roleSchemas — для проверки допустимых дочерних ролей и структур.

Пример:

const { roles, elementRoles } = require('aria-query');

const roleInfo = roles.get('listitem');
console.log('Дочерние роли:', roleInfo.childRoles);
console.log('Допустимые родители:', requireContextRole('listitem'));

const htmlElement = elementRoles.get('li');
console.log('Роли для <li>:', htmlElement);

Итоговые рекомендации по использованию

  • requireContextRole идеально подходит для статической и динамической валидации компонентов UI.
  • В сочетании с roles и elementRoles можно строить автоматические проверки доступности.
  • Использование множества Set позволяет легко интегрировать функцию в условные проверки или логирование предупреждений.

Функция requireContextRole является ключевым инструментом для соблюдения стандартов ARIA и гарантирует, что элементы интерфейса будут корректно восприниматься ассистивными технологиями. Она делает разработку доступного UI более безопасной и предсказуемой.

Оглавление