Объявления для скринридера LiveAnnouncer

LiveAnnouncer добавляет текстовые сообщения в скрытую live region — область страницы с атрибутом aria-live. Скринридер может сообщить пользователю об изменении этой области без перемещения фокуса.

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

В Bitrix Framework за объявления для скринридера отвечает расширение ui.a11y. В нем доступен класс LiveAnnouncer.

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

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

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

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

import { LiveAnnouncer } from 'ui.a11y';

Объявить сообщениеОбъявить сообщение

Статический метод LiveAnnouncer.announce(message, politeness?) передает сообщение в live region. Первый параметр содержит текст объявления, второй позволяет изменить приоритет для конкретного сообщения.

import { LiveAnnouncer } from 'ui.a11y';

LiveAnnouncer.announce('Настройки сохранены.');

Используйте короткий текст, который описывает результат действия. Не добавляйте в объявление текст кнопки или поля, если этот текст уже доступен скринридеру при фокусе на элементе.

import { LiveAnnouncer } from 'ui.a11y';

const form = document.querySelector('#profile-form');
if (!form)
{
    throw new Error('Profile form was not found.');
}

form.addEventListener('submit', (event) => {
    event.preventDefault();

    LiveAnnouncer.announce('Профиль сохранен.');
});

Выбрать приоритет объявленияВыбрать приоритет объявления

Параметр politeness задает приоритет объявления и принимает два строковых значения.

import { LiveAnnouncer } from 'ui.a11y';

LiveAnnouncer.announce('Не удалось сохранить настройки.', 'assertive');

Создать отдельный экземплярСоздать отдельный экземпляр

Создайте отдельный экземпляр LiveAnnouncer, если область объявления нужно добавить в конкретный контейнер или если нужно изменить задержки обработки сообщений.

import { LiveAnnouncer } from 'ui.a11y';

const container = document.querySelector('#wizard');
if (!container)
{
    throw new Error('Wizard container was not found.');
}

const announcer = new LiveAnnouncer({
    container,
    politeness: 'polite',
});

announcer.announce('Шаг сохранен.');

Вызовите destroy() у экземпляра, когда контейнер удаляется из DOM или отдельный экземпляр больше не нужен. Метод очищает ожидающие сообщения и удаляет созданную область объявления.

announcer.destroy();

Статический метод LiveAnnouncer.destroy() удаляет общий экземпляр, который создает LiveAnnouncer.announce().

LiveAnnouncer.destroy();

Основные методы LiveAnnouncer меняют состояние live region или отладочного вывода. Не используйте их как источник данных для бизнес-логики: вызывайте метод после действия и проверяйте результат по изменению интерфейса, live region или сообщению в консоли при включенной отладке.

Передать параметрыПередать параметры

Конструктор LiveAnnouncer принимает необязательный объект LiveAnnouncerOptions.

type LiveAnnouncerOptions = {
    politeness?: AriaLivePoliteness;
    container?: HTMLElement;
    baseDelay?: number;
    charDelay?: number;
    maxDelay?: number;
    maxMessageLength?: number;
};

type AriaLivePoliteness = 'polite' | 'assertive';

Итоговая задержка рассчитывается как baseDelay + message.length * charDelay, но не превышает maxDelay.

Передавайте в параметры задержек и длины положительные числа в миллисекундах. Если компоненту нужны нестандартные задержки, задавайте все связанные значения вместе: baseDelay, charDelay и maxDelay. Так проще предсказать, когда следующее сообщение попадет в live region.

import { LiveAnnouncer } from 'ui.a11y';

const container = document.querySelector('#search-results');
if (!container)
{
    throw new Error('Search results container was not found.');
}

const announcer = new LiveAnnouncer({
    container,
    baseDelay: 300,
    charDelay: 20,
    maxDelay: 2500,
    maxMessageLength: 120,
});

announcer.announce('Результаты поиска обновлены.');

Что происходит с сообщениямиЧто происходит с сообщениями

LiveAnnouncer нормализует текст перед объявлением.

• Пустые строки и строки из пробельных символов игнорируются.
• Пробелы в начале и конце сообщения удаляются.
• Сообщение длиннее maxMessageLength обрезается и завершается многоточием.
• Повтор последнего ожидающего сообщения с тем же приоритетом не добавляется повторно.
• Сообщение с приоритетом 'assertive' прерывает текущее объявление или ожидание и ставится в начало обработки.

Если после обработки сообщений список ожидания пуст, LiveAnnouncer очищает текст области объявления.

Проверить объявлениеПроверить объявление

На время проверки включите отладочный вывод через LiveAnnouncer.enableDebug(). После вызова announce() проверьте сообщение в консоли и убедитесь, что в DOM появилась скрытая область с атрибутом aria-live.

Фактическое чтение сообщения зависит от скринридера, браузера и текущей очереди объявлений. Поэтому не используйте LiveAnnouncer для сообщений, которые должны быть видимы всем пользователям: текст ошибки, статус загрузки или результат действия должен оставаться доступным в интерфейсе, а объявление для скринридера должно дублировать важное изменение состояния.

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

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

import { LiveAnnouncer } from 'ui.a11y';

// Включить вывод объявлений в консоль.
LiveAnnouncer.enableDebug();

// Отключить вывод объявлений в консоль.
LiveAnnouncer.disableDebug();

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

• Расширение ui.a11y — обзор инструментов доступности в интерфейсе.
• Навигация фокуса FocusNavigator — поиск и программное перемещение фокуса внутри DOM-контейнера.
• Ловушка фокуса FocusTrap — удержание фокуса внутри модального окна, диалога или выпадающего меню.
• Расширения — подключение JavaScript-расширений Bitrix Framework.