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 и показываем название.
Если в форме одновременно нужны сотрудник и отдел, создавайте два отдельных поля и два диалога. Так идентификаторы разных сущностей не смешаются.