requiredContextRole

Библиотека aria-query представляет собой мощный инструмент для работы с ARIA-атрибутами и ролями в веб-приложениях. Она позволяет проверять соответствие элементов заявленным ролям, выявлять допустимые свойства и их значения, а также строить структурированные карты доступности интерфейсов. Основу работы составляют объекты roles и properties, которые предоставляют детальную информацию о поддерживаемых ролях и атрибутах.

Объект roles и его структура

roles — это карта ARIA-ролей, где ключами выступают строки с именами ролей, а значениями — объекты, описывающие их свойства:

import { roles } from 'aria-query';

console.log(roles.get('button'));

Каждая роль содержит следующие ключевые поля:

  • name: название роли.
  • requiredContextRole: массив ролей, которые должны присутствовать в родительских элементах, чтобы данная роль была валидной.
  • requiredProps: список обязательных атрибутов для корректного функционирования роли.
  • superClass: массив ролей-родителей, от которых наследуются свойства.
  • abstract: булевое значение, указывающее, является ли роль абстрактной (не может использоваться напрямую в разметке).

Пример структуры роли menuitem

const menuitemRole = roles.get('menuitem');

console.log(menuitemRole.requiredContextRole); // ['menu', 'menubar']
console.log(menuitemRole.requiredProps);       // []
console.log(menuitemRole.superClass);          // ['widget', 'command']

Свойство requiredContextRole

Ключевой особенностью aria-query является возможность проверки родительских контекстов через requiredContextRole. Оно описывает, какие роли должны присутствовать в иерархии DOM над элементом с данной ролью. Это критически важно для корректной работы вспомогательных технологий, таких как экранные читалки, поскольку неправильный контекст может нарушить доступность.

  • Если роль имеет несколько значений requiredContextRole, элемент корректен, если хотя бы один из контекстов присутствует.
  • Если массив пустой или отсутствует, контекст не является обязательным.

Пример проверки роли с контекстом

import { roles } from 'aria-query';

const menuitem = roles.get('menuitem');

console.log(menuitem.requiredContextRole.includes('menu')); // true
console.log(menuitem.requiredContextRole.includes('toolbar')); // false

В данном примере элемент с ролью menuitem корректен внутри menu или menubar, но не в toolbar.

Наследование ролей через superClass

Многие ARIA-роли наследуют свойства от родительских классов. Это позволяет объединять общие характеристики и упрощает проверку доступности. Например, роль button принадлежит к widget, что автоматически накладывает на нее ограничения и рекомендации для всех виджетов.

const buttonRole = roles.get('button');
console.log(buttonRole.superClass); // ['widget', 'command']

Использование aria-query для анализа DOM

Библиотека aria-query часто применяется совместно с инструментами тестирования, такими как eslint-plugin-jsx-a11y. Основная задача — сопоставить роль элемента с его контекстом и атрибутами. Алгоритм проверки:

  1. Получение роли элемента (role или implicit role на основе тега).
  2. Сравнение requiredContextRole с ролями родителей.
  3. Проверка обязательных атрибутов из requiredProps.
  4. Проверка наследования через superClass.
import { roles } from 'aria-query';

function isRoleContextValid(elementRole, parentRoles) {
  const roleData = roles.get(elementRole);
  if (!roleData || !roleData.requiredContextRole.length) return true;
  return roleData.requiredContextRole.some(r => parentRoles.includes(r));
}

console.log(isRoleContextValid('menuitem', ['menu'])); // true
console.log(isRoleContextValid('menuitem', ['toolbar'])); // false

Практическое значение requiredContextRole

requiredContextRole позволяет:

  • Автоматически выявлять ошибки доступности на этапе разработки.
  • Генерировать предупреждения при неправильной вложенности ролей.
  • Улучшать взаимодействие с вспомогательными технологиями.
  • Создавать корректные ARIA-виджеты и интерфейсы без визуальных изменений.

Итоговая структура данных роли

Каждая ARIA-роль в aria-query включает три ключевых направления:

  1. Контекст (requiredContextRole) — где роль может корректно использоваться.
  2. Обязательные атрибуты (requiredProps) — что должно быть задано для работы.
  3. Наследование (superClass) — общие характеристики и ограничения, унаследованные от родительских ролей.

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

Оглавление