Добавление кастомных ролей

Библиотека Aria-query предназначена для работы с ARIA-ролью, свойствами и состояниями в DOM. Она предоставляет структурированные данные о доступности элементов, что позволяет создавать тесты, утилиты и компоненты с корректной семантикой.

Aria-query хранит информацию в виде таблиц ролей, атрибутов и состояний. Основные функции включают:

  • Получение списка всех стандартных ARIA-ролей.
  • Определение свойств и состояний конкретной роли.
  • Проверку соответствия HTML-элементов допустимым ARIA-атрибутам.

Использование библиотеки упрощает интеграцию кастомной доступности в React, Vue или Vanilla JS-приложения.

Структура данных в Aria-query

Aria-query использует несколько ключевых структур:

  1. RolesMap Объект, где ключ — имя роли (string), а значение — объект с информацией:

    • name: формула получения имени роли.
    • attributes: массив поддерживаемых ARIA-атрибутов.
    • abstract: булевое значение, указывающее на абстрактную роль.
    • superClass: массив, описывающий иерархию наследования ролей.

  2. ElementRolesMap Определяет соответствие HTML-тегов и ARIA-ролей. Пример: div → region, button → button.

  3. AttributesMap Содержит все стандартные ARIA-атрибуты с типами и допустимыми значениями:

    • aria-label: string
    • aria-hidden: true | false
    • aria-expanded: true | false | undefined

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

Добавление кастомных ролей

Добавление новой роли в Aria-query требует аккуратной работы с RolesMap. Основная цель — сохранить совместимость с API библиотеки и стандартами WAI-ARIA.

Пример структуры кастомной роли:

import { roles } from 'aria-query';

const customRole = {
  name: 'custom-widget',
  abstract: false,
  superClass: [['widget']],
  attributes: new Map([
    ['aria-label', { type: 'string' }],
    ['aria-checked', { type: 'boolean' }],
  ]),
};

// Добавление роли в RolesMap
roles.set('custom-widget', customRole);

Объяснение ключевых полей:

  • name — уникальный идентификатор роли. Он будет использоваться для проверки соответствия элементов.
  • abstract — если значение true, роль нельзя назначать элементам напрямую, она используется как родительская в иерархии.
  • superClass — массив массивов, задающий наследование. В примере custom-widget наследует поведение стандартной роли widget.
  • attributes — Map с ARIA-атрибутами и их типами. Для расширения поддерживаемых свойств можно добавлять новые пары ключ-значение.

Проверка и валидация кастомных ролей

После добавления кастомной роли важно убедиться, что она корректно интегрируется с существующими инструментами:

const testRole = roles.get('custom-widget');
console.log(testRole.superClass); // [['widget']]
console.log(testRole.attributes.has('aria-label')); // true

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


  Контент виджета

Наследование и переопределение атрибутов

Ключевой момент — кастомная роль может наследовать атрибуты родительской роли. В superClass указывается родитель, а затем атрибуты можно добавлять или переопределять.

Пример расширения существующей роли:

const baseWidget = roles.get('widget');

const extendedWidget = {
  ...baseWidget,
  name: 'extended-widget',
  attributes: new Map([...baseWidget.attributes, ['aria-custom', { type: 'string' }]]),
};

roles.set('extended-widget', extendedWidget);

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

Практические рекомендации

  • Всегда использовать уникальные имена ролей, чтобы избежать конфликтов с стандартными ARIA.
  • Атрибуты должны иметь точные типы (string, boolean, token), иначе возможны ошибки в валидации.
  • Использовать abstract: true для базовых ролей, которые не назначаются элементам напрямую.
  • При наследовании проверять наличие родительских атрибутов, чтобы не дублировать их без необходимости.
  • Тестировать кастомные роли через инструменты проверки доступности (например, axe-core) для совместимости с экранами чтения.
Оглавление