ally.element.focus и его параметры

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

Основное использование

ally.element.focus принимает объект конфигурации, где ключевым параметром является element. Он может быть:

  • DOM-элементом (HTMLElement)
  • CSS-селектором (string)
  • Функцией, возвращающей элемент

Пример базового вызова:

ally.element.focus({
  element: '#myButton'
});

В этом случае фокус будет установлен на элемент с id="myButton".

Параметры конфигурации

Функция поддерживает несколько параметров, позволяющих точно управлять поведением фокуса:

element

Тип: HTMLElement | string | function Обязательный параметр. Определяет элемент, на который будет установлен фокус.

preventScroll

Тип: boolean По умолчанию: false Если установлено в true, установка фокуса не вызовет прокрутку страницы к элементу. Полезно для сохранения позиции на странице при динамическом управлении фокусом.

ally.element.focus({
  element: '#inputField',
  preventScroll: true
});

strategy

Тип: string Возможные значения: 'default', 'focusable', 'tabbable' Определяет, каким образом библиотека выбирает элемент для фокусировки, если element не указан напрямую:

  • default — стандартное поведение браузера
  • focusable — выбирает первый фокусируемый элемент внутри контейнера
  • tabbable — выбирает элемент, который может быть достигнут с помощью клавиши Tab
ally.element.focus({
  element: '#container',
  strategy: 'tabbable'
});

context

Тип: HTMLElement Задает контекст, в котором будет производиться поиск фокусируемого элемента. Используется совместно со стратегией focusable или tabbable.

ally.element.focus({
  element: '.menu',
  strategy: 'focusable',
  context: document.querySelector('.menu-wrapper')
});

ignoreVisibility

Тип: boolean По умолчанию: false Если true, функция будет игнорировать проверку видимости элемента. Это позволяет установить фокус на скрытые элементы (например, в модальных окнах перед их показом).

ally.element.focus({
  element: '#hiddenInput',
  ignoreVisibility: true
});

ignoreAutofocus

Тип: boolean По умолчанию: false Если true, библиотека игнорирует элементы с атрибутом autofocus. Полезно при динамическом управлении фокусом, чтобы не конфликтовать с автозаполнением браузера.

selectText

Тип: boolean По умолчанию: false Если true и элемент является <input> или <textarea>, будет выделен весь текст внутри элемента после установки фокуса.

ally.element.focus({
  element: '#searchInput',
  selectText: true
});

Возвращаемое значение

Функция возвращает объект с информацией о результатах фокусировки:

  • success — true, если фокус был успешно установлен
  • element — элемент, на который был установлен фокус
  • reason — причина, если фокус установить не удалось

Пример обработки результата:

const result = ally.element.focus({ element: '#submitButton' });

if (result.success) {
  console.log('Фокус установлен на:', result.element);
} else {
  console.warn('Не удалось установить фокус. Причина:', result.reason);
}

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

  • Фокусировка выполняется асинхронно, что позволяет корректно обрабатывать динамически появляющиеся элементы.
  • При работе с элементами внутри модальных окон или вкладок рекомендуется использовать параметры ignoreVisibility и context для точного управления фокусом.
  • ally.element.focus автоматически учитывает доступность элементов: не фокусирует disabled-кнопки, скрытые поля и элементы вне DOM-контекста, если не включены соответствующие флаги.

Практические сценарии

  1. Фокус при открытии модального окна
const modal = document.querySelector('#modal');
ally.element.focus({
  element: modal.querySelector('button:first-of-type'),
  ignoreVisibility: true
});
  1. Автоматическое выделение текста в поле поиска
ally.element.focus({
  element: '#searchBox',
  selectText: true
});
  1. Фокус на первом таб-элементе в контейнере
ally.element.focus({
  element: '#tabContainer',
  strategy: 'tabbable'
});

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

Оглавление