Розробка UI-компонентів Bitrix24 UI Kit (React)

Розробка UI-компонентів на Bitrix24 UI Kit (React)

Застосунки для порталу Бітрікс24, що виглядають «чужорідно» — окрема проблема. Власні шрифти, нестандартні кнопки, саморобні модалки — користувачі сприймають такі застосунки як зовнішній сервіс, а не частину робочого інструменту. Bitrix24 UI Kit вирішує це завдання: набір React-компонентів, які точно відтворюють візуальну мову Бітрікс24, включно з підтримкою темної теми та RTL-локалей.

Структура Bitrix24 UI Kit

Офіційний пакет @bitrix24/b24jssdk містить TypeScript SDK для REST API. UI-компоненти в екосистемі Бітрікс24 постачаються двома способами: через BX.UI.* у бітрікс-шаблонах (vanilla JS) та через React-компоненти у @bitrix24/b24ui для застосунків.

Набір базових компонентів:

import {
  Button, ButtonSize, ButtonColor,
  Input, InputSize,
  Select, SelectSize,
  Table, TableColumn,
  Badge, BadgeColor,
  Modal, ModalSize,
  Notification, NotificationType,
  Avatar, AvatarSize,
  Chip, ChipColor,
} from '@bitrix24/b24ui';

Компоненти використовують CSS-змінні з теми порталу. При зміні теми (світла/темна) всі компоненти оновлюються автоматично без додаткової логіки.

Налаштування та ініціалізація теми

import { B24ThemeProvider, useB24Theme } from '@bitrix24/b24ui';

function App() {
  return (
    <B24ThemeProvider>
      <AppContent />
    </B24ThemeProvider>
  );
}

// Хук для роботи з темою
function ThemeAwareComponent() {
  const { theme, isDark } = useB24Theme();
  // theme: 'light' | 'dark' | 'auto'
  return <div className={isDark ? 'dark-specific' : ''}> ... </div>;
}

Тема синхронізується з порталом через BX24.getTheme() і подію зміни теми — коли користувач перемикає тему у Бітрікс24, застосунок відображає зміну миттєво.

Кейс: дашборд KPI для відділу продажів

Застосунок відображає KPI менеджерів у реальному часі: кількість дзвінків, зустрічей, угод у роботі, конверсія по воронці. Дані — з CRM Бітрікс24 через REST API + власний агрегаційний бекенд.

Завдання: інтерфейс має виглядати як частина Бітрікс24, підтримувати обидві теми, бути зрозумілим без навчання.

Використані компоненти UI Kit: Table для таблиці менеджерів, Badge для статусів (виконано/ні), Avatar для фото співробітників, Select для вибору періоду, Button для експорту.

Кастомні компоненти поверх UI Kit: прогрес-бар KPI (CSS-змінні UI Kit для кольорів), спарклайн-графіки (Recharts зі стилізацією під палітру Бітрікс24), таблиця рейтингу з drag-and-drop сортуванням колонок.

Результат: користувачі не сприймають дашборд як «сторонній застосунок» — інтерфейс органічно вписаний у робочий простір порталу.

Кастомізація та розширення компонентів

UI Kit не охоплює всі сценарії. Для кастомних компонентів використовуються дизайн-токени системи через CSS-змінні:

.custom-card {
  background:    var(--b24-color-base-3);
  border:        1px solid var(--b24-color-base-50);
  border-radius: var(--b24-radius-md);
  color:         var(--b24-color-base-90);
  font-family:   var(--b24-font-family);
}

Список токенів доступний у документації UI Kit. Використання токенів замість захардкоджених значень — обов'язкова умова для коректної роботи з усіма темами.

Компонент таблиці з сортуванням

const columns: TableColumn<Manager>[] = [
  {
    key:    'name',
    title:  'Менеджер',
    render: (row) => (
      <div className="flex items-center gap-2">
        <Avatar src={row.photo} name={row.name} size={AvatarSize.XS} />
        <span>{row.name}</span>
      </div>
    ),
    sortable: true,
  },
  {
    key:    'deals',
    title:  'Угод',
    render: (row) => (
      <Badge
        color={row.deals >= row.target ? BadgeColor.Success : BadgeColor.Warning}
        label={`${row.deals} / ${row.target}`}
      />
    ),
    sortable: true,
  },
];

<Table
  columns={columns}
  rows={managersData}
  onSort={(key, direction) => setSortConfig({ key, direction })}
  loading={isLoading}
/>

Склад робіт

• Аудит вимог до інтерфейсу, складання компонентного плану
• Налаштування проєкту: @bitrix24/b24jssdk, @bitrix24/b24ui, TypeScript
• Розробка компонентів: базові (з UI Kit) + кастомні (поверх дизайн-токенів)
• Підтримка темної теми, тестування в обох варіантах
• Документування кастомних компонентів для команди підтримки

Терміни: набір базових екранів на UI Kit — 1–2 тижні. Кастомна дизайн-система поверх токенів UI Kit — від 3 тижнів.