ally.when.key

Библиотека ally.js предоставляет мощный инструмент для работы с доступностью веб-приложений. Модуль ally.when.key предназначен для упрощения обработки клавиатурных событий и позволяет реагировать на конкретные нажатия клавиш с гибкой настройкой условий срабатывания.

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

  1. Прослушивание конкретных клавиш ally.when.key позволяет задать одну или несколько клавиш, на которые необходимо реагировать. Поддерживаются как строковые обозначения клавиш ('Enter', 'Escape'), так и коды клавиш ('KeyA', 'ArrowDown').

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

  3. Комбинации клавиш и модификаторы Поддерживаются сочетания клавиш с модификаторами: Shift, Ctrl, Alt, Meta. Например, можно настроить обработчик только для Ctrl+Enter или Shift+ArrowUp.

  4. Управление поведением событий С помощью параметров preventDefault и stopPropagation можно контролировать стандартное поведение браузера и всплытие событий, что особенно полезно для сложных интерфейсов.

Синтаксис и параметры

ally.when.key({
  key: 'Escape',              // Строка или массив клавиш
  context: document,          // DOM-элемент или селектор
  event: 'keydown',           // 'keydown' | 'keyup' | 'keypress'
  default: false,             // Предотвратить действие по умолчанию
  stop: false,                // Остановить всплытие события
  filter: function(event) {   // Дополнительная фильтрация
    return event.target.tagName !== 'INPUT';
  }
}).then(function(event) {
  console.log('Нажата клавиша Escape');
});

Ключевые параметры:

  • key – одна клавиша или массив клавиш, на которые реагирует обработчик.
  • context – область документа, где отслеживаются события. По умолчанию это document.
  • event – тип события клавиатуры (keydown, keyup, keypress).
  • default – если true, стандартное поведение клавиши не выполняется.
  • stop – если true, событие не будет всплывать.
  • filter – функция для дополнительной фильтрации, возвращающая true для разрешённых случаев.

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

Отслеживание одной клавиши

ally.when.key({
  key: 'Enter',
  context: document
}).then(function(event) {
  console.log('Нажата клавиша Enter');
});

Сочетание клавиш с модификаторами

ally.when.key({
  key: ['KeyS'],
  context: document,
  filter: function(event) {
    return event.ctrlKey; // Только Ctrl+S
  }
}).then(function(event) {
  console.log('Сохранение документа');
});

Фильтрация по целевым элементам

ally.when.key({
  key: 'Escape',
  context: document,
  filter: function(event) {
    return !event.target.matches('input, textarea'); // Игнорируем поля ввода
  }
}).then(function(event) {
  console.log('Закрыть модальное окно');
});

Отмена стандартного поведения и всплытия

ally.when.key({
  key: 'Tab',
  context: document,
  default: true,
  stop: true
}).then(function(event) {
  console.log('Смена фокуса через Tab управляется вручную');
});

Рекомендации по использованию

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

Взаимодействие с другими модулями ally.js

ally.when.key часто комбинируется с:

  • ally.query.focused – для проверки текущего элемента с фокусом перед выполнением действия.
  • ally.maintain.tab.focus – для управления циклом табуляции в модальных окнах или динамических интерфейсах.
  • ally.focus.trap – чтобы ограничить фокус внутри определённой области и реагировать на Escape для выхода.

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

Особенности поведения

  • ally.when.key использует промисы, что позволяет выстраивать цепочки действий и асинхронную логику без вложенных коллбэков.
  • Обработчики можно легко удалять, сохраняя ссылку на возвращаемый объект и вызывая метод destroy() для прекращения отслеживания событий.
  • Поддержка массивов клавиш упрощает обработку нескольких вариантов действий для одного события.
Оглавление