Интеграция UI Kit с REST API и бизнес-логикой

UI Kit отвечает за интерфейс приложения. Данные для экрана и проверку прав приложение получает отдельно — через REST API Битрикс24. Связать их — задача кода приложения: получить авторизацию во фрейме, вызвать метод и передать ответ в компонент.

Откуда приложение берет авторизациюОткуда приложение берет авторизацию

Приложение с UI Kit открывается внутри Битрикс24, во фрейме. Токен не нужно запрашивать и хранить в коде: библиотека B24JsSDK получает данные авторизации от родительского окна Битрикс24 и сама продлевает их, когда истекает срок.

Подключение создает функция initializeB24Frame(). Пока она не отработала, вызовы REST API недоступны. Если страницу открыть не во фрейме, а напрямую в браузере, функция отклонит промис ошибкой SdkError с кодом JSSDK_CLIENT_SIDE_WARNING — поэтому вызов оборачивают в try/catch.

Пример: список пользователей в компоненте UI KitПример: список пользователей в компоненте UI Kit

Компонент запрашивает сотрудников методом user.get и выводит их в таблице UI Kit. Приложению нужен scope user.

<script setup>
import { onMounted, ref } from 'vue'
import { initializeB24Frame } from '@bitrix24/b24jssdk'

const users = ref([])
const error = ref('')
const isLoading = ref(true)

onMounted(async () => {
  try {
    const $b24 = await initializeB24Frame()

    const response = await $b24.actions.v2.call.make({
      method: 'user.get',
      params: { FILTER: { ACTIVE: true } },
      requestId: 'ui-kit-user-list'
    })

    if (!response.isSuccess) {
      error.value = response.getErrorMessages().join('; ')
      return
    }

    users.value = response.getData().result
  } catch (sdkError) {
    error.value = sdkError.message
  } finally {
    isLoading.value = false
  }
})
</script>

<template>
  <p v-if="isLoading">Загрузка</p>
  <p v-else-if="error">{{ error }}</p>
  <B24Table v-else :data="users" />
</template>

Что делает каждая часть:

• initializeB24Frame() возвращает объект $b24 с готовой авторизацией
• actions.v2.call.make() вызывает один метод REST API. Параметр requestId необязателен, он уходит вместе с запросом и помогает найти его в логах
• isSuccess показывает, вернул ли Битрикс24 результат, а getErrorMessages() отдает тексты ошибок REST API
• getData().result — данные ответа. У метода user.get это массив сотрудников
• B24Table принимает массив в свойстве data. Остальные свойства компонента описаны в документации библиотеки

Установка SDK, выбор класса подключения и работа на сервере описаны в статье Установка и использование B24JsSDK.

Подход до UI KitПодход до UI Kit

Если вы уже писали приложения для Битрикс24, то знакомы со схемой:

• интерфейс создается на PHP, HTML и Bootstrap
• внутри фрейма отображается сгенерированная разметка
• данные подгружаются методом BX24.callMethod() из BX24.js
• запросы к REST API идут напрямую из браузера или из PHP до формирования страницы

Такой подход работал и продолжает работать, но у него есть ограничения:

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

Что поменялосьЧто поменялось

Vue принес с собой реактивный подход: теперь вы не управляете DOM напрямую. Вместо этого вы описываете, что должно быть видно на экране, а Vue сам следит за состоянием данных и обновляет интерфейс при их изменении.

Простой пример:

<script setup>
import { ref } from 'vue';

const count = ref(0);
</script>

<template>
  <button @click="count++">
    Нажато {{ count }} раз
  </button>
</template>

Значение count — это реактивная переменная. При каждом клике значение обновляется, и интерфейс автоматически перерисовывается. Вам не нужно вручную менять HTML — Vue делает это за вас.

С UI Kit вы получаете готовые Vue-компоненты, которые реализуют всю визуальную логику за вас:

• кнопки, формы, таблицы, макеты, модальные окна
• компоненты адаптивны и соответствуют стилю Битрикс24
• вы работаете не с HTML и стилями, а с декларативными компонентами

REST API при этом остался тот же: методы, параметры и авторизация работают так же, как в BX24.js или PHP. Меняется точка вызова — из Vue-приложения методы вызывают через B24JsSDK.

Что осталось прежнимЧто осталось прежним

• все методы REST API работают точно так же
• методы можно вызывать из фронтенда приложения или со своего сервера
• авторизация не изменилась: OAuth-протокол для приложений, вебхуки для серверной части
• приложение по-прежнему работает внутри фрейма

Как делятся ролиКак делятся роли

Если вы не работали с VueЕсли вы не работали с Vue

Чтобы начать, знать Vue целиком не нужно:

• компоненты UI Kit инкапсулируют поведение
• структура проектов на Vite или Nuxt простая
• достаточно понимать, как передавать данные и обрабатывать события

Начните с готовых примеров и разбирайтесь по ходу. Другой вариант — взять из UI Kit только дизайн-токены и иконки, оставшись на HTML и Tailwind CSS. Тогда компоненты и их поведение останутся недоступны.

Продолжите изучениеПродолжите изучение

• Битрикс24 UI Kit: обзор
• Быстрый старт: подключение UI Kit к проекту
• Компоненты и шаблоны
• Зарегистрировать обработчик виджета placement.bind