Перейти к содержанию

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

В обычном сценарии не создавайте трекер вручную. Расширение ui.a11y инициализирует FocusMonitor, а монитор содержит общий экземпляр InputModalityTracker. Получайте его через FocusMonitor.Instance.getModalityTracker().

Подключить расширение

Если вы подключаете JavaScript API из PHP, загрузите расширение ui.a11y.

\Bitrix\Main\UI\Extension::load('ui.a11y');

Если вы работаете в модульном JavaScript, импортируйте FocusMonitor из ui.a11y.

import { FocusMonitor } from 'ui.a11y';

Если нужен отдельный экземпляр трекера, импортируйте InputModalityTracker.

import { InputModalityTracker } from 'ui.a11y';

Получить общий трекер

Метод getModalityTracker() возвращает экземпляр InputModalityTracker, который использует FocusMonitor.

import { FocusMonitor } from 'ui.a11y';

const tracker = FocusMonitor.Instance.getModalityTracker();

Используйте общий трекер, если компонент работает на странице с уже подключенным ui.a11y.

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

Методы

|

|| Метод | Что делает || || attach(doc) | Подключает документ к отслеживанию клавиатуры и указателя || || detach(doc) | Отключает документ от отслеживания || || getLastModality() | Возвращает последний способ ввода: 'keyboard', 'pointer' или 'unknown' || || getLastPointerType() | Возвращает тип последнего указателя: 'mouse', 'pen', 'touch' или null || || getLastNavigationKey() | Возвращает последнюю навигационную клавишу или null || || isLastNavigationReversed() | Возвращает true, если последним клавиатурным действием был Shift+Tab || || InputModalityTracker.enableDebug() | Включает отладочный вывод || || InputModalityTracker.disableDebug() | Отключает отладочный вывод || |#

Контракты методов

|

|| Метод | Параметры | Результат | Эффект и ограничения || || attach(doc) | doc — объект Document | Ничего не возвращает | Подключает документ к отслеживанию клавиатуры и указателя. Используйте для отдельного экземпляра трекера или изолированного документа || || detach(doc) | doc — объект Document | Ничего не возвращает | Отключает обработчики от документа. Вызывайте после завершения сценария, если документ больше не нужно отслеживать || || getLastModality() | Нет | Возвращает 'keyboard', 'pointer' или 'unknown' | Обычный ввод текста не считается клавиатурной навигацией || || getLastPointerType() | Нет | Возвращает 'mouse', 'pen', 'touch' или null | Возвращает тип только после указательного действия. Если последним действием была клавиатура, вернет null || || getLastNavigationKey() | Нет | Возвращает последнюю навигационную клавишу или null | Учитывает только Tab, Escape, стрелки, Home и End. После указательного действия возвращает null || || isLastNavigationReversed() | Нет | Возвращает true или false | Возвращает true, если последним клавиатурным действием был Shift+Tab || || InputModalityTracker.enableDebug() | Нет | Ничего не возвращает | Включает отладочный вывод трекера способа ввода. Используйте только на время проверки сценария || || InputModalityTracker.disableDebug() | Нет | Ничего не возвращает | Отключает отладочный вывод трекера способа ввода || |#

Проверить последний способ ввода

Метод getLastModality() возвращает последний зафиксированный способ ввода.

|

|| Значение | Когда возвращается || || 'keyboard' | Пользователь нажал навигационную клавишу: Tab, Escape, стрелки, Home или End || || 'pointer' | Пользователь нажал кнопку мыши, коснулся экрана или использовал стилус || || 'unknown' | Трекер еще не зафиксировал клавиатурное или указательное действие || |#

import { FocusMonitor } from 'ui.a11y';

const tracker = FocusMonitor.Instance.getModalityTracker();

if (tracker.getLastModality() === 'keyboard')
{
    FocusMonitor.Instance.restoreFocus();
}

Проверяйте способ ввода перед действиями, которые нужны только в клавиатурном сценарии. Например, после удаления активного элемента можно восстановить фокус для пользователя клавиатуры и не менять фокус после клика мышью.

Определить тип указателя

Метод getLastPointerType() возвращает тип последнего указательного действия или null, если последним был не указатель.

|

|| Значение | Что означает || || 'mouse' | Пользователь нажал кнопку мыши || || 'pen' | Пользователь использовал стилус || || 'touch' | Пользователь коснулся экрана || || null | Последнее действие не было указательным || |#

import { FocusMonitor } from 'ui.a11y';

const tracker = FocusMonitor.Instance.getModalityTracker();

if (tracker.getLastPointerType() === 'touch')
{
    document.body.classList.add('touch-input');
}

Метод возвращает тип указателя только после указательного действия. Если последним действием была клавиатура, результат будет null, даже если раньше пользователь работал мышью или касанием.

Проверить навигационную клавишу

Метод getLastNavigationKey() возвращает последнюю клавишу, по которой трекер определил клавиатурный сценарий. Если последним действием был указатель, метод возвращает null.

import { FocusMonitor } from 'ui.a11y';

const tracker = FocusMonitor.Instance.getModalityTracker();
const key = tracker.getLastNavigationKey();

if (key === 'Escape')
{
    document.querySelector('#panel')?.remove();
}

Трекер учитывает только навигационные клавиши: Tab, Escape, стрелки, Home и End. Обычный ввод текста не переводит трекер в состояние 'keyboard'.

Проверить обратную навигацию

Метод isLastNavigationReversed() возвращает true, если последним клавиатурным действием был Shift+Tab.

import { FocusMonitor } from 'ui.a11y';

const tracker = FocusMonitor.Instance.getModalityTracker();

if (tracker.isLastNavigationReversed())
{
    FocusMonitor.Instance.restoreFocus();
}

Используйте проверку, когда поведение компонента зависит от направления перехода по фокусу. Например, FocusZone применяет это состояние, чтобы выбрать элемент при входе в контейнер с обратной навигацией.

Подключить документ вручную

Метод attach(doc) подключает документ к отслеживанию клавиатуры и указателя. Метод detach(doc) отключает обработчики от этого документа.

import { InputModalityTracker } from 'ui.a11y';

const tracker = new InputModalityTracker();
tracker.attach(document);

// После удаления документа или завершения сценария
tracker.detach(document);

Создавайте отдельный экземпляр только для изолированного сценария, где нельзя использовать общий трекер FocusMonitor. Например, отдельный трекер может понадобиться для документа, жизненный цикл которого контролирует ваш компонент.

После завершения такого сценария вызовите detach(doc), чтобы отключить обработчики.

В интерфейсе страницы обычно достаточно FocusMonitor.Instance.getModalityTracker().

Включить логирование

InputModalityTracker поддерживает отладочный вывод через статические методы. Включайте логирование только на время проверки сценария и отключайте после отладки.

import { InputModalityTracker } from 'ui.a11y';

InputModalityTracker.enableDebug();
InputModalityTracker.disableDebug();

Связанные материалы