requiredProps

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

Определение requiredProps

requiredProps — это объект, в котором каждой роли ARIA соответствует массив обязательных атрибутов, необходимых для корректного функционирования этой роли в DOM.

Пример структуры:

import { roles } from 'aria-query';

const buttonRequiredProps = roles.get('button').requiredProps;
console.log(buttonRequiredProps); // { type: 'button' }

В этом примере видно, что для роли button требуется атрибут type, значение которого по умолчанию должно быть 'button'. Если этот атрибут отсутствует, элемент не полностью соответствует спецификации ARIA.

Доступ к requiredProps

Для получения обязательных свойств используются объекты roles или elements из Aria-query.

  1. Использование через roles
import { roles } from 'aria-query';

const checkboxProps = roles.get('checkbox').requiredProps;
console.log(checkboxProps);
// { 'aria-checked': true/false/mixed }

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

  1. Использование через elements

Для элементов HTML можно получить связанные роли и их обязательные свойства:

import { elements } from 'aria-query';

const buttonElement = elements.get('button');
console.log(buttonElement.roles);
// Map { 'button' => { requiredProps: { type: 'button' } } }

В этом случае elements.get('button') возвращает информацию о ролях, которые могут быть назначены элементу <button>, и их обязательных свойствах.

Структура данных requiredProps

Объект requiredProps имеет следующую типовую структуру:

{
  [attributeName]: expectedValue
}
  • attributeName — имя обязательного ARIA-атрибута или стандартного HTML-атрибута.
  • expectedValue — значение, которое должно присутствовать, либо массив допустимых значений.

Примеры:

roles.get('checkbox').requiredProps
// { 'aria-checked': ['true', 'false', 'mixed'] }

roles.get('link').requiredProps
// {} — роль link не требует обязательных свойств

Некоторые роли не имеют обязательных атрибутов, в таком случае requiredProps возвращает пустой объект.

Применение requiredProps для проверки доступности

С помощью requiredProps можно создавать функции для валидирования разметки:

function validateRoleProps(element, roleName) {
  const role = roles.get(roleName);
  if (!role) return false;

  const requiredProps = role.requiredProps;
  for (const [prop, value] of Object.entries(requiredProps)) {
    if (!(prop in element) || (Array.isArray(value) && !value.includes(element[prop]))) {
      return false;
    }
  }
  return true;
}

// Пример использования
const checkboxElement = { 'aria-checked': 'true' };
console.log(validateRoleProps(checkboxElement, 'checkbox')); // true

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

Отличия requiredProps для различных ролей

Разные роли ARIA требуют разных наборов обязательных атрибутов:

Роль Обязательные свойства
button type
checkbox aria-checked
radio aria-checked
slider aria-valuemin, aria-valuemax, aria-valuenow
tab aria-selected
option aria-selected

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

Практическая интеграция в библиотеки и тесты

requiredProps часто используется в связке с тестовыми фреймворками для UI, например:

import { render } from '@testing-library/react';
import { roles } from 'aria-query';
import MyButton from './MyButton';

test('Button имеет обязательный тип', () => {
  const { getByRole } = render(<MyButton />);
  const button = getByRole('button');
  const required = roles.get('button').requiredProps;

  for (const [prop, value] of Object.entries(required)) {
    expect(button[prop]).toBe(value);
  }
});

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

Выводы о requiredProps

  • Объект requiredProps описывает обязательные свойства каждой ARIA-ролии.
  • Позволяет проверять соответствие элементов спецификации доступности.
  • Используется как для анализа стандартных HTML-элементов, так и для кастомных компонентов с ARIA-ролями.
  • Обеспечивает основу для автоматических тестов и динамического контроля интерфейса.

Использование requiredProps делает код более надёжным и доступным, снижая риск ошибок при работе с ARIA-атрибутами.

Оглавление