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

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 задает приоритет объявления и принимает два строковых значения.

|

|| Значение | Когда использовать || || 'polite' | Для обычных сообщений, которые можно передать без прерывания текущего чтения: сохранение, завершение фоновой загрузки, обновление списка. || || 'assertive' | Для срочных сообщений, которые могут прервать текущую очередь объявлений: критичная ошибка, потеря соединения, действие, которое нельзя продолжить без внимания пользователя. || |#

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.announce(message, politeness?) | message — текст объявления, politeness — приоритет для этого сообщения. | Добавляет сообщение в общий экземпляр LiveAnnouncer. Если общий экземпляр еще не создан, метод создает его автоматически. || || announcer.announce(message, politeness?) | message — текст объявления, politeness — приоритет для этого сообщения. | Добавляет сообщение в очередь отдельного экземпляра. || || announcer.destroy() | Нет. | Очищает очередь сообщений отдельного экземпляра и удаляет созданную им live region. || || LiveAnnouncer.destroy() | Нет. | Удаляет общий экземпляр, который используется статическим методом LiveAnnouncer.announce(). || || LiveAnnouncer.enableDebug() | Нет. | Включает вывод объявлений в консоль. || || LiveAnnouncer.disableDebug() | Нет. | Отключает вывод объявлений в консоль. || |#

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

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

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

type AriaLivePoliteness = 'polite' | 'assertive';

|

|| Параметр | Тип | Описание || || politeness | AriaLivePoliteness | Задает приоритет по умолчанию. По умолчанию — 'polite'. || || container | HTMLElement | Задает элемент, в который будет добавлена область объявления. Передавайте существующий HTMLElement. По умолчанию — document.body или document.documentElement. || || baseDelay | number | Задает базовую задержку перед обработкой следующего сообщения в миллисекундах. По умолчанию — 500. || || charDelay | number | Добавляет задержку за каждый символ сообщения в миллисекундах. По умолчанию — 30. || || maxDelay | number | Ограничивает максимальную задержку перед следующим сообщением в миллисекундах. По умолчанию — 4000. || || maxMessageLength | number | Ограничивает длину сообщения. Более длинный текст обрезается и завершается многоточием. По умолчанию — 160. || |#

Итоговая задержка рассчитывается как 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();

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