Розробка кастомних уявлень списків Бітрікс24

Розробка користувацьких представлень списків у Bitrix24

Стандартні представлення списків у Bitrix24 — канбан та плоска таблиця. Для більшості задач цього досить. Але коли потрібно показати ієрархію завдань як діаграму Ганта, вивести угоди на карті за адресами клієнтів або відобразити запити в календарному виді — вбудованих представлень немає. Користувацьке представлення вирішує задачу візуалізації даних у форматі, зручному для конкретного бізнес-процесу.

Механізм вбудовування

Користувацьке представлення списку реалізується через 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 Bitrix24 повертає максимум 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 (якщо підключена B24 Push)

Оцінка трудомісткості

Основний ризик — не UI, а продуктивність при великих обсягах даних. Прототипуйте на реальному обсязі: якщо в CRM 20 000 угод, представлення має працювати з 20 000 угодами, а не з тестовими 50.