Конфигурация и опции

Библиотека ally.js предназначена для улучшения доступности веб-приложений, предоставляя инструменты для управления фокусом, обнаружения и обработки элементов интерфейса. Центральным элементом работы с библиотекой является её система конфигурации, которая позволяет гибко настраивать поведение функций, соответствующих требованиям конкретного проекта.

Конфигурация в ally.js строится вокруг объектов опций, передаваемых в методы библиотеки. Каждый метод имеет набор предопределённых настроек, которые могут быть изменены для контроля логики обхода DOM, управления фокусом и определения видимости элементов.

Конфигурационные объекты и их структура

Конфигурация представляет собой обычный JavaScript-объект. Пример базовой структуры:

const options = {
  context: document,       // Контекст поиска элементов
  includeContext: false,   // Включать ли сам контекст в результаты
  filter: null,            // Функция фильтрации элементов
  strategy: 'strict',      // Стратегия обхода DOM
};
  • context — элемент, внутри которого будут выполняться операции поиска или управления фокусом. Обычно это document или конкретный контейнер.
  • includeContext — булевое значение, указывающее, следует ли включать сам контекст в результаты поиска.
  • filter — функция обратного вызова, позволяющая дополнительно отфильтровать элементы. Принимает DOM-элемент и возвращает true, если элемент нужно включить.
  • strategy — определяет способ обхода DOM. Доступны варианты: strict (только элементы, полностью видимые и доступные) и all (включает скрытые или неактивные элементы).

Настройка стратегии фокусировки

ally.js предоставляет несколько подходов к определению того, какие элементы могут получать фокус. Основные параметры:

  • tabindex — учитывается ли атрибут tabindex при обходе элементов.
  • focusable — функция или булев флаг, определяющий, является ли элемент фокусируемым. По умолчанию библиотека использует встроенные правила HTML и ARIA.
  • includeOnlyTabbable — включает в результаты только элементы, которые реально могут быть достигнуты при навигации с клавиатуры.

Пример конфигурации для метода получения всех фокусируемых элементов:

const focusableOptions = {
  context: document.body,
  includeOnlyTabbable: true,
  strategy: 'strict',
  filter: function(element) {
    return !element.classList.contains('no-focus');
  }
};

Управление видимостью и доступностью

Функции ally.js учитывают видимость элементов и их доступность для пользователей с ограничениями. Ключевые опции:

  • visible — определяет, учитывать ли скрытые элементы. Значения: true (только видимые), false (все элементы), 'strict' (исключает элементы с opacity:0 или display:none).
  • ignoreScroll — игнорировать ли элементы, которые находятся за пределами области видимости (scrollable контейнеров).
  • ignoreOpacity — игнорировать ли элементы с прозрачностью 0 при выборе фокусируемых элементов.

Пример использования:

const visibleOptions = {
  context: document.querySelector('#app'),
  visible: 'strict',
  ignoreScroll: true
};

Расширенные фильтры и кастомизация

Фильтры предоставляют максимальную гибкость при конфигурации:

  • Фильтры могут быть функциями, принимающими элемент и возвращающими true или false.
  • Можно объединять несколько фильтров, используя логические операции.
  • Допускается использование атрибутов ARIA, классов CSS, состояния элементов (disabled, hidden) для фильтрации.

Пример комбинированного фильтра:

function customFilter(element) {
  return element.offsetParent !== null && !element.hasAttribute('aria-hidden');
}

const optionsWithFilter = {
  context: document.body,
  filter: customFilter
};

Конфигурация событий

Некоторые методы ally.js, связанные с динамическим управлением фокусом и доступностью, поддерживают параметры событий:

  • bind — элемент, на который навешиваются обработчики событий.
  • event — тип события (focus, blur, keydown и т.д.).
  • callback — функция, выполняемая при наступлении события, с передачей объекта события и текущего элемента.

Пример настройки наблюдателя за фокусом:

ally.on.focus(function(event, element) {
  console.log('Фокус на элементе:', element);
}, { context: document.body });

Глобальные и локальные настройки

  • Глобальные настройки задаются при инициализации библиотеки и применяются ко всем методам по умолчанию.
  • Локальные настройки передаются непосредственно в метод и переопределяют глобальные параметры для конкретного вызова.

Пример глобальной конфигурации:

ally.defaults = {
  strategy: 'strict',
  includeContext: false,
  visible: true
};

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

  • Всегда задавать context явно, чтобы избежать непредсказуемого поиска по всему документу.
  • Использовать фильтры для исключения элементов с динамическими состояниями, например скрытых модальных окон.
  • Комбинировать опции видимости, чтобы корректно работать с элементами за пределами области прокрутки.
  • Глобальные настройки следует применять только при единообразной политике доступности на всех страницах приложения.

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

Оглавление