Разработка 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 недель.