Показать диалог множественного выбора пользователей BX24.selectUsers

BX24.selectUsers(callback: callable): void;
BX24.selectUsers(title: string, callback: callable): void;

Метод BX24.selectUsers показывает стандартный диалог множественного выбора пользователей. Диалог выводит только действующих сотрудников компании: пользователей экстранета и уволенных сотрудников в нем нет.

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

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

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

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

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

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

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

Примеры кодаПримеры кода

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

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

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

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

BX24.init(() => {
    BX24.selectUsers((selected) => {
        const ids = selected.map((user) => Number(user.id));

        // пустой выбор не затирает сохраненные идентификаторы
        if (ids.length === 0)
        {
            return;
        }

        BX24.userOption.set('assignees', ids.join(','));
    });
});

Получить карточки выбранных сотрудников методом user.get и собрать ссылки на аватары. Методу нужен один из скоупов user, user_brief или user_basic. За один запрос user.get отдает не больше 50 записей — если сотрудников выбрали больше, дочитайте остальные методом next() результата:

BX24.init(() => {
    BX24.selectUsers((selected) => {
        if (selected.length === 0)
        {
            return;
        }

        const ids = selected.map((user) => Number(user.id));
        const avatars = {};

        selected.forEach((user) => {
            avatars[user.id] = user.photo
                ? 'https://' + BX24.getDomain() + user.photo
                : '';
        });

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

            result.data().forEach((employee) => {
                console.log(employee.EMAIL, avatars[employee.ID]);
            });
        });
    });
});

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

Диалог не возвращает данные напрямую: результат выбора приходит в функцию callback массивом объектов.

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

Порядок объектов в массиве не зависит от порядка выбора: сотрудники идут по возрастанию идентификатора. Определяйте сотрудника по полю id, а не по позиции в массиве.

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

Пользователь подтвердил пустой выбор:

[]

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

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

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

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

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

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

• Системные диалоги: обзор методов
• Показать диалог одиночного выбора пользователя BX24.selectUser
• Показать диалог выбора прав доступа BX24.selectAccess
• Вызвать диалог выбора объектов CRM BX24.selectCRM
• Вызвать метод REST-сервиса с указанными параметрами BX24.callMethod
• Получить список пользователей по фильтру user.get
• Установить настройки для пользователя BX24.userOption.set