requiredOwnedElements

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

В aria-query роли определяются через карту roles, где каждая роль описывает свои ограничения, включая requiredProps, supportedProps, requiredContextRole и requiredOwnedElements. Атрибут requiredOwnedElements особенно важен для интерактивных и сложных компонентов, таких как menu, listbox, grid.

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

Элемент requiredOwnedElements имеет следующую типовую структуру:

{
  roleName: [
    {
      requiredElement: 'childRole',
      requiredElementContext: 'optionalContext',
      min: 1,
      max: null
    }
  ]
}

Пояснения к полям:

  • roleName — родительская ARIA-роль, для которой задаются обязательные дочерние элементы.
  • requiredElement — ARIA-роль дочернего элемента, которая обязательна для корректной структуры.
  • requiredElementContext — контекст, в котором должен находиться дочерний элемент; чаще всего соответствует родительской роли.
  • min — минимальное количество требуемых дочерних элементов.
  • max — максимальное количество требуемых дочерних элементов; null означает отсутствие верхней границы.

Пример из aria-query для роли list:

const listRequiredElements = {
  list: [
    { requiredElement: 'listitem', min: 1, max: null }
  ]
};

Это означает, что каждый элемент с ролью list должен содержать как минимум один элемент с ролью listitem. Если в DOM отсутствуют такие дочерние элементы, это нарушает требования ARIA.

Практическое использование валидации DOM

requiredOwnedElements используется для валидаторов и линтеров, которые проверяют соответствие структуры элементов ARIA. Например:

  1. Проверка минимального числа дочерних элементов.
  2. Проверка соответствия ролей дочерних элементов требованиям родителя.
  3. Контекстная проверка — дочерний элемент должен находиться в правильной роли-контейнере.

Пример функции для проверки DOM:

import { roles } from 'aria-query';

function validateRequiredChildren(elementRole, childrenRoles) {
  const requiredChildren = roles.get(elementRole)?.requiredOwnedElements || [];
  
  return requiredChildren.every(({ requiredElement, min }) => {
    const count = childrenRoles.filter(r => r === requiredElement).length;
    return count >= min;
  });
}

// Пример использования
const isValid = validateRequiredChildren('list', ['listitem', 'listitem']);
console.log(isValid); // true

Здесь мы извлекаем requiredOwnedElements для родительской роли и проверяем, что все обязательные дочерние роли присутствуют в DOM в нужном количестве.

Связь с другими свойствами ролей

requiredOwnedElements тесно взаимодействует с другими ключами aria-query:

  • requiredProps — свойства, которые должны присутствовать у родителя.
  • supportedProps — свойства, которые могут присутствовать, но не обязательны.
  • requiredContextRole — определяет роли контейнера, в которых может находиться элемент.

Это позволяет создавать комплексные правила валидации:

  • Контекстная проверка (родительская роль).
  • Проверка обязательных дочерних элементов.
  • Проверка обязательных свойств.

Частые паттерны использования

  1. Списки и элементы списка

    • list → listitem (минимум 1)
    • menu → menuitem или menuitemcheckbox/menuitemradio

  2. Таблицы и сетки

    • grid → row (минимум 1)
    • row → gridcell (минимум 1)

  3. Компоненты с комбинированной структурой

    • tablist → tab
    • tabpanel → любое количество элементов контента

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

Оптимизация и расширение

Для крупных проектов полезно строить карты зависимостей ролей, где requiredOwnedElements становится источником истинной структуры ARIA-компонентов. Это облегчает:

  • Автоматическую генерацию шаблонов компонентов.
  • Валидацию динамически создаваемого DOM.
  • Поддержку комплексных виджетов с множественными уровнями вложенности.

Можно создавать функции, которые на основе requiredOwnedElements генерируют DOM, соответствующий стандарту, или автоматически предупреждают разработчика при несоответствии ролей.

Оглавление