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

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

Встраиваемые приложения в Битрикс24 — это отдельные фронтенд-модули, которые загружаются внутри интерфейса портала через iframe или BX24 JS SDK. Стандартный путь — PHP-страница с window.BX24.init() и jQuery-кодом. Когда логика приложения становится нетривиальной: несколько экранов, состояние, реактивные обновления — jQuery превращается в неподдерживаемую лапшу. Vue.js решает эту проблему архитектурно.

Как встраиваются приложения в Битрикс24

Битрикс24 предоставляет два механизма размещения:

• iframe-приложение — загружается по внешнему URL в окне портала. Обменивается данными с Битрикс24 через window.BX24 JS-библиотеку.
• Встроенное JS-приложение — размещается на том же домене, регистрируется через \Bitrix\Rest\AppTable, использует серверный REST API напрямую.

Для Vue-приложений стандартный выбор — iframe с отдельным хостингом или размещение в /local/apps/. Серверная часть может быть написана на Laravel, Node.js или самом Битрикс.

Инициализация Vue внутри Битрикс24

Подключение BX24 SDK и старт Vue-приложения:

<!-- index.html -->
<script src="//{{portal}}.bitrix24.ru/bitrix/js/rest/bx24/bx24.js"></script>
<div id="app"></div>
<script type="module" src="/assets/app.js"></script>

// main.js
import { createApp } from 'vue'
import App from './App.vue'

window.BX24.init(() => {
  const app = createApp(App)
  app.provide('bx24', window.BX24)
  app.mount('#app')
})

Передача BX24 через provide/inject позволяет использовать его в любом компоненте без глобальных переменных.

Работа с REST API Битрикс24 из Vue

Для REST-вызовов используется BX24.callMethod или BX24.callBatch. Оборачиваем в промисы:

// composables/useBx24.js
import { inject } from 'vue'

export function useBx24() {
  const bx24 = inject('bx24')

  function callMethod(method, params = {}) {
    return new Promise((resolve, reject) => {
      bx24.callMethod(method, params, (result) => {
        if (result.error()) reject(result.error())
        else resolve(result.data())
      })
    })
  }

  async function callBatch(calls) {
    return new Promise((resolve, reject) => {
      bx24.callBatch(calls, (results) => {
        const errors = Object.values(results).filter(r => r.error())
        if (errors.length) reject(errors[0].error())
        else resolve(Object.fromEntries(
          Object.entries(results).map(([k, v]) => [k, v.data()])
        ))
      })
    })
  }

  return { callMethod, callBatch }
}

Типичный компонент списка сделок:

<script setup>
import { ref, onMounted } from 'vue'
import { useBx24 } from '@/composables/useBx24'

const { callMethod } = useBx24()
const deals = ref([])
const loading = ref(true)

onMounted(async () => {
  deals.value = await callMethod('crm.deal.list', {
    select: ['ID', 'TITLE', 'STAGE_ID', 'OPPORTUNITY'],
    filter: { STAGE_ID: 'NEW' },
    order: { DATE_CREATE: 'DESC' }
  })
  loading.value = false
})
</script>

Управление размером iframe

Битрикс24 не управляет высотой iframe автоматически. Приложение должно само сообщать о своём размере:

// App.vue
import { onMounted, onUpdated } from 'vue'

const bx24 = inject('bx24')

function fitWindow() {
  bx24.fitWindow()
}

onMounted(fitWindow)
onUpdated(fitWindow)

Для динамических приложений с изменяемой высотой — ResizeObserver на корневой элемент с вызовом bx24.resizeWindow(width, height).

Авторизация и права доступа

Токен доступа передаётся автоматически через BX24 SDK. Для серверных запросов используется bx24.getAuth():

const auth = bx24.getAuth()
// { access_token, expires_in, scope, domain, ... }

await fetch('/api/my-endpoint', {
  headers: { Authorization: `Bearer ${auth.access_token}` }
})

Проверка прав пользователя — crm.contact.access.has и аналогичные методы в зависимости от сущности.

Сборка и деплой

Vite — оптимальный выбор для сборки:

// vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  base: '/local/apps/my-app/',
  build: {
    outDir: 'dist',
    assetsDir: 'assets',
  }
})

Собранный dist/ размещается на сервере. В настройках приложения Битрикс24 прописывается URL точки входа. Для локальной разработки используется ngrok или Vite dev server с HTTPS — Битрикс24 требует HTTPS для iframe-приложений.

Типичные сценарии применения

Дашборд по сделкам — агрегация данных из CRM, визуализация воронки, фильтры по ответственным и периодам. Стандартных отчётов Битрикс24 для нестандартных срезов недостаточно.

Кастомная форма создания заявки — мультишаговая форма с валидацией, зависимыми полями, загрузкой файлов. Стандартная карточка CRM не поддерживает сложную условную логику отображения полей.

Интеграционный коннектор — приложение получает данные из внешней системы (1С, ERP, маркетплейс) и отображает их в контексте Битрикс24 с возможностью синхронизации.

Планировщик задач — кастомный UI для управления задачами с drag-and-drop, kanban-доской или timeline-видом поверх стандартного API задач.

Сроки выполнения

Простое приложение (один экран, CRUD по одной сущности) — 2–3 рабочих дня. Приложение с несколькими экранами, авторизацией, серверной частью и деплоем — 1–2 недели в зависимости от сложности бизнес-логики.