Кастомные пользовательские поля Битрикс24: как разработать

Что такое кастомные пользовательские поля

В Битрикс24 у каждой сущности (сделка, контакт, смарт-процесс) есть стандартный набор полей: текст, число, дата, список, файл и т.д. Но часто нужны специальные поля, которых нет «из коробки»: специфичные сущности, кастомные интерфейсы, интеграции с внешними сервисами.

Кастомные пользовательские поля (UF) — механизм Битрикс24 для разработки таких полей через REST API.

Архитектура кастомного поля

Состоит из двух HTML-страниц на вашем сервере:

• index.html — страница установки. Регистрирует тип поля в Битрикс через JS API.
• handler.html — обработчик отображения. Битрикс встраивает его в карточку через iframe, передавая данные.

Дополнительно — серверная часть (PHP/Node) для логики и работы с данными.

Шаг 1: Регистрация типа поля

Через метод userfieldtype.add:

// в index.html
BX24.callMethod('userfieldtype.add', {
  USER_TYPE_ID: 'my_custom_field',
  HANDLER: 'https://yourdomain.com/handler.html',
  TITLE: 'Моё кастомное поле',
  DESCRIPTION: 'Описание поля'
});

После регистрации поле становится доступным в настройках (можно создать пользовательское поле этого типа в любой сущности).

Шаг 2: Обработчик отображения

Битрикс встраивает handler.html в карточку через iframe. Передаёт параметры через GET:

• field — JSON с настройками поля
• value — текущее значение
• mode — режим (view, edit, settings)

В handler.html — JS, который рендерит интерфейс и при изменении сохраняет значение через postMessage.

Пример: поле «Привязать договор»

Задача: в карточке счёта показывать выпадающий список договоров той же компании. Выбрал — привязка сохраняется.

Реализация:

1. В index.html — регистрация типа
2. В handler.html: при загрузке получить из Битрикс ID компании (через BX24.placement), запросить договоры этой компании, отрендерить выпадающий список
3. При выборе — отправить значение в Битрикс через placement.call

Так работает наше реальное приложение Contract Linker.

Размеры iframe

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

BX24.resizeWindow(width, height);
// или для авто-высоты
BX24.fitWindow();

Режимы работы

view — только просмотр значения. Минимум интерфейса.

edit — редактирование. Полный интерфейс с сохранением.

settings — настройка поля при создании в админке.

Часто handler.html обрабатывает все режимы через if по mode.

Связанные методы API

• userfieldtype.add — регистрация типа
• userfieldtype.update — изменение
• userfieldtype.delete — удаление
• userfieldtype.list — список зарегистрированных

Также — crm.deal.userfield.add и аналоги для других сущностей, чтобы создавать пользовательские поля программно.

Безопасность

• handler.html должен проверять подпись от Битрикс (поле AUTH_ID)
• HTTPS обязателен
• CORS настроен на домен Битрикс
• Валидация всех входных данных

Варианты применения

• Привязка к внешним справочникам (товары из 1С)
• Кастомные виджеты (карта адресов, выбор времени)
• Интеграционные поля (статус из CRM партнёра)
• Кнопки действий (запустить процесс, сгенерировать документ)
• Виджеты согласования (как наше Invoice Approve)

Деплой

Файлы (index.html, handler.html, статика) размещаются на любом веб-сервере с HTTPS. Часто — у вашего хостинг-провайдера.

Регистрация типа делается один раз. Дальше Битрикс обращается к handler.html при каждом отображении поля.

Частые ошибки

• handler.html без HTTPS — Битрикс не загрузит (mixed content)
• Не вызывается BX24.init() — JS API не работает
• Сохранение через REST API вместо placement.call — проблемы с правами
• Не учитывают разные режимы (view/edit/settings) — поле работает только в одном
• Без логирования — отладка кошмарна

Сколько стоит разработка

Простое кастомное поле (выпадающий список с подгрузкой данных): 30 000–80 000 ₽. Срок 1–3 недели.

Сложное (с интеграцией и кастомным UX): 80 000–300 000 ₽. Срок 1–3 месяца.

Рассчитать →   Записаться на разбор →

FAQ

Можно ли использовать для смарт-процессов?

Да, после регистрации тип поля доступен для всех сущностей.

Где хранить серверную логику?

На любом веб-сервере с HTTPS. Часто на том же, где размещены файлы поля.