Полный список методов ally.maintain

Библиотека ally.js предназначена для управления доступностью веб-приложений и поддержания правильного фокуса, взаимодействия с элементами и ARIA-состояниями. Модуль ally.maintain используется для поддержания состояния элементов в DOM, включая фокус, видимость, управление скроллом и отключение взаимодействий.

Основные возможности ally.maintain

Модуль ally.maintain предоставляет методы, которые позволяют:

  • Сохранять фокус на определенном элементе при взаимодействии с интерфейсом.
  • Ограничивать фокус внутри контейнера (focus trap).
  • Управлять видимостью элементов для скринридеров и пользователей клавиатуры.
  • Деактивировать элементы без удаления из DOM.
  • Автоматически восстанавливать состояния после взаимодействия.

Все методы возвращают объект с контролем отмены (disengage), который позволяет корректно завершить поддержание состояния.

Методы ally.maintain

1. maintain.focus

Метод предназначен для поддержания фокуса на элементе или в контейнере.

Синтаксис:

ally.maintain.focus(element, options)

Параметры:

  • element — DOM-элемент, на котором нужно зафиксировать фокус.

  • options — объект с настройками:

    • ignoreKeys — массив клавиш, которые не будут прерывать фокус.
    • context — DOM-контейнер, внутри которого работает поддержание.
    • trap — boolean, если true, фокус будет ограничен внутри контейнера (focus trap).

Возвращает: объект с методом disengage(), который снимает поддержку фокуса.

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

const focusMaintainer = ally.maintain.focus(modal, { trap: true });

// Позже можно отключить
focusMaintainer.disengage();

2. maintain.tabFocus

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

Синтаксис:

ally.maintain.tabFocus(container)
  • container — DOM-элемент, внутри которого необходимо замкнуть фокус.
  • Автоматически предотвращает выход фокуса за пределы контейнера.
  • Работает с клавишей Tab и Shift+Tab.

Возвращает: объект с disengage().

Пример:

const tabTrap = ally.maintain.tabFocus(modalContent);
tabTrap.disengage();

3. maintain.hidden

Метод позволяет скрывать элементы от клавиатурной навигации и скринридеров, не удаляя их из DOM.

Синтаксис:

ally.maintain.hidden(element)

Особенности:

  • Добавляет aria-hidden="true" и tabindex="-1".
  • Поддерживает восстановление исходного состояния.
  • Полезно для управления видимостью модальных слоев или выпадающих меню.

Пример:

const hiddenMaintainer = ally.maintain.hidden(sidebar);
hiddenMaintainer.disengage(); // восстанавливает видимость

4. maintain.disabled

Позволяет временно отключать элементы без удаления их из DOM.

Синтаксис:

ally.maintain.disabled(element)

Действия метода:

  • Добавляет disabled атрибут для кнопок, input, select.
  • Устанавливает aria-disabled="true" для совместимости со скринридерами.
  • Блокирует любые события взаимодействия.

Пример:

const disableMaintainer = ally.maintain.disabled(button);
disableMaintainer.disengage(); // возвращает кнопку в активное состояние

5. maintain.scroll

Метод удерживает прокрутку на определенном элементе, предотвращая нежелательное перемещение при модальных диалогах.

Синтаксис:

ally.maintain.scroll(element)

Особенности:

  • Блокирует прокрутку родительских контейнеров.
  • Работает в сочетании с фокус-ловушками.
  • Важен для модальных окон, полноэкранных слоев и боковых панелей.

Пример:

const scrollMaintainer = ally.maintain.scroll(modalContainer);
scrollMaintainer.disengage();

6. maintain.inert

Метод делает контейнер неинтерактивным для всех вложенных элементов.

Синтаксис:

ally.maintain.inert(container)

Действия:

  • Устанавливает aria-hidden="true" и inert атрибут.
  • Все элементы внутри становятся недоступными для клавиатуры и скринридеров.
  • Позволяет управлять слоем интерфейса без удаления элементов.

Пример:

const inertMaintainer = ally.maintain.inert(backgroundContent);
inertMaintainer.disengage(); // восстанавливает интерактивность

7. maintain.disableFocus

Метод блокирует фокусировку на выбранных элементах без их физического скрытия.

Синтаксис:

ally.maintain.disableFocus(elements)
  • elements — один или массив DOM-элементов.
  • Устанавливает tabindex="-1".
  • Полезно при временной смене фокуса на модальные окна или уведомления.

Пример:

const disableFocusMaintainer = ally.maintain.disableFocus(navLinks);
disableFocusMaintainer.disengage();

Общие принципы работы методов maintain

  1. Возврат объекта с disengage() — стандартный способ корректного завершения поддержания состояния.
  2. Композиция методов — методы можно комбинировать, например, focus + scroll + inert, чтобы полностью контролировать модальные слои.
  3. ARIA-совместимость — все методы автоматически управляют ARIA-атрибутами (aria-hidden, aria-disabled), что обеспечивает корректную работу с экранными читалками.
  4. Отмена изменений — при вызове disengage() возвращаются исходные значения атрибутов и состояния DOM-элементов.

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

const modal = document.getElementById('modal');
const background = document.getElementById('content');
const submitButton = modal.querySelector('button');

const focusTrap = ally.maintain.focus(modal, { trap: true });
const scrollLock = ally.maintain.scroll(modal);
const backgroundInert = ally.maintain.inert(background);
const buttonDisabled = ally.maintain.disabled(submitButton);

// После закрытия модального окна
focusTrap.disengage();
scrollLock.disengage();
backgroundInert.disengage();
buttonDisabled.disengage();

В этом примере демонстрируется полное управление состоянием интерфейса: фокус, прокрутка, интерактивность элементов и доступность.

Методы ally.maintain обеспечивают гибкое управление состоянием интерфейса, позволяя создавать доступные, управляемые и безопасные для клавиатуры и скринридеров веб-приложения. Их правильное применение повышает удобство и корректность взаимодействия пользователей с интерфейсом.

Оглавление