Розробка вбудовуваних програм на Vue.js для Бітрікс24

Розробка вбудованих застосунків на Vue.js для Бітрікс24

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

Як вбудовуються застосунки у Бітрікс24

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

• iframe-застосунок — завантажується за зовнішнім URL у вікні порталу. Обмінюється даними з Бітрікс24 через JS-бібліотеку window.BX24.
• Вбудований 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 тижні залежно від складності бізнес-логіки.