Показать диалог одиночного выбора пользователя BX24.selectUser

Выберите инструмент для разработки с AI-агентом:

  • используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
  • используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации
BX24.selectUser(callback: callable): void;
BX24.selectUser(title: string, callback: callable): void;

Метод BX24.selectUser показывает стандартный диалог одиночного выбора пользователя. Диалог выводит только действующих сотрудников компании, которые состоят хотя бы в одном подразделении. Пользователей экстранета, уволенных сотрудников, приглашенных с неактивированным аккаунтом и служебных пользователей — чат-ботов, почтовых и коннекторных — в нем нет.

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

Состав диалога зависит от того, кто открыл приложение. Если это пользователь экстранета, вкладки с оргструктурой у него нет, а список сотрудников ограничен его рабочими группами.

Собственный scope диалогу не нужен: диалог открывает интерфейс Битрикс24, а не обращается к REST API.

Вызвать метод можно только из приложения, встроенного во фрейм Битрикс24, где подключена библиотека BX24.js.

Вызывайте метод внутри обработчика BX24.init. Сам диалог библиотека до инициализации не откладывает, но функции, которые обычно вызывают из callback, до нее не работают — например, BX24.userOption.set.

Отметить сотрудника заранее или сузить список сотрудников в диалоге нельзя.

Диалог одиночного выбора создается один раз и переиспользуется. При повторном вызове открывается то же окно: в нем отмечен прошлый выбор, а в строке поиска стоит имя выбранного сотрудника. Окно живет на странице портала, поэтому перезагрузка фрейма приложения его не сбрасывает. В приложение выбор не переносится — храните его сами.

Чтобы выбрать нескольких сотрудников, используйте BX24.selectUsers: он показывает тот же диалог с множественным выбором и отдает массив объектов вместо одного объекта.

Параметры метода

Обязательные параметры отмечены *

Название
тип

Описание

title
string

Заголовок диалога в форме вызова с двумя параметрами. Библиотека передает значение в Битрикс24, но диалог его не использует: окно открывается без заголовка. На диалог параметр не влияет, передавать его не нужно

callback*
callable

Функция обратного вызова. Получает один параметр — объект с данными выбранного сотрудника (подробное описание). Если функцию не передать, диалог откроется и закроется по клику, но результат выбора никуда не придет: ошибки при этом не будет

Примеры кода

Как использовать примеры в документации

Показать диалог и вывести выбранного сотрудника:

BX24.init(() => {
    BX24.selectUser((user) => {
        console.log(user.id, user.name);
    });
});

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

BX24.init(() => {
    BX24.selectUser((user) => {
        BX24.userOption.set('assignee', user.id);
    });
});

Получить карточку выбранного сотрудника методом user.get через BX24.callMethod и собрать ссылку на аватар. Методу нужен один из скоупов user, user_brief или user_basic, но в user_brief поле EMAIL не приходит:

BX24.init(() => {
    BX24.selectUser((user) => {
        const avatar = user.photo
            ? 'https://' + BX24.getDomain() + user.photo
            : '';

        BX24.callMethod('user.get', { ID: Number(user.id) }, (result) => {
            if (result.error())
            {
                console.log(result.error());
                return;
            }

            const employee = result.data()[0];

            if (!employee)
            {
                return;
            }

            console.log(employee.EMAIL, employee.WORK_POSITION, avatar);
        });
    });
});

Обработка ответа

Диалог не возвращает данные напрямую: результат выбора приходит в функцию callback объектом. Сам метод возвращает void, поэтому дождаться выбора через await нельзя — работайте с результатом внутри callback.

Функция callback срабатывает по клику на сотрудника, отдельной кнопки подтверждения у диалога нет. Закрыть диалог, ничего не выбрав, можно кликом вне окна — крестика у него нет, и клавиша Esc его не закрывает. В этом случае функция не вызывается: пустого результата у одиночного диалога не бывает.

{
    "id": "12",
    "name": "Мария Петрова",
    "sub": true,
    "sup": false,
    "position": "Менеджер по продажам",
    "photo": "/upload/resize_cache/main/c1c/100_100_2/petrova.jpg",
    "url": ""
}

Сотрудник без должности и фотографии:

{
    "id": "7",
    "name": "Иван Иванов",
    "sub": false,
    "sup": false,
    "position": null,
    "photo": "",
    "url": ""
}

Возвращаемые данные

Название
тип

Описание

id
string

Идентификатор сотрудника. Приходит строкой — приводите значение к числу для методов Битрикс24, где нужен USER_ID

name
string

Имя сотрудника, отформатированное по настройкам Битрикс24

sub
boolean

true, если сотрудник работает в подразделении, которое подчинено текущему пользователю

sup
boolean

true, если сотрудник руководит подразделением текущего пользователя или любым вышестоящим подразделением

position
string

Должность сотрудника. Если должность не заполнена, приходит пустая строка или null — проверяйте значение на истинность

photo
string

Путь к уменьшенной копии аватара сотрудника относительно адреса Битрикс24, а не адреса приложения. Чтобы получить рабочую ссылку, соберите ее из https://, домена из BX24.getDomain и этого пути. Если фотографии нет, приходит пустая строка

url
string

Ссылка на профиль сотрудника. В диалоге приложения всегда приходит пустой строкой

Кроме id, поля диалог отдает для вывода в интерфейсе приложения — актуальные данные о сотруднике возвращает user.get.

Обработка ошибок

Кодов ошибок диалог не возвращает. Случай, когда результата нет, разобран в блоке Обработка ответа.

Единственная ошибка появляется до вызова диалога. Библиотека берет адрес портала и идентификатор сессии приложения из window.name, который проставляет Битрикс24. Если страница открыта не во фрейме приложения Битрикс24, при загрузке скрипта библиотеки возникает исключение с текстом Unable to initialize Bitrix24 JS library!, а объект BX24 обнуляется. Перехватывайте исключение там, где подключаете библиотеку: продолжить работу с ней после этого нельзя.

Продолжите изучение

Предыдущая
Обзор методов
Следующая
Показать диалог множественного выбора пользователей