Виджеты

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

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