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

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

Основная концепция ally.when

ally.when позволяет отслеживать состояние элементов или определённые события и выполнять callback-функцию, когда условие становится истинным. Синтаксис базируется на цепочках методов с последующим вызовом .do(callback) или .then(callback):

ally.when.selector('.my-button').do(() => {
  console.log('Элемент доступен для взаимодействия');
});

Ключевой принцип: методы ally.when возвращают объект с API для настройки условий и действий, что позволяет создавать гибкие комбинации.

Методы для условий

1. selector(query)

Отслеживает появление элемента в DOM по CSS-селектору. Callback выполняется, когда элемент существует.

ally.when.selector('#submit-button').do(el => {
  el.focus();
});

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

  • Можно использовать несколько селекторов через запятую.
  • Работает с динамически создаваемыми элементами.

2. focus(element)

Следит за фокусом на указанном элементе. Callback вызывается при получении или потере фокуса.

ally.when.focus('#input-field').do(el => {
  console.log('Поле в фокусе');
});

Дополнительно поддерживается фильтрация событий focusin и focusout.

3. visible(element)

Условие срабатывает, когда элемент становится видимым в DOM:

ally.when.visible('#menu').do(() => {
  console.log('Меню отображено');
});

Учитывается:

  • Стили display: none и visibility: hidden.
  • Перекрытия других элементов.

4. enabled(element)

Следит за изменением состояния доступности элемента (disabled):

ally.when.enabled('#submit').do(el => {
  el.click();
});

Callback выполняется только при переходе элемента в активное состояние.

5. focused(element)

Позволяет отслеживать конкретно фокус клавиатуры на элементе:

ally.when.focused('.input-field').do(el => {
  console.log('Элемент активен');
});

Используется для управления навигацией и доступностью форм.

6. contains(element, child)

Проверяет, находится ли один элемент внутри другого:

ally.when.contains('#container', '.child-element').do(() => {
  console.log('Элемент внутри контейнера');
});

Полезно для динамического DOM и отслеживания вложенных элементов.

7. attribute(element, attr, value)

Срабатывает при изменении значения указанного атрибута:

ally.when.attribute('#input', 'aria-expanded', 'true').do(() => {
  console.log('Меню раскрыто');
});

Поддерживает:

  • Простое наличие атрибута.
  • Сравнение с конкретным значением.

8. event(element, eventName)

Позволяет реагировать на пользовательские события:

ally.when.event('#button', 'click').do(() => {
  console.log('Кнопка нажата');
});

Поддерживает любые стандартные DOM-события, включая keydown, input, change.

Методы для управления выполнением

1. do(callback)

Основной метод для выполнения действий при срабатывании условия. Callback получает элемент в качестве аргумента.

ally.when.selector('#modal').do(el => el.focus());

2. then(callback)

Аналог do, но поддерживает цепочку промисов, полезно для асинхронных действий:

ally.when.selector('#modal').then(async el => {
  await fetchData();
  el.focus();
});

3. otherwise(callback)

Выполняется, если условие не выполняется:

ally.when.enabled('#submit')
  .do(() => console.log('Элемент активен'))
  .otherwise(() => console.log('Элемент заблокирован'));

4. wait(milliseconds)

Добавляет задержку перед выполнением callback:

ally.when.visible('#tooltip').wait(300).do(el => el.focus());

Комбинирование условий

Методы ally.when поддерживают логические цепочки:

  • and — все условия должны выполняться одновременно.
  • or — достаточно выполнения хотя бы одного условия.

Пример:

ally.when.selector('#input')
  .and.focused()
  .do(el => console.log('Поле существует и в фокусе'));

Встроенная отписка и очистка

ally.when возвращает объект с методом dispose(), позволяющий отменить наблюдение:

const watcher = ally.when.selector('#dynamic').do(el => console.log(el));
watcher.dispose();

Это предотвращает утечки памяти при работе с динамическим контентом.

Полезные особенности

  • Поддержка динамически создаваемых элементов без ручного отслеживания MutationObserver.
  • Совместимость с ассистивными технологиями: соблюдает стандарты ARIA.
  • Интеграция с асинхронными сценариями через then.
  • Высокая гибкость при построении цепочек условий и событий.

ally.when является мощным инструментом для контроля доступности и состояния элементов в интерфейсе, обеспечивая точное управление фокусом, видимостью, событиями и атрибутами DOM с минимальным количеством кода. Он позволяет создавать адаптивные и доступные интерфейсы, отвечающие современным стандартам веб-разработки.

Оглавление