Каталог объектов ui.entity-catalog

Каталог объектов показывает всплывающее окно с двумя колонками: слева список групп, справа карточки элементов выбранной группы. У каждой карточки есть заголовок, описание и кнопка действия.

Каталог применяют там, где пользователь выбирает один объект из большого набора: шаблон документа, робота для автоматизации, роль помощника. Группы и описания помогают сориентироваться, когда элементов много и по одному названию их не различить.

Расширение только отрисовывает переданные данные и сообщает о действиях пользователя. Запросы к серверу оно не отправляет: обработчики нажатий пишет разработчик.

В Bitrix Framework за каталог объектов отвечает расширение ui.entity-catalog. Оно экспортирует класс и два вспомогательных объекта:

• EntityCatalog — сам каталог: хранит группы и элементы, создает окно и перерисовывает содержимое.

• Stubs — готовые заглушки для пустых состояний.

• States — доступ к состоянию каталога: текущая группа, строка поиска, признак примененных фильтров.

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

Если вы подключаете каталог из PHP, загрузите расширение ui.entity-catalog.

\Bitrix\Main\UI\Extension::load('ui.entity-catalog');

Вместе с расширением подключаются его зависимости: main.core, main.core.events, main.popup, ui.advice, ui.cnt, ui.feedback.form, ui.forms, ui.icons, ui.vue3, ui.vue3.components.counter, ui.vue3.components.hint и ui.vue3.pinia. Загружать их отдельно не нужно.

Если вы работаете в модульном JavaScript, импортируйте класс EntityCatalog из ui.entity-catalog.

import { EntityCatalog } from 'ui.entity-catalog';

Вне модульного JavaScript класс доступен как BX.UI.EntityCatalog, а вспомогательные объекты — как BX.UI.Stubs и BX.UI.States.

Когда каталог нужен не сразу, а по нажатию кнопки, загрузите расширение методом Runtime.loadExtension(). Он возвращает промис с экспортами расширения.

Пример. Расширение загружается в момент открытия каталога, а не вместе со страницей.

import { Runtime } from 'main.core';

const { EntityCatalog } = await Runtime.loadExtension('ui.entity-catalog');

Серверной части у расширения нет: ни класса, ни компонента. Группы и элементы разработчик готовит сам и передает в JavaScript.

Собрать каталог объектовСобрать каталог объектов

Чтобы показать каталог, выполните основные действия:

1. Создайте экземпляр EntityCatalog. Передайте группы в параметре groups, а элементы — в параметре items.

2. Свяжите элементы с группами. Каждый элемент перечисляет идентификаторы своих групп в поле groupIds.

3. Вызовите метод show(). Он собирает содержимое каталога и показывает окно.

Пример. Каталог шаблонов документов открывается с двумя группами и тремя шаблонами. Группа «Акты» выбрана заранее, поэтому пользователь сразу видит ее содержимое.

import { EntityCatalog } from 'ui.entity-catalog';

const catalog = new EntityCatalog({
    title: 'Шаблоны документов',
    groups: [
        { id: 'acts', name: 'Акты', selected: true },
        { id: 'invoices', name: 'Накладные' },
    ],
    items: [
        {
            id: 'act-transfer',
            title: 'Акт приема-передачи',
            description: 'Фиксирует передачу объекта между складами',
            groupIds: ['acts'],
        },
        {
            id: 'act-writeoff',
            title: 'Акт списания',
            description: 'Оформляет списание объекта с остатков',
            groupIds: ['acts'],
        },
        {
            id: 'invoice-internal',
            title: 'Внутренняя накладная',
            description: 'Перемещение между подразделениями',
            groupIds: ['invoices'],
        },
    ],
});

catalog.show();

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

Метод show() каждый раз собирает содержимое заново по текущим группам и элементам, поэтому между вызовами их можно менять.

Передать параметрыПередать параметры

Все параметры конструктора необязательны, кроме самого объекта параметров: без него конструктор завершится ошибкой. Если параметр не передан, каталог использует значение по умолчанию.

type EntityCatalogOptions = {
    groups?: Array;
    items?: Array;
    canDeselectGroups?: boolean;
    showEmptyGroups?: boolean;
    showSearch?: boolean;
    filterOptions?: Object;
    popupOptions?: PopupOptions;
    title?: string;
    customTitleBar?: string | Element;
    slots?: Object;
    customComponents?: Object;
    events?: Object;
};

Описать группуОписать группу

Каждую группу задают объектом данных, а каталог выводит группы списком в левой колонке. Идентификатор группы он сопоставляет с полем groupIds элементов и показывает справа подходящие карточки.

Пример. Значок группы задан встроенным тегом svg.

const group = {
    id: 'acts',
    name: 'Акты',
    icon: '<svg width="20" height="20" viewBox="0 0 20 20"><circle cx="10" cy="10" r="8" fill="#2fc6f6"/></svg>',
};

Подсказку над списком элементов каталог рисует расширением ui.advice — это блок с текстом и аватаром рядом. Достаточно заполнить поле adviceTitle.

Описать элементОписать элемент

Карточка в правой колонке — это и есть то, что выбирает пользователь. Каталог собирает ее из полей объекта данных.

Кнопку карточки описывают объектом из трех полей.

Обработать выбор элементаОбработать выбор элемента

О выборе элемента каталог не сообщает событием. Пользователь нажимает кнопку карточки, и каталог вызывает функцию из поля button.action.

Обработчик получает объект события с двумя полями: в поле eventData лежат данные элемента, в поле originalEvent — исходное событие нажатия. Каталог после нажатия не закрывается, поэтому закрывайте его сами вызовом close().

Пример. Обработчик сохраняет выбранный шаблон и закрывает каталог. Элемент с признаком locked показывает сообщение о недоступности.

const item = {
    id: 'act-writeoff',
    title: 'Акт списания',
    description: 'Оформляет списание объекта с остатков',
    groupIds: ['acts'],
    button: {
        text: 'Выбрать',
        locked: isTemplateLocked,
        action: (event) => {
            if (isTemplateLocked)
            {
                showLockedNotice();

                return;
            }

            applyTemplate(event.getData().eventData.id);
            catalog.close();
        },
    },
};

Разбить группы на блокиРазбить группы на блоки

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

Пример. Первый блок содержит действующие типы документов, второй отделяет от них архив.

const catalog = new EntityCatalog({
    groups: [
        [
            { id: 'acts', name: 'Акты' },
            { id: 'invoices', name: 'Накладные' },
        ],
        [
            { id: 'archive', name: 'Архив' },
        ],
    ],
    items: documentTemplates,
});

Отдельно от блоков работает поле isHeaderGroup. Оно поднимает группу в верхний список над основными группами, и это происходит независимо от того, в каком блоке группа лежит. У заголовочных групп есть еще одно отличие: параметр showEmptyGroups на них не действует, и каталог показывает их даже без элементов.

Остальные группы без элементов каталог по умолчанию скрывает. Чтобы показывать все группы, передайте параметр showEmptyGroups со значением true.

Показать счетчик на группеПоказать счетчик на группе

Справа от названия группы каталог может показать цветную метку с числом. Значение он берет из поля customData.counterValue и выводит метку, только если это целое число больше нуля.

Пример. Группа «Недавние» открывается со счетчиком новых шаблонов.

const group = {
    id: 'recent',
    name: 'Недавние',
    isHeaderGroup: true,
    customData: {
        counterValue: 3,
    },
};

Когда каталог уже открыт, меняйте счетчик методом updateGroupCounter(). Он принимает идентификатор группы и новое значение. Ноль скрывает метку.

catalog.updateGroupCounter('recent', 0);

Собрать группу «Недавние»Собрать группу «Недавние»

Готовой группы недавних элементов у каталога нет. Соберите ее как обычную группу: пометьте полем isHeaderGroup, храните идентификаторы последних выбранных элементов на своей стороне и добавляйте идентификатор группы в поле groupIds этих элементов.

Порядок внутри группы задает функция compare. Каталог передает ее в сортировку массива элементов.

Пример. Функция расставляет элементы по порядку, который хранится в карте недавних.

const recentGroup = {
    id: 'recent',
    name: 'Недавние',
    isHeaderGroup: true,
    compare: (firstItem, secondItem) => {
        return (recentSort.get(firstItem.id) ?? 0) - (recentSort.get(secondItem.id) ?? 0);
    },
};

Включить поискВключить поиск

Параметр showSearch добавляет в шапку окна поле поиска. Пользователь нажимает на значок, поле раскрывается, и каталог ищет через 255 миллисекунд после последнего нажатия клавиши.

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

Совпадение каталог ищет по трем полям элемента.

Если ничего не нашлось, каталог показывает готовую заглушку. Свой текст для нее задают слотом SLOT_MAIN_CONTENT_SEARCH_NOT_FOUND.

Отфильтровать элементыОтфильтровать элементы

Кнопка фильтра появляется в шапке окна, когда задан хотя бы один вариант. По нажатию она открывает меню, где каждый вариант описан функцией проверки элемента.

Фильтры задают параметром filterOptions. Поле filterItems принимает список вариантов, поле multiple разрешает применять несколько вариантов сразу. Со значением false новый выбранный вариант отменяет предыдущий.

Пример. Два варианта делят шаблоны на действующие и архивные, и одновременно работает только один.

const catalog = new EntityCatalog({
    groups: documentGroups,
    items: documentTemplates,
    filterOptions: {
        multiple: false,
        filterItems: [
            {
                id: 'active',
                text: 'Действующие',
                action: (item) => item.customData?.archived === false,
                applied: true,
            },
            {
                id: 'archived',
                text: 'Архивные',
                action: (item) => item.customData?.archived === true,
                applied: false,
            },
        ],
    },
});

В меню фильтра каталог всегда добавляет пункт «Сброс фильтра». Он снимает все примененные варианты.

Фильтры работают вместе с поиском: каталог сначала отбирает элементы по строке запроса, затем применяет к результату функции фильтров.

Настроить окно каталогаНастроить окно каталога

Окно каталога — это всплывающее окно расширения main.popup. Параметр popupOptions принимает те же настройки и накладывает их поверх значений каталога.

Размер окна каталог всегда разрешает менять мышью, а значения minWidth и minHeight не дают уменьшить его сверх заданного предела.

Пример. Настройка overlay включает затемнение под окном, а обработчик onPopupClose срабатывает при его закрытии.

const catalog = new EntityCatalog({
    title: 'Шаблоны документов',
    groups: documentGroups,
    items: documentTemplates,
    popupOptions: {
        overlay: true,
        width: 900,
        events: {
            onPopupClose: () => {
                saveCatalogState();
            },
        },
    },
});

Заголовок окна задают параметром title. Если простого текста мало, передайте в параметре customTitleBar разметку строкой или готовый DOM-узел — он встанет вместо заголовка, а поле поиска, кнопка фильтра и кнопка закрытия останутся на своих местах.

Метод getPopup() возвращает объект окна. Через него подписываются на события окна и обращаются к его методам.

catalog.getPopup().subscribe('onAfterShow', () => {
    sendOpenAnalytics();
});

Расширить каталог своим кодомРасширить каталог своим кодом

Каталог собран на Vue 3 — библиотеке для сборки интерфейса из компонентов. Почти любую его часть можно заменить своей разметкой, а своему компоненту — дать доступ к состоянию каталога.

Заменить части каталога своими компонентамиЗаменить части каталога своими компонентами

Части каталога заменяют через слоты. Параметр slots принимает объект, где ключ — константа класса EntityCatalog, а значение — строка с шаблоном Vue.

Слот карточки получает данные элемента в переменной itemSlotProps, слот группы — данные группы и обработчик нажатия в переменной groupSlotProps. Если вы заменяете группу в списке целиком, повесьте на свою разметку groupSlotProps.handleClick: без него выбор группы работать не будет.

Пример. Группа в списке заменена своей разметкой, и нажатие по ней по-прежнему выбирает группу.

slots: {
    [EntityCatalog.SLOT_GROUP]: `
        <li class="document-catalog__group" @click="groupSlotProps.handleClick">
            {{ groupSlotProps.groupData.name }}
        </li>
    `,
},

Свои компоненты регистрируют параметром customComponents. Каталог добавляет их в приложение, и после этого их можно вызывать в шаблонах слотов.

Пример. Карточка элемента заменена своим компонентом, которому передаются произвольные данные элемента.

const catalog = new EntityCatalog({
    groups: documentGroups,
    items: documentTemplates,
    customComponents: {
        TemplatePreview,
    },
    slots: {
        [EntityCatalog.SLOT_MAIN_CONTENT_ITEM]: '<TemplatePreview :item="itemSlotProps.itemData" />',
        [EntityCatalog.SLOT_MAIN_CONTENT_HEADER]: '<div class="document-catalog__hint">Выберите шаблон документа</div>',
    },
});

Кроме своих компонентов, в шаблонах слотов доступны два готовых инструмента. Компонент Hint рисует значок со всплывающей подсказкой: текст задают свойством text, сторону появления — свойством position. Директива v-feedback открывает форму обратной связи по нажатию и принимает параметры формы значением — те же, что метод Form.open() расширения ui.feedback.form.

Пример. Под списком элементов встает значок подсказки, а всплывающий текст появляется сверху от него.

slots: {
    [EntityCatalog.SLOT_MAIN_CONTENT_FOOTER]: '<Hint text="Шаблон подставится в новый документ" position="top" />',
},

Подробнее о работе с Vue в Bitrix Framework читайте в статье Vue.js.

Показать свою заглушкуПоказать свою заглушку

Когда показать справа нечего, каталог выбирает одно из пяти состояний и отдает его слоту. Проверка идет сверху вниз, работает первое подходящее состояние.

Первые два состояния своего оформления не имеют: пока вы не передали слот, правая колонка остается пустой.

Заглушку фильтров каталог показывает, только когда задан слот SLOT_MAIN_CONTENT_FILTERS_STUB_TITLE. Без него отработает следующее подходящее состояние.

Если менять нужно только текст, берите слоты, у которых в таблице слотов указано «Только текст». Каталог подставит значение в свою рамку со значком, и свой компонент не понадобится.

Пример. Пустая группа сообщает, что шаблонов этого типа еще нет.

slots: {
    [EntityCatalog.SLOT_MAIN_CONTENT_EMPTY_GROUP_STUB_TITLE]: 'Шаблонов этого типа пока нет',
},

Когда заглушку собирают своим компонентом, ту же рамку со значком берут из объекта Stubs: он отдает ее компонентом EmptyContent.

Читать состояние каталогаЧитать состояние каталога

Свой компонент внутри слота не получает состояние каталога через параметры. Объект States отдает функцию useGlobalState — хранилище, из которого компонент читает текущее состояние.

Пример. Заглушка пустой группы показывает разный текст для группы недавних и для остальных групп.

import { Stubs, States } from 'ui.entity-catalog';
import { mapState } from 'ui.vue3.pinia';

export const EmptyTemplatesStub = {
    name: 'empty-templates-stub',
    components: {
        EmptyContent: Stubs.EmptyContent,
    },
    computed: {
        isRecentGroup()
        {
            return this.currentGroup?.id === 'recent';
        },
        ...mapState(States.useGlobalState, ['currentGroup']),
    },
    template: `
        <EmptyContent>
            <span v-if="isRecentGroup">Вы еще не выбирали шаблоны</span>
            <span v-else>Шаблонов этого типа пока нет</span>
        </EmptyContent>
    `,
};

Готовый компонент зарегистрируйте в параметре customComponents и вызовите в нужном слоте.

const catalog = new EntityCatalog({
    groups: documentGroups,
    items: documentTemplates,
    customComponents: {
        EmptyTemplatesStub,
    },
    slots: {
        [EntityCatalog.SLOT_MAIN_CONTENT_EMPTY_GROUP_STUB]: '<EmptyTemplatesStub />',
    },
});

Обновить данные каталогаОбновить данные каталога

Данные каталога меняют и после создания: элементы приходят с сервера, счетчики растут, состав групп зависит от действий пользователя. Методы изменения работают всегда, но перерисовывают открытый каталог по-разному.

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

Пример. Каталог открывается, когда шаблоны уже загружены.

loadTemplates().then((templates) => {
    catalog.setItems(templates);
    catalog.show();
});

Пример. Шаблон помечается архивным. Метод принимает идентификатор элемента и объект с новыми значениями полей.

catalog.updateItemById('act-writeoff', {
    customData: { archived: true },
});

Закрыть каталогЗакрыть каталог

Метод close() закрывает окно и удаляет содержимое каталога. Метод isShown() сообщает, открыто ли окно сейчас.

Отдельных методов скрытия и уничтожения у каталога нет: метод close() выполняет обе задачи.

Подписаться на событияПодписаться на события

Каталог бросает события через EventEmitter из расширения main.core.events. Пространство имен событий — BX.UI.EntityCatalog.

Обработчики задают в параметре events конструктора.

const catalog = new EntityCatalog({
    groups: documentGroups,
    items: documentTemplates,
    events: {
        onItemsRendered: () => {
            trackVisibleTemplates();
        },
    },
});

Тот же обработчик добавляют методом subscribe() уже созданному каталогу.

catalog.subscribe('onItemsRendered', () => {
    trackVisibleTemplates();
});

Других событий у каталога нет. Выбор элемента обрабатывают функцией button.action, а выбранную группу читают из состояния каталога.

Связанные материалыСвязанные материалы

• Всплывающие окна и меню main.popup — окно каталога и меню фильтра.

• Диалог выбора объектов ui.entity-selector — выбор объектов через провайдеры данных.

• Vue.js — компоненты и шаблоны для слотов каталога.

• Иконки — наборы значков для поля icon группы.

• Расширения — подключение JavaScript-расширений Bitrix Framework.