Поддержка legacy-кода

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

aria-query экспортирует два основных набора данных:

  • Roles — объект с описанием всех стандартных ARIA-ролей, их разрешённых дочерних ролей и свойств.
  • Attributes — объект с атрибутами ARIA и их допустимыми значениями.

Каждая роль хранится в виде ключа с объектом, который содержит:

  • abstract — булевое значение, указывающее, является ли роль абстрактной.
  • baseConcepts — массив, описывающий элементы HTML и их свойства, соответствующие роли.
  • allowedProps — список свойств ARIA, допустимых для роли.
  • requiredProps — свойства, обязательные для корректной работы роли.
  • childrenPresentational — флаг, указывающий, что дочерние элементы не должны влиять на доступность.
  • requiredContextRole — роль родителя, необходимая для корректного использования.
  • superClass — массив с предками роли для наследования свойств.

Использование roles для валидации

Простейший пример применения — проверка, допустимо ли использовать определённую роль для элемента:

import { roles } from 'aria-query';

const buttonRole = roles.get('button');

console.log(buttonRole.allowedProps.has('aria-pressed')); // true
console.log(buttonRole.requiredProps); // Set {} если нет обязательных свойств

Здесь roles.get('button') возвращает объект с полной информацией о роли button. С помощью allowedProps можно определить, какие атрибуты можно применять к элементу, а requiredProps позволяет убедиться в наличии обязательных ARIA-свойств.

Attributes и их назначение

Объект Attributes предоставляет полное описание ARIA-атрибутов:

  • Тип значения — строка, булевое значение или перечисление допустимых вариантов.
  • Множественность — поддержка списков значений через true/false или массивы.
  • Состояния и свойства — различие между состояниями (dynamic, mutable) и статическими свойствами.

Пример проверки допустимого значения атрибута:

import { attributes } from 'aria-query';

const ariaChecked = attributes.get('aria-checked');

console.log(ariaChecked.valueSet); // ['true', 'false', 'mixed', undefined]

Работа с legacy-кодом

При интеграции aria-query в существующие проекты важно учитывать несколько аспектов:

  1. Старые теги и роли Некоторые legacy-компоненты используют устаревшие ARIA-атрибуты или нестандартные роли. Библиотека позволяет:

    • Определять соответствие между устаревшими HTML-атрибутами и актуальными ARIA-ролями.
    • Автоматически игнорировать абстрактные роли, которые не должны напрямую применяться к элементам.

  2. Проверка контекста Старый код часто не учитывает требуемую иерархию ролей. Использование requiredContextRole помогает выявить потенциальные ошибки:

const listItemRole = roles.get('listitem');
console.log(listItemRole.requiredContextRole); // Set { 'list', 'group', 'menu' }

Это позволяет построить автоматические скрипты для проверки соответствия DOM иерархии ARIA-ролей.

  1. Валидация динамических компонентов Для legacy-приложений с динамическими изменениями DOM важно проверять актуальность ARIA-атрибутов в реальном времени. Можно создать утилиту, которая проходит по всем элементам и сверяет их роли и атрибуты с базой aria-query.

Оптимизация работы с данными

aria-query использует структуры Map и Set, что позволяет:

  • Быструю проверку наличия роли или атрибута (roles.has('button'))
  • Эффективную фильтрацию допустимых свойств (allowedProps.has('aria-label'))
  • Лёгкое объединение множеств для наследуемых ролей (superClass)

Пример объединения свойств родительской и дочерней роли:

const menuRole = roles.get('menu');
const menuItemRole = roles.get('menuitem');

const inheritedProps = new Set([
  ...menuRole.allowedProps,
  ...menuItemRole.allowedProps
]);

console.log(inheritedProps.has('aria-disabled')); // true

Интеграция с тестами

Для поддержки legacy-кода полезно использовать aria-query вместе с тестовыми фреймворками:

  • Jest или Mocha для unit-тестов ролей и атрибутов
  • Автоматическая генерация отчётов о некорректных ARIA-свойствах
  • Валидация после обновления старых компонентов на новые версии библиотеки UI

Пример теста роли:

import { roles } from 'aria-query';

test('role button поддерживает aria-pressed', () => {
  const buttonRole = roles.get('button');
  expect(buttonRole.allowedProps.has('aria-pressed')).toBe(true);
});

Резюме по работе с legacy-кодом

  • Проверка соответствия ролей и атрибутов с помощью roles и attributes.
  • Игнорирование абстрактных и устаревших ролей для сохранения корректности.
  • Учет контекста родительских элементов через requiredContextRole.
  • Использование структур Map и Set для эффективной валидации и объединения свойств.
  • Интеграция с тестами для автоматической проверки старых компонентов.

Такая системная работа с aria-query позволяет постепенно приводить legacy-код к современным стандартам доступности без полной переписки приложения.

Оглавление