ARIAPropertyDefinition

Библиотека aria-query представляет собой набор инструментов для работы с спецификацией ARIA (Accessible Rich Internet Applications) в среде JavaScript. Она используется для валидации и анализа ARIA-атрибутов, проверки их соответствия спецификации и построения доступных компонентов пользовательского интерфейса. Ключевым элементом структуры библиотеки является ARIAPropertyDefinition, определяющий свойства ARIA-атрибутов и их допустимые значения.

Структура ARIAPropertyDefinition

Объект ARIAPropertyDefinition описывает отдельное свойство ARIA через следующие поля:

  • name — строка, имя атрибута, например aria-label или aria-checked.

  • type — тип значения свойства. Возможные типы:

    • "string" — произвольная строка;
    • "boolean" — логическое значение true или false;
    • "tristate" — логическое значение с опцией mixed для частично выбранных состояний;
    • "token" — строка с ограниченным набором допустимых значений;
    • "idref" — ссылка на идентификатор другого элемента в DOM;
    • "idref_list" — список идентификаторов через пробел;
    • "integer" — целое число;
    • "number" — число с плавающей точкой;
    • "token_list" — список токенов через пробел, каждый из которых должен соответствовать разрешённым значениям.

  • values — массив допустимых значений, используется для типов token и token_list.

  • allowUndefined — булевое значение, определяющее, разрешено ли отсутствие атрибута.

  • defaultValue — значение по умолчанию, которое считается установленным, если атрибут отсутствует в DOM.

  • requiredParentRole — массив ролей ARIA, в которых это свойство допустимо. Например, aria-checked корректен только в элементах с ролью checkbox или menuitemcheckbox.

  • implicitValue — значение, которое считается установленным по умолчанию, если оно не явно указано, может отличаться от defaultValue.

Пример структуры объекта:

{
  name: 'aria-checked',
  type: 'tristate',
  values: ['true', 'false', 'mixed'],
  allowUndefined: true,
  defaultValue: 'false',
  requiredParentRole: ['checkbox', 'menuitemcheckbox'],
  implicitValue: undefined
}

Типы значений и их проверка

1. Логические значения (boolean)

Используются для атрибутов, которые могут принимать только true или false. Проверка осуществляется через строгое сравнение с этими строковыми литералами.

2. Тристейт (tristate)

Поддерживает три состояния: true, false и mixed. Типично используется для чекбоксов с частично выбранными элементами в группе.

3. Токены (token) и списки токенов (token_list)

  • token — единственное значение из ограниченного набора.
  • token_list — несколько значений через пробел, каждое из которых должно быть допустимым.

Пример проверки значения:

const definition = {
  name: 'aria-orientation',
  type: 'token',
  values: ['horizontal', 'vertical']
};

function isValidToken(value, def) {
  return def.values.includes(value);
}

isValidToken('vertical', definition); // true
isValidToken('diagonal', definition); // false

4. Ссылки на идентификаторы (idref и idref_list)

  • idref — ссылка на единственный элемент DOM через его id.
  • idref_list — список идентификаторов, разделённых пробелами.

Проверка корректности idref требует поиска элемента в документе:

function validateIdref(id) {
  return document.getElementById(id) !== null;
}

5. Числовые значения (integer, number)

Поддерживаются целые и дробные числа. Проверка выполняется через стандартные функции Number.isInteger() или parseFloat().

Связь ARIAPropertyDefinition с ролями

Каждое свойство ARIA может быть валидным только для определённых ролей. Поле requiredParentRole позволяет описать эти зависимости. Например:

{
  name: 'aria-checked',
  requiredParentRole: ['checkbox', 'menuitemcheckbox']
}

При анализе DOM библиотека может проверять соответствие:

function validateRole(element, propertyDef) {
  return propertyDef.requiredParentRole.includes(element.getAttribute('role'));
}

Использование ARIAPropertyDefinition в библиотеке

Библиотека aria-query предоставляет несколько объектов, основанных на ARIAPropertyDefinition:

  • ariaAttributes — карта всех ARIA-атрибутов с их определениями.
  • roles — карта ARIA-ролей и их допустимых свойств.
  • getPropertyValues — функция для извлечения допустимых значений конкретного свойства.

Пример получения всех возможных значений атрибута aria-checked:

const { ariaAttributes } = require('aria-query');
const checkedDef = ariaAttributes.get('aria-checked');
console.log(checkedDef.values); // ['true', 'false', 'mixed']

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

Работа с библиотекой в проекте

  1. Установка через npm:
npm install aria-query
  1. Импорт и использование в Node.js или современных сборщиках:
const { ariaAttributes, roles } = require('aria-query');

// Проверка свойства
const propDef = ariaAttributes.get('aria-expanded');
console.log(propDef.type); // 'boolean'
  1. Проверка соответствия роли и атрибута:
function isAttributeValidForRole(attribute, role) {
  const propDef = ariaAttributes.get(attribute);
  return propDef.requiredParentRole.includes(role);
}

Ключевые преимущества подхода через ARIAPropertyDefinition

  • Централизованная спецификация — все атрибуты ARIA определены в виде объектов с типами и допустимыми значениями.
  • Автоматическая валидация — библиотека позволяет проверять атрибуты на соответствие спецификации.
  • Гибкость и расширяемость — легко добавлять кастомные проверки или новые свойства.
  • Совместимость с ролями — свойства привязаны к допустимым ролям, предотвращая ошибочное использование.

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

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

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

Оглавление