Entity Selector в Битрикс24: выбор сотрудников и отделов в своей форме

При разработке собственных форм в Битрикс24 часто нужен выбор ответственного сотрудника или подразделения. Можно сделать обычный выпадающий список, но тогда поиск, загрузку данных и отображение структуры компании придётся реализовывать самостоятельно.

Для таких задач в Битрикс есть Entity Selector — штатный интерфейс выбора сущностей. Рассмотрим, как открыть диалог, получить выбранного сотрудника и записать его ID в поле формы.

Примеры рассчитаны на PHP-страницу или шаблон коробочного Битрикс24 с подключённым прологом. Это не пример для облачного REST-приложения. Доступность провайдеров зависит от модулей и версии портала; код нужно проверить на своей установке.

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

Для работы с диалогом подключим расширение ui.entity-selector:

<?php

use Bitrix\Main\UI\Extension;

Extension::load('ui.entity-selector');

После подключения станет доступен JavaScript-класс BX.​UI.​EntitySelector.​Dialog.

Данные для диалога могут задаваться вручную или загружаться через провайдеры. Для сотрудников воспользуемся стандартной сущностью user — собственный обработчик поиска для этого не понадобится.

Выбор сотрудника

Добавим в форму скрытое поле для ID сотрудника, подпись и две кнопки:

<div id="responsible-selector">
    <input
        type="hidden"
        name="RESPONSIBLE_ID"
        data-role="value"
        value=""
    >

    <span data-role="title" aria-live="polite">
        Сотрудник не выбран
    </span>

    <button type="button" data-role="select">
        Выбрать сотрудника
    </button>

    <button type="button" data-role="clear">
        Очистить
    </button>
</div>

Теперь создадим диалог и свяжем его состояние с полем формы:

BX.ready(() => {
    const container = document.getElementById('responsible-selector');
    const input = container.querySelector('[data-role="value"]');
    const title = container.querySelector('[data-role="title"]');
    const selectButton = container.querySelector('[data-role="select"]');
    const clearButton = container.querySelector('[data-role="clear"]');

    const syncSelection = (event) => {
        const [item] = event.getTarget().getSelectedItems();

        input.value = item ? String(item.getId()) : '';
        title.textContent = item
            ? item.getTitle()
            : 'Сотрудник не выбран';
    };

    const dialog = new BX.UI.EntitySelector.Dialog({
        targetNode: selectButton,
        context: 'CUSTOM_FORM_RESPONSIBLE',
        width: 400,
        height: 300,
        multiple: false,
        enableSearch: true,
        hideOnSelect: true,

        entities: [
            {
                id: 'user',
                options: {
                    inviteEmployeeLink: false
                }
            }
        ],

        events: {
            'Item:onSelect': syncSelection,
            'Item:onDeselect': syncSelection
        }
    });

    selectButton.addEventListener('click', () => {
        dialog.show();
    });

    clearButton.addEventListener('click', () => {
        dialog.deselectAll();
    });
});

При нажатии на кнопку откроется диалог с поиском сотрудников. После выбора имя появится рядом с кнопкой, а ID попадёт в RESPONSIBLE_ID.

Диалог создаётся один раз, а при следующих нажатиях повторно открывается через show(). Это позволяет сохранить его текущее состояние и не создавать лишние экземпляры.

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

targetNode задаёт элемент, около которого откроется диалог. multiple: false ограничивает выбор одним сотрудником, а hideOnSelect: true закрывает окно после выбора. enableSearch: true включает строку поиска. context разделяет историю последних выбранных элементов между сценариями. Например, для выбора ответственного и согласующего можно использовать разные контексты. Это не сохранение значения формы — записывать ответственного в свою сущность нужно отдельно.

Опция inviteEmployeeLink: false скрывает ссылку приглашения сотрудника.

Получение значения и очистка

Метод getSelectedItems() возвращает массив выбранных элементов. Поскольку множественный выбор отключён, в примере используется только первый элемент:

const [item] = dialog.getSelectedItems();

if (item) {
    console.log(item.getId());
    console.log(item.getTitle());
    console.log(item.getEntityId());
}

У элемента есть не только ID, но и идентификатор сущности. Это важно, если один диалог позволяет выбирать разные типы данных: сотрудник с ID 15 и отдел с ID 15 — разные элементы.

Для синхронизации формы мы подписались на два события:

  • Item:onSelect — элемент выбран;
  • Item:onDeselect — выбор снят.

В обоих случаях обработчик заново получает текущее состояние диалога. Поэтому после очистки скрытое поле не будет содержать ID ранее выбранного сотрудника.

Кнопка «Очистить» вызывает deselectAll(), а обновление подписи и поля происходит через тот же обработчик событий.

Выбор отдела вместо сотрудника

Для выбора подразделения используется сущность department.

В конфигурации предыдущего диалога заменим entities и зададим отдельный контекст:

context: 'CUSTOM_FORM_DEPARTMENT',

entities: [
    {
        id: 'department',
        options: {
            selectMode: 'departmentsOnly'
        }
    }
],

Режим departmentsOnly включает выбор именно подразделений. Простая замена user на department без указания режима не равнозначна этой настройке: провайдер структуры компании также используется для выбора сотрудников через дерево отделов.

В разметке изменим имя скрытого поля на DEPARTMENT_ID, текст кнопки — на «Выбрать отдел», а пустую подпись в HTML и JavaScript — на «Отдел не выбран».

Остальная логика остаётся прежней: получаем выбранный элемент, записываем его ID и показываем название.

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

46