Боковая панель main.sidepanel

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Передать содержимое без 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) — объект настроек слайдера. Передавайте только те параметры, которые нужны конкретному сценарию.

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

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

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

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

Настроить загрузку через POSTНастроить загрузку через 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();
        }
        

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

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

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

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

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

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

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

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

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

• main.popup — всплывающее окно или выпадающее меню рядом с элементом страницы.

• Расширения — подключение JavaScript-расширений Bitrix Framework.