main.sidepanel — это клиентское JavaScript-расширение Bitrix Framework для открытия страниц и содержимого в боковой панели. В API такую панель называют слайдером. Используйте расширение, когда нужно показать пользователю объект или форму без перехода с текущей страницы: карточку элемента, форму редактирования или настройки.

Основной API доступен через глобальный объект BX.SidePanel.Instance. PHP-код только загружает расширение на страницу, а открытие и управление боковой панелью выполняет JavaScript в браузере.

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

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

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

После загрузки расширения используйте объект BX.SidePanel.Instance в JavaScript-коде страницы.

Если вы работаете в модульном JavaScript, импортируйте объект SidePanel из расширения.

import { SidePanel } from 'main.sidepanel';

SidePanel.Instance.open('/crm/deal/details/15/', {
    width: 900,
});

Открыть панель

Метод BX.SidePanel.Instance.open(url, options) открывает слайдер по URL.

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

true — слайдер начал открываться;
false — слайдер не открылся. Возможные причины: URL пустой, сверху уже открыт слайдер с таким же URL или обработчик события запретил действие.

Если последний закрытый слайдер был кэширован и его URL совпадает с новым вызовом open(), менеджер использует этот экземпляр повторно.

BX.SidePanel.Instance.open('/crm/deal/details/15/', {
    width: 900,
    cacheable: false,
    allowChangeHistory: false,
});

url должен быть непустой строкой.

Не добавляйте в url параметры IFRAME и IFRAME_TYPE. Компонент сам передаст их при загрузке страницы в iframe.

Передать содержимое без iframe

Если панель должна показать содержимое текущей страницы, передайте contentCallback. В этом режиме слайдер не загружает iframe, а использует результат функции как содержимое.

BX.SidePanel.Instance.open('settings-panel', {
    width: 620,
    contentCallback: () => {
        const content = document.createElement('div');
        content.textContent = 'Настройки доступны без перехода на отдельную страницу.';

        return content;
    },
    cacheable: false,
});

Параметр contentCallback получает текущий слайдер и может вернуть DOM-узел, строку, объект с полем html или Promise, который завершится одним из этих значений.

В этом сценарии url остается идентификатором слайдера. Используйте стабильное значение, чтобы затем найти или закрыть слайдер через менеджер.

Передать параметры слайдера

Параметр options в open(url, options) — объект настроек слайдера. Передавайте только те параметры, которые нужны конкретному сценарию.

Размеры и отображение

|

|| Параметр | Тип | Описание || || width | number | Ширина панели в пикселях. Если значение не передано, ширину рассчитывает компонент. || || startPosition | right bottom top | Сторона, с которой появляется слайдер. По умолчанию right. || || animationDuration | number | Длительность анимации открытия и закрытия в миллисекундах. По умолчанию 200. || || overlayOpacity | number | Прозрачность затемнения от 0 до 100. По умолчанию 40. || || overlayBgColor | string | Цвет затемнения в формате #RRGGBB. По умолчанию #000000. || || hideControls | boolean | Скрывает стандартные элементы управления слайдера. || |#

Загрузка содержимого

|

|| Параметр | Тип | Описание || || contentCallback | Function | Возвращает содержимое слайдера без загрузки iframe. Функция получает текущий слайдер. || || requestMethod | get post | Метод загрузки iframe. Значение post включает POST-запрос, остальные значения работают как GET. По умолчанию get. || || requestParams | object | Параметры POST-запроса, если requestMethod: 'post'. || || allowCrossOrigin | boolean | Включает загрузку кросс-доменного iframe при открытии слайдера. В этом режиме слайдер не обращается к содержимому iframe напрямую и обменивается с ним сообщениями через window.postMessage. || || loader | string HTMLElement | Индикатор загрузки. Передайте DOM-элемент или строку с именем загрузчика. || || skeleton | string | Имя скелетона, который будет показан во время загрузки. || || cacheable | boolean | Сохраняет слайдер после закрытия. По умолчанию true. Передайте false, если при следующем открытии нужно заново загрузить страницу или содержимое. || |#

История, заголовок и фокус

|

|| Параметр | Тип | Описание || || title | string | Заголовок слайдера. Компонент может использовать его как заголовок страницы при включенном allowChangeTitle. || || autoFocus | boolean | Переводит фокус в слайдер после открытия. По умолчанию true. || || allowChangeHistory | boolean | Управляет изменением URL текущей страницы через History API. Если параметр не передан, слайдер с iframe меняет URL. URL не меняется для страниц /bitrix/components/, /bitrix/tools/ и кросс-доменных iframe. || || allowChangeTitle | boolean | Управляет изменением document.title. Если параметр не передан, заголовок меняется при наличии title или при включенном изменении URL. || |#

Действия и данные

|

|| Параметр | Тип | Описание || || printable | boolean | Показывает кнопку печати. По умолчанию false. || || newWindowLabel | boolean | Показывает кнопку открытия в новом окне, если слайдер может определить URL. || || newWindowUrl | string | URL для кнопки открытия в новом окне. || || copyLinkLabel | boolean | Показывает кнопку копирования ссылки, если слайдер может определить URL. || || data | object | Пользовательские данные слайдера. Доступен через slider.getData(). Метод возвращает объект Dictionary; читайте значения через slider.getData().get('key') || || events | object object[] | Обработчики событий слайдера. || |#

Настроить загрузку через POST

Передайте requestMethod: 'post' и requestParams, если страницу внутри панели нужно открыть POST-запросом.

BX.SidePanel.Instance.open('/reports/detail/', {
    width: 760,
    requestMethod: 'post',
    requestParams: {
        reportId: 42,
        mode: 'preview',
    },
});

Добавить действия в панель

Чтобы показать в слайдере кнопку печати, открытия в новом окне или копирования ссылки, передайте параметры printable, newWindowLabel или copyLinkLabel.

BX.SidePanel.Instance.open('/company/policy/', {
    width: 800,
    printable: true,
    newWindowLabel: true,
    copyLinkLabel: true,
});

Кнопка открытия в новом окне и кнопка копирования ссылки используют URL слайдера или значение newWindowUrl.

Обработать события

Передайте обработчики в параметре events. Обработчик получает объект SliderEvent: event.getSlider() возвращает текущий слайдер, event.denyAction() запрещает открытие или закрытие.

BX.SidePanel.Instance.open('/crm/deal/details/15/', {
    width: 900,
    events: {
        onLoad: (event) => {
            const slider = event.getSlider();
            console.log(slider.getUrl());
        },
        onClose: (event) => {
            if (window.hasUnsavedChanges === true)
            {
                event.denyAction();
            }
        },
        onCloseComplete: () => {
            window.hasUnsavedChanges = false;
        },
    },
});

Событие onClose вызывается до начала закрытия и может запретить действие. Для кода после фактического закрытия используйте onCloseComplete.

Основные события:

onOpen — вызывается перед открытием. Обработчик может вызвать denyAction().
onOpenStart — вызывается при начале открытия.
onOpening — вызывается при запуске анимации открытия.
onLoad — вызывается после загрузки iframe или содержимого из contentCallback.
onReload — вызывается после повторной загрузки iframe.
onBeforeOpenComplete и onOpenComplete — вызываются при завершении открытия.
onClose — вызывается перед закрытием. Обработчик может вызвать denyAction().
onCloseStart — вызывается при начале закрытия.
onClosing — вызывается при запуске анимации закрытия.
onBeforeCloseComplete и onCloseComplete — вызываются при завершении закрытия.
onDestroy и onDestroyComplete — вызываются при уничтожении слайдера.
onEscapePress — вызывается при нажатии Esc внутри слайдера.
onFrameFocus — вызывается при переходе фокуса в iframe слайдера.
onMaximizeStart — вызывается при начале разворачивания свернутого слайдера.
onMinimizeStart — вызывается при начале сворачивания слайдера.
onLayout — вызывается при пересчете раскладки слайдера.
onFullScreenEnter — вызывается при переходе слайдера в полноэкранный режим.
onFullScreenExit — вызывается при выходе слайдера из полноэкранного режима.

Клавиша Esc закрывает слайдер только когда текущий слайдер находится поверх всплывающих окон и обработчики не запретили закрытие.

Открывать ссылки автоматически

Метод bindAnchors({ rules }) добавляет правила, по которым обычные ссылки открываются в боковой панели. Правило содержит массив условий condition и параметры options.

BX.SidePanel.Instance.bindAnchors({
    rules: [
        {
            condition: [
                '/crm/deal/details/[0-9]+/',
            ],
            options: {
                width: 900,
                cacheable: false,
                allowChangeHistory: false,
            },
        },
    ],
});

Строковые условия преобразуются в регулярные выражения без учета регистра. Если ссылка подходит под правило, компонент отменяет обычный переход и вызывает open(link.url, rule.options).

Параметр stopParameters исключает ссылки с указанными query-параметрами.

BX.SidePanel.Instance.bindAnchors({
    rules: [
        {
            condition: [
                '/tasks/task/view/[0-9]+/',
            ],
            stopParameters: [
                'IFRAME',
                'print',
            ],
            options: {
                width: 820,
            },
        },
    ],
});

Чтобы временно отключить автоматическую обработку ссылок, вызовите disableAnchorBinding(). Правила с forceAnchorBinding: true продолжат работать.

BX.SidePanel.Instance.disableAnchorBinding();
BX.SidePanel.Instance.enableAnchorBinding();

Ссылка не откроется в боковой панели в трех случаях:

ссылка кросс-доменная, а в правиле автопривязки не передано allowCrossDomain: true;
страница открыта в мобильном браузере, а в правиле нет mobileFriendly: true;
функция validate(link) вернула false.

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

BX.SidePanel.Instance хранит стек открытых слайдеров. Верхний слайдер считается текущим.

const slider = BX.SidePanel.Instance.getTopSlider();

if (slider)
{
    slider.reload();
}

Основные методы менеджера:

|

|| Метод | Что делает || || open(url, options) | Открывает слайдер. || || maximize(url, options) | Открывает слайдер из свернутого состояния, если используется минимизация. || || close(immediately, callback) | Закрывает верхний слайдер. || || closeAll(immediately) | Закрывает все открытые слайдеры сверху вниз. || || minimize(immediately, callback) | Сворачивает верхний слайдер, если заданы настройки минимизации. || || reload() | Перезагружает верхний слайдер. || || destroy(url) | Уничтожает слайдер по URL. || || getTopSlider() | Возвращает верхний слайдер или null. || || getSlider(url) | Возвращает открытый слайдер по URL или null. || || getOpenSliders() | Возвращает массив открытых слайдеров. || || getOpenSlidersCount() | Возвращает количество открытых слайдеров. || || hide() и unhide() | Скрывают и возвращают открытые слайдеры без уничтожения. || || enterFullScreen() | Переводит браузер в полноэкранный режим для верхнего слайдера. || || exitFullScreen() | Выходит из полноэкранного режима. || |#

Метод close() работает с верхним слайдером. Если нужно закрыть конкретный слайдер, получите его через getSlider(url) и вызовите close() у самого слайдера.

const slider = BX.SidePanel.Instance.getSlider('/crm/deal/details/15/');

if (slider)
{
    slider.close();
}

Передавать сообщения между слайдерами

Менеджер передает сообщения между слайдерами и основной страницей. Источником может быть URL слайдера, объект Window или экземпляр Slider.

Методы принимают три аргумента: источник сообщения, идентификатор события и объект с данными.

|

|| Метод | Куда отправляет сообщение || || postMessage(source, eventId, data) | В предыдущий слайдер. Если предыдущего слайдера нет, сообщение получает основная страница. || || postMessageAll(source, eventId, data) | Во все открытые слайдеры, кроме слайдера-источника, и на основную страницу. || || postMessageTop(source, eventId, data) | На основную страницу. || |#

const slider = BX.SidePanel.Instance.getTopSlider();

if (slider)
{
    BX.SidePanel.Instance.postMessageTop(slider, 'deal-updated', {
        id: 15,
    });
}

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

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

main.popup — всплывающее окно или выпадающее меню рядом с элементом страницы.
Расширения — подключение JavaScript-расширений Bitrix Framework.