Разработка кастомных представлений списков Битрикс24

Разработка кастомных представлений списков Битрикс24

Стандартные представления списков в Битрикс24 — канбан и плоская таблица. Для большинства задач этого хватает. Но когда нужно показать иерархию задач в виде диаграммы Ганта, вывести сделки на карте по адресам клиентов или отобразить заявки в календарном виде — встроенных представлений нет. Кастомное представление решает задачу визуализации данных в формате, удобном для конкретного бизнес-процесса.

Механизм встраивания

Кастомное представление списка реализуется через REST-приложение, встроенное в интерфейс Б24 через placement. Для списков CRM-сущностей доступны:

• CRM_DEAL_LIST_TOOLBAR — кнопка в панели инструментов списка сделок
• CRM_ANALYTICS_TOOLBAR — встраивание в аналитику CRM
• REST_APP_URI — полноэкранное приложение как отдельный раздел

Для полноценного кастомного представления лучше использовать отдельный раздел в левом меню (LEFT_MENU placement) или встраивание как табы внутри существующего раздела через GRID_TOOLBAR.

Логика работы: приложение загружается в iframe, получает контекст авторизации, запрашивает данные через REST API (crm.deal.list, crm.item.list, tasks.task.list) и рендерит их в своём формате.

Три типовых кастомных представления

1. Карта. Сделки или контакты с адресами отображаются маркерами на Яндекс.Картах или Leaflet. Кликабельные маркеры открывают карточку сущности через BX24.openPath('/crm/deal/details/{id}/').

Данные для карты: REST-запрос crm.deal.list с выборкой полей ID, TITLE, UF_CRM_ADDRESS, STAGE_ID, OPPORTUNITY. Геокодирование адресов — на вашем бэкенде через API геокодера, результаты кэшируются, чтобы не перекодировать при каждом открытии.

2. Календарь. Элементы с датами (дедлайн сделки, дата события в смарт-процессе) отображаются в месячном/недельном виде. Библиотека FullCalendar интегрируется за 1–2 дня. Drag-and-drop для переноса даты → вызов crm.deal.update с новой датой.

3. Диаграмма Ганта. Задачи или этапы проекта с зависимостями. Каждый элемент — отрезок от DATE_START до DATE_END. Библиотеки: DHTMLX Gantt (платная, полнофункциональная) или Frappe Gantt (open source, базовая). Данные из tasks.task.list или кастомного смарт-процесса.

Работа с большими списками

REST API Битрикс24 отдаёт максимум 50 элементов за запрос. Для представления, показывающего сотни элементов одновременно (карта с маркерами, Гант с задачами), нужна пагинация.

Оптимальная стратегия — параллельные batch-запросы:

// Получаем total из первого запроса
BX24.callMethod('crm.deal.list', {
    select: ['ID', 'TITLE', 'UF_CRM_ADDRESS'],
    filter: {'STAGE_SEMANTIC_ID': 'P'}
}, function(result) {
    var total = result.total();
    var pages = Math.ceil(total / 50);

    // Формируем batch из параллельных запросов
    var batch = {};
    for (var i = 0; i < pages; i++) {
        batch['page_' + i] = ['crm.deal.list', {
            select: ['ID', 'TITLE', 'UF_CRM_ADDRESS'],
            filter: {'STAGE_SEMANTIC_ID': 'P'},
            start: i * 50
        }];
    }
    BX24.callBatch(batch, renderAll);
});

Лимит batch: до 50 команд в одном batch-запросе. Для списков в 5000+ элементов batch-запросы отправляются последовательными пачками. На практике 2500 сделок загружаются за 3–5 секунд через batch.

Фильтрация и синхронизация с основным фильтром

Критически важно: кастомное представление должно учитывать фильтры, установленные пользователем в стандартном интерфейсе. Проблема в том, что iframe-приложение не имеет прямого доступа к состоянию фильтра Б24.

Два подхода:

• Свой фильтр. Реализуете фильтрацию внутри приложения. Пользователь настраивает фильтры в вашем UI, они транслируются в параметр filter REST-запроса. Проще в реализации, но пользователь работает с двумя разными фильтрами.
• Передача контекста. Через BX24.placement.info() можно получить базовый контекст (ID сущности, тип). Для полноценной передачи фильтра используйте промежуточный обработчик: пользователь нажимает кнопку «Показать на карте» в toolbar-placement, приложение считывает текущие GET-параметры страницы (где закодирован фильтр) и применяет их.

Кэширование на клиенте

Для представлений, которые открываются часто (карта территорий, Гант проекта), реализуйте кэш в IndexedDB браузера. Схема:

1. При первом открытии — полная загрузка данных через REST, сохранение в IndexedDB с меткой времени
2. При повторном открытии — рендеринг из кэша, фоновый запрос на обновление
3. Инвалидация кэша — по таймеру (каждые 5 минут) или по событию через WebSocket (если подключён BX24 Push)

Оценка трудозатрат

Основной риск — не UI, а производительность при больших объёмах данных. Прототипируйте на реальном объёме: если в CRM 20 000 сделок, представление должно работать с 20 000 сделками, а не с тестовыми 50.