Инструкция по разработке приложений для Битрикс24

1. Введение

Эта инструкция представляет собой руководство по использованию приложения "Конструктор Vue-форм" для Битрикс24. Приложение позволяет создавать современные, адаптивные формы и пользовательские поля с использованием Vue3 и Vuetify 3, которые затем можно легко интегрировать в Битрикс24. Представленные в документации примеры кода демонстрируют практическое применение конструктора в различных бизнес-сценариях: от простых тестовых форм до сложных интеграций с бизнес-процессами, внешними API и CRM-системой. Каждый пример сопровождается детальным описанием структуры кода, особенностей работы с Bitrix24 API через Axios и рекомендациями по кастомизации под конкретные задачи. Приложение обеспечивает полную совместимость с экосистемой Битрикс24, сохраняя при этом преимущества современного фронтенд-разработки с использованием Vue.js и Vuetify, что делает пользовательский интерфейс более интуитивным и функциональным.

https://www.bitrix24.ru/apps/app/jnas.konstruktor_form_vue/

2. Структура проекта

Общая структура

src/
├── mock/                # Моковые данные для разработки
├── features/            # Фичи (функциональные модули приложения)
│   ├── example1-test-form/        # Пример 1: Тестовая форма
│   ├── example2-redirect/         # Пример 2: Перенаправление
│   ├── example3-business-process-workflow-starter/  # Пример 3: Запуск бизнес-процесса
│   ├── example4-axios/            # Пример 4: Работа с внешними API
│   ├── example5-comments-form/    # Пример 5: Форма комментариев
│   ├── example6-business-process-field-set-value/  # Пример 6: Установка значений в поле Бизнес-Процесса
│   └── example7-form-upload-files/  # Пример 7: Загрузка файлов в форму Бизнес-Процесса
├── shared/              # Общие компоненты и утилиты
└── AppMount.vue         # Основной точка входа (не подлежит переименованию)

Описание примеров

Пример 1: Тестовая форма (`example1-test-form`)

Назначение: Демонстрационная форма с базовой функциональностью
Возможности:
- Ввод и отображение текста с реактивными вычислениями
- Обработка кликов по кнопкам с анимацией загрузки
- Интеграция с Bitrix24 API для получения данных пользователя
- Демонстрация работы с хуками жизненного цикла

Пример 2: Перенаправление (`example2-redirect`)

Назначение: Демонстрация перенаправления на внешний ресурс
Компоненты:
- Example21RedirectButton.vue - Кнопка для инициализации перенаправления
- Example22RedirectProcess.vue - Компонент процесса перенаправления
Особенности:
- Автоматическое перенаправление через 3 секунды
- Индикатор загрузки во время ожидания

Пример 3: Запуск бизнес-процесса (`example3-business-process-workflow-starter`)

Назначение: Управление бизнес-процессом в Bitrix24
Функциональность:
- Кнопка для запуска бизнес-процесса
- Отслеживание состояния процесса
- Периодический опрос статуса
Особенности:
- Интеграция с Bitrix24 API
- Обработка ошибок и состояний загрузки

Пример 4: Работа с внешними API (`example4-axios`)

Назначение: Демонстрация работы с внешними API
Функциональность:
- Загрузка случайных фактов о кошках с внешнего API
- Кнопка для обновления данных
- Обработка состояний загрузки и ошибок
Используемые технологии:
- Axios для HTTP-запросов
- Vuetify для UI компонентов

Пример 5: Форма комментариев (`example5-comments-form`)

Назначение: Полноценная система комментариев
Компоненты:
- CommentInput.vue - Поле ввода комментария
- CommentsList.vue - Список комментариев с пагинацией
Функциональность:
- Добавление новых комментариев
- Загрузка и отображение существующих
- Пагинация и сортировка
- Интеграция с CRM Bitrix24

Пример 6: Пользовательское поле в Бизнес-процессах (`example6-business-process-field-set-value`)

Назначение: Управление значениями пользовательских полей в бизнес-процессах
Особенности:
- Выбор нескольких значений из выпадающего списка
- Сохранение значений в формате JSON
- Валидация и обработка ввода
- Интеграция с API Bitrix24 через setUserfieldValue
Ограничения:
- Работает только в контексте пользовательского поля
- Требует настройки обязательного поля в настройках БП

Пример 7: Загрузка файлов (`example7-form-upload-files`)

Назначение: Компонент для загрузки и управления файлами в CRM
Функциональность:
- Загрузка одного или нескольких файлов
- Отображение прогресса загрузки
- Удаление загруженных файлов
- Интеграция с полями сущностей CRM
Особенности:
- Поддержка множественной загрузки файлов
- Визуальная индикация процесса загрузки
- Управление состоянием загруженных файлов
- Интеграция с Bitrix24 API для работы с файлами
Используемые технологии:
- Vue 3 Composition API
- Vuetify 3 для UI компонентов
- Кастомный менеджер загрузки файлов

3. Подробное описание папок

mock/

Назначение: содержит моковые данные для работы в режиме разработки
Особенности: папка всегда должна находиться в текущем расположении проекта
Содержание: JSON-файлы с эмуляцией данных от Битрикс24 (placement info, API-ответы)

features/

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

features/
└── [feature-name]/
    ├── components/       # UI-компоненты для данной фичи
    ├── managers/         # Логика в виде композаблов (useAuth, useLogin)
    ├── services/         # API-сервисы и бизнес-логика
    └── [FeatureName].vue # Основной компонент фичи

Пример структуры:

features/
├── auth/
│   ├── components/
│   │   └── LoginForm.vue
│   ├── managers/
│   │   └── useAuth.js
│   ├── services/
│   │   └── authService.js
│   └── AuthComponent.vue
└── profile/
    └── ...

shared/

Содержит переиспользуемые элементы по всему приложению:

shared/
├── components/          # Переиспользуемые UI-компоненты
├── composables/         # Общие композаблы
├── utils/               # Вспомогательные функции
└── types/               # TypeScript типы

3. API приложения

Объект api() предоставляет доступ к функциональности Битрикс24 и вспомогательным инструментам.

3.1. Свойства api()

api().fields

Содержит свойства, передаваемые приложению из Битрикс24.

api().fields.placement - данные, передаваемые из Битрикс24, аналогичные функции BX24.placement.info
- Документация: BX24.placement.info

3.2. Методы api()

api().methods.b24Call

Асинхронный метод для выполнения запросов к REST API Битрикс24.

Аналогичен методу BX24.callMethod, но возвращает Promise
Использование: const response = await api().methods.b24Call('method.name', params)
Не требует callback-параметра, что упрощает работу с асинхронным кодом
Документация: BX24.callMethod

api().methods.axios

Стандартный плагин Axios (версия 1.11.0) для выполнения HTTP-запросов.

Назначение: выполнение запросов к внешним API или кастомным бэкенд-сервисам
Документация: Axios

api().methods.toast

Интеграция с библиотекой "vue-toastification" (версия ^2.0.0-rc.5).

Назначение: отображение уведомлений и информационных сообщений пользователю
Пример использования: api().methods.toast.success('Операция выполнена!')

api().methods.openCustomScript

Метод для открытия пользовательских скриптов в слайдере.

Синтаксис: api().methods.openCustomScript(scriptName: string, params = {})
Важно: метод недоступен в режиме разработки, работает только после компиляции и загрузки в Битрикс24
Назначение: переход между различными скриптами внутри приложения

4. Работа с mock-данными

Поскольку режим разработки изолирован от Битрикс24, необходимо создать моковые данные для тестирования.

4.1. Получение данных placement

В приложении Битрикс24 создайте встройку и включите режим разработки
Перейдите к месту размещения виджета в интерфейсе Битрикс24
Нажмите кнопку "Разработка" в месте размещения виджета
В открывшемся слайдере нажмите "Входные данные" (в правом верхнем углу)
Нажмите иконку экспорта (↑) для сохранения файла
Поместите сохраненный файл в папку /src/mock/, в случае отсутствия папки - создайте папку

Теперь при вызове api().fields.placement в режиме разработки будут использоваться сохраненные данные.

4.2. Создание mock-запросов к API

В режиме веб-разработки нажмите "Отладчик API" (правый верхний угол)
В поле "Метод" укажите название API-метода (например, user.get)
В поле "Данные JSON" укажите параметры запроса:
```
{
  "filter": {
    "ID": 1
  }
}
```
Нажмите "Отправить"
После получения ответа нажмите иконку экспорта (↑)
Сохраните файл в папку /src/mock/

Пример структуры mock-файла:

{
  "method": "user.get",
  "params": {
    "filter": {
      "ID": 1
    }
  },
  "response": {
    "result": [...],
    "total": 1
  },
  "delay": 200
}

Примечание: Параметр delay можно редактировать вручную для эмуляции различных скоростей ответа API.

5. Установка и запуск

5.1. Установка зависимостей

Перед первым запуском проекта выполните в корне проекта:

npm install

5.2. Режим разработки

Для запуска режима разработки используйте команду:

npm run dev

После запуска в консоли будет указан адрес, по которому доступно приложение (обычно http://localhost:5173).

5.3. Сборка проекта

Для компиляции приложения в production-версию выполните:

npm run build

После выполнения команды в папке dist/ появятся файлы:

dev-b24vue.js - основной JavaScript-файл
dev-b24vue.css - стили приложения (если использовались)

5.4. Деплой в Битрикс24

Перейдите в режим веб-разработки в Битрикс24
Переключитесь на режим "Загрузка готового решения"
Загрузите скомпилированные файлы из папки dist/
Сохраните изменения

После загрузки файлы будут автоматически применяться при открытии виджета.

6. Примеры использования

Пример 1: Получение данных о пользователе

// В composables/user.js
export const useUser = () => {
  const getUser = async (userId) => {
    try {
      const response = await api().methods.b24Call('user.get', {
        filter: { ID: userId }
      });
      return response.result[0];
    } catch {
      api().methods.toast.error('Ошибка загрузки данных пользователя');
      throw error;
    }
  };
  
  return { getUser };
};

Пример 2: Отображение уведомления

// В компоненте
import { useUser } from '@/features/user/composables/useUser';

export default {
  setup() {
    const { getUser } = useUser();
    
    const loadUser = async () => {
      try {
        const user = await getUser(1);
        api().methods.toast.success(`Пользователь ${user.NAME} загружен`);
      } catch {
        // Обработка ошибки
      }
    };
    
    return { loadUser };
  }
};

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
dev		dev
public		public
src		src
.gitignore		.gitignore
README.md		README.md
eslint.config.js		eslint.config.js
index.html		index.html
package.json		package.json
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation

Инструкция по разработке приложений для Битрикс24

1. Введение

2. Структура проекта

Общая структура

Описание примеров

Пример 1: Тестовая форма (example1-test-form)

Пример 2: Перенаправление (example2-redirect)

Пример 3: Запуск бизнес-процесса (example3-business-process-workflow-starter)

Пример 4: Работа с внешними API (example4-axios)

Пример 5: Форма комментариев (example5-comments-form)

Пример 6: Пользовательское поле в Бизнес-процессах (example6-business-process-field-set-value)

Пример 7: Загрузка файлов (example7-form-upload-files)

3. Подробное описание папок

mock/

features/

shared/

3. API приложения

3.1. Свойства api()

api().fields

3.2. Методы api()

api().methods.b24Call

api().methods.axios

api().methods.toast

api().methods.openCustomScript

4. Работа с mock-данными

4.1. Получение данных placement

4.2. Создание mock-запросов к API

5. Установка и запуск

5.1. Установка зависимостей

5.2. Режим разработки

5.3. Сборка проекта

5.4. Деплой в Битрикс24

6. Примеры использования

Пример 1: Получение данных о пользователе

Пример 2: Отображение уведомления

7. Дополнительные ресурсы

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Пример 1: Тестовая форма (`example1-test-form`)

Пример 2: Перенаправление (`example2-redirect`)

Пример 3: Запуск бизнес-процесса (`example3-business-process-workflow-starter`)

Пример 4: Работа с внешними API (`example4-axios`)

Пример 5: Форма комментариев (`example5-comments-form`)

Пример 6: Пользовательское поле в Бизнес-процессах (`example6-business-process-field-set-value`)

Пример 7: Загрузка файлов (`example7-form-upload-files`)

Packages