Индикатор загрузки main.loader

Расширение main.loader выводит вращающийся круговой индикатор загрузки. Индикатор показывают, пока выполняется запрос или загружается содержимое блока, например список документов, вкладка или превью файла.

За индикатор отвечает класс Loader. Он вставляет индикатор в указанный контейнер и плавно показывает и скрывает его.

Если на время загрузки нужно показать заготовку будущего содержимого, а не индикатор, используйте скелетон загрузки ui.system.skeleton. Если нужно показать долю выполненной работы, используйте индикаторы прогресса ui.progressbar и ui.progressround.

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

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

\Bitrix\Main\UI\Extension::load('main.loader');

В модульном JavaScript импортируйте класс Loader.

import { Loader } from 'main.loader';

Вне модульного JavaScript класс доступен как BX.Loader.

Показать индикаторПоказать индикатор

Создайте экземпляр Loader, передайте контейнер в параметре target и вызовите show(). Метод hide() скрывает индикатор. Вызывайте hide() и при ошибке запроса, иначе индикатор останется на странице.

Пример. Пока загружается список документов, в центре блока списка вращается индикатор. Код скрывает индикатор после ответа, в том числе после ошибки.

import { Loader } from 'main.loader';

// Контейнеру нужно позиционирование, например position: relative
const container = document.getElementById('documents');
const loader = new Loader({ target: container });

loader.show();

// loadDocuments() — функция вашего модуля, которая возвращает Promise с HTML списка
loadDocuments()
    .then((html) => {
        container.innerHTML = html;
    })
    .finally(() => {
        loader.hide();
    });

Индикатор с параметрами по умолчанию — серое вращающееся кольцо в центре контейнера.

По умолчанию индикатор размещается по центру контейнера с абсолютным позиционированием. Задайте контейнеру позиционирование, например position: relative, иначе индикатор встанет по центру ближайшего позиционированного предка.

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

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

Все параметры необязательны.

Режим размещения задает, как индикатор стоит в контейнере.

• Без mode — индикатор стоит по центру контейнера. Значения offset сдвигают его через отступы margin-top и margin-left.

• inline — индикатор встает в поток содержимого, как обычный элемент, и не перекрывает соседние элементы. Значения offset сдвигают его относительно места в потоке через свойства top и left.

• custom — индикатор стоит в левом верхнем углу контейнера, а offset задает свойства top и left, то есть точное положение.

Пример. Небольшой индикатор встает в поток рядом с подписью «Сохраняем».

import { Loader } from 'main.loader';

const loader = new Loader({
    target: document.getElementById('save-status'),
    size: 20,
    mode: 'inline',
    color: '#2fc6f6',
});

loader.show();

В режиме inline индикатор стоит в строке рядом с текстом.

Управлять индикаторомУправлять индикатором

Методы экземпляра:

• show(target) — показывает индикатор. Если передан контейнер, переносит индикатор в него. Повторный вызов на показанном индикаторе ничего не меняет.

• hide() — скрывает индикатор. Элемент индикатора остается в контейнере, и повторный show() показывает его снова.

• isShown() — возвращает true, если последним вызывали show(). Значение true не гарантирует, что индикатор виден на странице.

• setOptions(options) — меняет размер, цвет, толщину линии, режим и сдвиг уже созданного индикатора.

• destroy() — удаляет элемент индикатора со страницы. Экземпляр остается рабочим, и следующий show() вернет индикатор в прежний контейнер.

Если не передать контейнер ни в конструктор, ни в show(), индикатор не появится на странице, хотя isShown() вернет true.

Передавайте mode в каждом вызове setOptions(), иначе индикатор выходит из режима inline. Метод setOptions() не отменяет режим custom. Чтобы вернуть индикатор в центр контейнера, создайте новый экземпляр.

Свойство layout возвращает элемент индикатора. Используйте его, если индикатор нужно вставить в разметку самостоятельно.

Индикатор не задает атрибуты доступности. Если экранная читалка должна сообщить о загрузке, добавьте элементу layout атрибут role сами.

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

• Скелетон загрузки

• Индикаторы прогресса ui.progressbar и ui.progressround

• Вкладки ui.tabs

• Расширения