Виджеты

Что такое виджет

Bitrix24 открывает обработчик виджета в iframe, слайдере или другом интерфейсном месте. На URL обработчика передаётся контекст: где открыт виджет, кто его открыл и к какой сущности он относится.

Для простых внутренних инструментов виджет удобно делать как локальное приложение: страница приложения открывается внутри Bitrix24, получает контекст и дальше вызывает REST-методы через BX24.callMethod().

placement

PLACEMENT — это код места встройки. Именно он передаётся в placement.bind и говорит Битриксу, куда добавить приложение.

BX24.callMethod(
    'placement.bind',
    {
        PLACEMENT: 'CRM_DEAL_DETAIL_TAB',
        HANDLER: 'https://example.com/bitrix24/deal-tab.php',
        TITLE: 'Мой виджет'
    },
    function (result) {
        if (result.error()) {
            console.error(result.error());
            return;
        }

        console.log(result.data());
    }
);

Когда один и тот же URL используется для нескольких виджетов, значение PLACEMENT помогает понять, откуда именно был открыт обработчик.

Основные места встройки

Ниже не полный справочник всех параметров, а рабочая карта: куда можно встроить приложение и какую страницу документации открыть, когда нужен конкретный виджет.

CRM

Задачи

Рабочие группы и проекты

Профиль пользователя, календарь и телефония

Мессенджер

Контакт-центр, универсальные виджеты и пользовательские поля

Коды встройки лучше сверять с конкретной страницей документации перед использованием: часть мест поддерживает разные варианты для лидов, сделок, контактов, компаний, счетов, предложений и смарт-процессов.

Когда регистрировать

Виджеты удобно регистрировать при установке приложения через BX24.install(). Пока приложение не установлено до конца, виджет обычно не отображается в интерфейсе.

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

placement.bind

BX24.install(function () {
    BX24.callMethod(
        'placement.bind',
        {
            PLACEMENT: 'CRM_DEAL_DETAIL_TAB',
            HANDLER: 'https://example.com/bitrix24/deal-tab.php',
            TITLE: 'Мой виджет'
        },
        function (result) {
            if (result.error()) {
                console.error(result.error());
                BX24.installFinish();
                return;
            }

            BX24.installFinish();
        }
    );
});

В HANDLER указывается URL страницы приложения, которую Bitrix24 откроет в месте встройки. Для боевого приложения это должен быть доступный HTTPS-адрес.

placement.unbind

Если нужно убрать привязку, используется placement.unbind.

BX24.callMethod(
    'placement.unbind',
    {
        PLACEMENT: 'CRM_DEAL_DETAIL_TAB',
        HANDLER: 'https://example.com/bitrix24/deal-tab.php'
    },
    function (result) {
        if (result.error()) {
            console.error(result.error());
            return;
        }

        console.log(result.data());
    }
);

PLACEMENT_OPTIONS

Когда Bitrix24 открывает обработчик виджета, в него передаются параметры контекста. Например, в карточке CRM обычно приходит ID элемента, а в мессенджере — данные диалога.

<?php

/**
 * Получает параметры виджета.
 */
function fetchPlacementOptions(): array
{
    $placement_options = $_REQUEST['PLACEMENT_OPTIONS'] ?? '{}';
    $options = json_decode((string) $placement_options, true);

    return is_array($options) ? $options : [];
}

$options = fetchPlacementOptions();

print_r($options);

На практике первый шаг при разработке нового виджета — вывести весь $_REQUEST и отдельно PLACEMENT_OPTIONS, чтобы увидеть фактический контекст конкретного места встройки.

CRM detail tab

BX24.callMethod(
    'placement.bind',
    {
        PLACEMENT: 'CRM_DEAL_DETAIL_TAB',
        HANDLER: 'https://example.com/bitrix24/deal-tab.php',
        TITLE: 'Данные интеграции'
    },
    function (result) {
        if (result.error()) {
            console.error(result.error());
            return;
        }

        console.log('CRM tab registered');
    }
);

В обработчике вкладки нужно читать PLACEMENT_OPTIONS, чтобы получить ID сущности CRM и загрузить данные именно по этой карточке.

<?php

/**
 * Получает ID CRM-элемента из параметров виджета.
 */
function fetchCrmEntityIdFromPlacement(): int
{
    $options = fetchPlacementOptions();

    return isset($options['ID']) ? (int) $options['ID'] : 0;
}

$deal_id = fetchCrmEntityIdFromPlacement();

echo $deal_id;

IM sidebar

BX24.callMethod(
    'placement.bind',
    {
        PLACEMENT: 'IM_SIDEBAR',
        HANDLER: 'https://example.com/bitrix24/im-sidebar.php',
        TITLE: 'Информация по чату'
    },
    function (result) {
        if (result.error()) {
            console.error(result.error());
            return;
        }

        console.log('IM sidebar registered');
    }
);

В сайдбаре мессенджера в PLACEMENT_OPTIONS может приходить dialogId. Для обычного группового чата он часто выглядит как chat1489. Перед использованием лучше вывести реальные параметры на своём портале.

<?php

/**
 * Получает dialogId из параметров виджета.
 */
function fetchDialogIdFromPlacement(): string
{
    $options = fetchPlacementOptions();

    return (string) ($options['dialogId'] ?? '');
}

$dialog_id = fetchDialogIdFromPlacement();

echo $dialog_id;

Background worker

PAGE_BACKGROUND_WORKER — невидимый виджет, который загружается на страницах Bitrix24. Его нужно использовать аккуратно: тяжёлый обработчик может замедлять интерфейс.

BX24.callMethod(
    'placement.bind',
    {
        PLACEMENT: 'PAGE_BACKGROUND_WORKER',
        HANDLER: 'https://example.com/bitrix24/background-worker.php',
        OPTIONS: {
            errorHandlerUrl: 'https://example.com/bitrix24/background-worker-error.php'
        }
    },
    function (result) {
        if (result.error()) {
            console.error(result.error());
            return;
        }

        console.log('Background worker registered');
    }
);

В таком обработчике лучше не выполнять тяжёлые запросы сразу при загрузке. Безопаснее сначала быстро загрузить минимальный JS, а основную работу запускать только при нужном условии.

• Официальная документация: механизм встройки виджетов
• Официальная документация: placement.bind
• Официальная документация: placement.unbind
• CRM: пункт контекстного меню в списке элементов
• CRM: пункт выпадающего меню над списком элементов
• CRM: вкладка в детальной карточке элемента
• CRM: кнопка над таймлайном карточки элемента
• CRM: пункт выпадающего меню верхней кнопки карточки элемента
• CRM: пункт контекстного меню дела в карточке элемента
• CRM: пункт выпадающего меню генератора документов
• CRM: пункт выпадающего меню верхней кнопки дизайнера роботов
• CRM: пункт выпадающего меню в туннелях продаж
• CRM: пункт левого меню CRM-аналитики
• CRM: пункт выпадающего меню верхней кнопки CRM-аналитики
• Задачи: пункт контекстного меню списка
• Задачи: вкладка в карточке задачи
• Задачи: правая панель карточки задачи
• Задачи: ссылка в верхней части карточки задачи
• Задачи: пункт основного выпадающего меню
• Задачи: пункт меню около настроек роботов
• Рабочие группы: пункт основного выпадающего меню проекта
• Рабочие группы: пункт выпадающего меню над списком задач
• Рабочие группы: пункт меню около настроек роботов
• Профиль пользователя: пункт контекстного меню в профиле
• Профиль пользователя: пункт контекстного меню верхней кнопки профиля
• Календарь: виджет в календаре
• Телефония: вкладка в карточке звонка
• Телефония: пункт меню в аналитике звонков
• Телефония: WebRTC
• Мессенджер: виджет над полем ввода
• Мессенджер: виджет для сайдбара
• Мессенджер: пункт контекстного меню сообщения
• Мессенджер: коллекция смайлов
• Контакт-центр: виджет в контакт-центре
• Универсальные виджеты: виджет в виде ссылки со слайдером
• Универсальные виджеты: невидимый виджет на каждой странице
• Пользовательские поля: регистрация нового типа пользовательских полей