Создание поля ввода с поиском и выбором значений из списка

Подключение

JS (ES6)

import { FieldSelector } from 'ui.field-selector';

const selector = new FieldSelector({
    containerId: 'field-selector-container',
    fieldName: 'selected_id',
    multiple: true,
    collectionType: 'int',
    entities: [
        {
            id: 'users',
            options: { enableSearch: true }
        }
    ],
    selectedItems: [['users', 123]]
});

selector.render();

JS (ES5)

var FieldSelector = require('ui.field-selector').FieldSelector;

var selector = new FieldSelector({
    containerId: 'field-selector-container',
    fieldName: 'selected_id',
    multiple: true,
    collectionType: 'int',
    entities: [
        {
            id: 'users',
            options: { enableSearch: true }
        }
    ],
    selectedItems: [['users', 123]]
});

selector.render();

PHP

<?php
use Bitrix\Main\UI\Extension;
// Подключаем расширение
Extension::load('ui.field-selector');
$containerId = 'field-selector-container';
?>
<div id="<?= $containerId ?>"></div>
<script>
function () {
    const selector = new BX.UI.FieldSelector({
        containerId: '<?= $containerId ?>',
        fieldName: 'selected_id',
        multiple: false,
        collectionType: 'int',
        entities: [
            {
                id: 'crm_contact',
                options: { enableSearch: true }
            }
        ],
        selectedItems: [['crm_contact', 456]]
    });
    selector.render();
})();
</script>

Параметры конструктора FieldSelectorConfig

Конфигурация передается в конструктор класса FieldSelector. Все параметры, кроме отмеченных как опциональные, обязательны.

Методы класса FieldSelector

Примеры использования

Базовое использование — одиночный выбор контакта CRM

Минимальная конфигурация: достаточно указать контейнер, имя поля и тип сущности.

new BX.UI.FieldSelector({
    containerId: 'contact-selector',
    fieldName: 'contact_id',
    multiple: false,
    collectionType: 'int',
    entities: [{ id: 'crm_contact' }]
}).render();

Множественный выбор с предустановленными значениями

Передаем массив выбранных элементов. Указываем fieldName с [] для корректной передачи в PHP.

const selector = new BX.UI.FieldSelector({
    containerId: 'user-selector',
    fieldName: 'user_ids[]',
    multiple: true,
    collectionType: 'int',
    entities: [{ id: 'users' }],
    selectedItems: [
        ['users', 101],
        ['users', 102]
    ]
});

selector.render();

Реагирование на изменения через события

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

const selector = new BX.UI.FieldSelector({
    containerId: 'tag-selector',
    fieldName: 'tag_ids[]',
    multiple: true,
    collectionType: 'int',
    entities: [{ id: 'tags' }],
    changeEvents: ['onTagsChanged']
});

selector.render();

BX.EventEmitter.subscribe('onTagsChanged', function() {
    const values = selector.getValues();
    console.log('Текущие теги:', values);
});

Программное обновление значений

Можно вручную устанавливать значения через setValues и обновлять DOM.

// Добавляем новый элемент
function addItem(entityId, value)
{
    const current = selector.getValues();
    current.push([entityId, value]);
    selector.setValues(current);
    selector.renderSelectedItems(current);
}

// Использование
addItem('users', 999);

Контрол для выборки сотрудников

Выбор сотрудников из структуры компании с возможностью просмотра отделов.

$userOptions = [
    'collabers' => false,
    'intranetUsersOnly' => true,
    'emailUsers' => false,
    'inviteEmployeeLink' => false,
];

$entities = [
    [
        'id' => 'user',
        'dynamicLoad' => true,
        'dynamicSearch' => true,
        'options'=> $userOptions,
    ],
    [
        'id' => 'structure-node',
        'dynamicLoad' => true,
        'dynamicSearch' => true,
        'options'=> [
            'selectMode' => 'usersOnly',
            'flatMode' => false,
            'fillRecentTab' => false,
            'restricted' => 'view',
            'includedNodeEntityTypes' => ['department'],
            'useMultipleTabs' => false,
            'userOptions' => $userOptions,
        ],
    ],
];

$entityValues = [
    [
        'user', 12
    ],
    [
        'user', 14
    ],
];

$multiple = true;
$config = \Bitrix\Main\Web\Json::encode([
    'containerId' => 'doc-selector',
    'fieldName' => 'EMPLOYEE' . ($multiple ? '[]' : ''),
    'context' => null,
    'multiple' => $multiple,
    'collectionType' => 'int',
    'selectedItems' => $entityValues,
    'entities' => $entities,
]);

\Bitrix\Main\UI\Extension::load('ui.field-selector');

return <<<HTML
    <div id="doc-selector"></div>
    <script>
    (function() {
        const selector = new BX.UI.FieldSelector({$config});
        selector.render();
    })();
    </script>
    HTML
;

Кастомизация вкладки поиска

Можно задать заголовок и подзаголовок, чтобы улучшить UX.

new BX.UI.FieldSelector({
    containerId: 'doc-selector',
    fieldName: 'doc_id',
    multiple: false,
    collectionType: 'int',
    entities: [{ id: 'documents' }],
    searchMessages: {
        title: 'Найти документ',
        subtitle: 'Введите название или номер'
    }
}).render();

Дополнительная информация

• Не требуется вручную управлять hidden-полями, синхронизацией или событиями — все делается автоматически.
• Тип collectionType определяет, какие значения считаются валидными:
  • 'int' — только положительные целые числа.
  • 'string' — непустые строки.
• При multiple: false диалог закрывается после выбора элемента.
• Метод renderSelectedItems полностью заменяет содержимое контейнера результатов — дублирования не происходит.
• Если containerId не найден в DOM, инициализация прерывается с ошибкой в консоли.