Расширьте возможности карточки сделки в Битрикс24: Отображение должности контакта – полное руководство

Узнайте, как с помощью JavaScript добавить поле "Должность" при выборе контакта в сделке, сделав работу в CRM еще эффективнее.

Ключевые моменты

Настройка пользовательских полей: Основа для добавления любой дополнительной информации, включая должность, в карточку контакта Битрикс24.
JavaScript и REST API: Мощные инструменты для динамического получения и отображения данных контакта непосредственно в интерфейсе сделки.
Улучшение UX: Отображение должности контакта помогает менеджерам быстрее ориентироваться и принимать решения, повышая общую продуктивность.

При работе со сделками в Битрикс24 часто возникает необходимость видеть больше информации о клиенте прямо в момент его выбора. Стандартно система отображает только телефон и email контакта, что не всегда достаточно для полного понимания контекста. Добавление поля "Должность" может значительно улучшить этот процесс. В этой статье мы подробно разберем, как это сделать с использованием JavaScript и возможностей REST API Битрикс24.

Пример карточки сделки в Битрикс24, где можно отобразить дополнительную информацию о контакте.

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

Стандартный виджет выбора контакта в Битрикс24 (CRM Entity Selector), используемый в форме сделки, оптимизирован для отображения наиболее востребованной базовой информации: ФИО, телефон и email. Это сделано для обеспечения скорости работы интерфейса и его универсальности. Отображение всех возможных полей, включая пользовательские, сделало бы этот виджет перегруженным и менее удобным для большинства сценариев.

Для вывода дополнительных сведений, таких как "Должность", требуется кастомизация. Битрикс24 предоставляет гибкие механизмы для таких доработок через свой REST API и возможность выполнения JavaScript-кода на стороне клиента.

Шаги по добавлению отображения поля "Должность"

Процесс добавления отображения должности контакта при его выборе в сделке можно разделить на несколько ключевых этапов. Важно понимать, что поле "Должность" должно существовать и быть заполнено в карточке самого контакта.

Шаг 1: Убедитесь, что поле "Должность" существует и используется

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

Проверка системного поля "Должность"

В Битрикс24 существует стандартное системное поле "Должность" (POST в терминах API). Убедитесь, что оно используется и отображается в карточке контакта. Вы можете настроить его видимость:

Перейдите в CRM → Клиенты → Контакты.
Откройте любую карточку контакта.
Нажмите "Выбрать поле" или "Изменить" (в зависимости от настроек вашей карточки), чтобы добавить или отобразить поле "Должность".

Создание пользовательского поля "Должность" (если необходимо)

Если стандартное поле по каким-то причинам не подходит, или вы хотите использовать отдельное пользовательское поле, его можно создать:

Через интерфейс:
1. Перейдите в CRM → Настройки → Настройки CRM → Настройки форм и отчетов → Пользовательские поля.
2. Выберите "Контакт" и нажмите "Добавить поле".
3. Задайте имя поля (например, "Должность сотрудника"), выберите тип "Строка". Запомните или запишите ID поля (например, UF_CRM_XXXXXX), он понадобится для API.

Через REST API: Можно использовать метод crm.contact.userfield.add.

// Пример запроса на создание пользовательского поля
BX24.callMethod(
    'crm.contact.userfield.add',
    {
        fields: {
            FIELD_NAME: 'UF_CRM_CUSTOM_POSITION', // Уникальное имя поля
            USER_TYPE_ID: 'string',         // Тип поля: строка
            XML_ID: 'CUSTOM_POSITION',      // Внешний код (необязательно)
            SORT: 100,                      // Порядок сортировки
            MANDATORY: 'N',                 // Обязательное (Y/N)
            EDIT_FORM_LABEL: { ru: 'Должность (доп.)' }, // Название в форме
            LIST_COLUMN_LABEL: { ru: 'Должность (доп.)' } // Название в списках
        }
    },
    function(result) {
        if (result.error()) {
            console.error('Ошибка создания поля:', result.error());
        } else {
            console.log('Поле успешно создано, ID:', result.data());
        }
    }
);

После создания поля не забудьте заполнить его данными для тестовых контактов.

Шаг 2: Получение данных контакта с помощью JavaScript и REST API

Когда контакт выбран в сделке, его ID становится доступным. Этот ID можно использовать для запроса полной информации о контакте, включая поле "Должность", через метод crm.contact.get.

Шаг 3: Отображение должности в интерфейсе сделки

Получив значение должности, его нужно вставить в HTML-структуру страницы сделки. Это делается путем манипулирования DOM (Document Object Model) с помощью JavaScript. Вы можете создать специальный <div> элемент рядом с полем выбора контакта или в другом удобном месте карточки сделки.

Пример JavaScript кода для реализации

Ниже приведен пример JavaScript-кода, который можно адаптировать и использовать для отображения должности. Этот код следует размещать в месте, где он будет выполняться на странице карточки сделки (например, через кастомное приложение, виджет или другие механизмы внедрения JS в Битрикс24).

BX.ready(function() {
    // Функция для получения и отображения должности контакта
    function displayContactPosition(contactId) {
        if (!contactId) {
            // Если контакт не выбран или ID пуст, очищаем поле должности
            let positionDisplayElement = document.getElementById('contact-position-display');
            if (positionDisplayElement) {
                positionDisplayElement.innerText = '';
            }
            return;
        }

        BX24.callMethod(
            'crm.contact.get',
            { id: contactId },
            function(result) {
                if (result.error()) {
                    console.error('Ошибка получения данных контакта:', result.error());
                } else {
                    let contactData = result.data();
                    // Пытаемся получить должность из стандартного поля 'POST'
                    // или из пользовательского поля (замените 'UF_CRM_YOUR_POSITION_FIELD' на ID вашего поля)
                    let position = contactData.POST || contactData.UF_CRM_YOUR_POSITION_FIELD || 'Должность не указана';

                    // Находим или создаем элемент для отображения должности
                    let positionDisplayElement = document.getElementById('contact-position-display');
                    let contactSelectorField = document.querySelector('[data-field-id="CONTACT_ID"]'); // Адаптируйте селектор под вашу форму

                    if (!positionDisplayElement && contactSelectorField) {
                        positionDisplayElement = document.createElement('div');
                        positionDisplayElement.id = 'contact-position-display';
                        positionDisplayElement.style.marginTop = '5px'; // Небольшой отступ
                        positionDisplayElement.style.fontSize = '0.9em';
                        positionDisplayElement.style.color = '#555';
                        // Вставляем элемент после поля выбора контакта
                        contactSelectorField.parentNode.insertBefore(positionDisplayElement, contactSelectorField.nextSibling);
                    }
                    
                    if (positionDisplayElement) {
                        positionDisplayElement.innerText = 'Должность: ' + position;
                    }
                }
            }
        );
    }

    // Отслеживание изменения в поле выбора контакта
    // Селектор поля контакта может отличаться в зависимости от версии и настроек Битрикс24.
    // Возможно, потребуется использовать MutationObserver для отслеживания динамически загружаемых полей.
    // Простой пример для поля, которое уже существует на странице:
    // Предположим, что у поля выбора контакта есть атрибут data-field-id="CONTACT_ID" или аналогичный.
    // Этот код является ОБЩИМ ПРИМЕРОМ и может потребовать адаптации.
    
    // Находим контейнер, где находится поле выбора контакта (селектор может нуждаться в уточнении)
    // Идеально использовать события, которые предоставляет сам Bitrix24 для компонента выбора сущности, если таковые доступны.
    // Если стандартные события отсутствуют, можно отслеживать изменения DOM.

    // Пример: Попытка повесить обработчик на уже существующий элемент (если он не подгружается динамически)
    // или использовать MutationObserver для динамически изменяющихся форм.
    // ВАЖНО: Селектор '[data-field-id="CONTACT_ID"]' является предположением.
    // Вам нужно будет инспектировать DOM вашей формы сделки, чтобы найти правильный селектор
    // для элемента, отображающего ID выбранного контакта, или для input-поля, если оно используется.
    // Часто ID контакта хранится в скрытом input поле или в атрибуте data-* родительского элемента.

    // Более надежный способ - использовать API Bitrix24 для подписки на события изменения поля, если оно доступно.
    // BX.addCustomEvent(window, 'CrmEntityEditorChange', function(editor, eventArgs) {
    //     if (eventArgs.fieldName === 'CONTACT_ID' || (eventArgs.field && eventArgs.field.getId() === 'CONTACT_ID')) {
    //          const contactBindings = editor.getFieldValue('CONTACT_BINDINGS');
    //          if (contactBindings && contactBindings.length > 0 && contactBindings[0].CONTACT_ID) {
    //             displayContactPosition(contactBindings[0].CONTACT_ID);
    //          } else {
    //             displayContactPosition(null); // Очистить, если контакт удален
    //          }
    //     }
    // });
    // Примечание: CrmEntityEditorChange может не работать во всех контекстах или версиях.
    // Может потребоваться отслеживать изменения в input поле, связанном с CONTACT_ID.

    // Альтернативный (менее надежный) подход с MutationObserver для отслеживания изменений:
    const targetNode = document.body; // Наблюдаем за всем body, или более конкретным контейнером формы
    const config = { childList: true, subtree: true };
    let currentContactId = null;

    const callback = function(mutationsList, observer) {
        // Попробуйте найти элемент, в котором хранится ID контакта
        // Это может быть скрытое поле input или элемент с data-атрибутом
        let contactIdInput = document.querySelector('input[name="CONTACT_ID"]'); // Пример селектора
        if (!contactIdInput) {
             // Попробуйте другой селектор, если первый не сработал, например для множественных контактов
             contactIdInput = document.querySelector('input[name="CONTACT_IDS[]"]');
        }
        // Также можно искать по data-атрибутам, как в примере выше: document.querySelector('[data-field-id="CONTACT_ID"]')
        
        let newContactId = null;
        if (contactIdInput) {
             newContactId = contactIdInput.value;
        } else {
            // Если поле выбора контакта реализовано через UI компоненты Битрикса, 
            // может потребоваться более сложный поиск ID, например, через data-атрибуты элемента выбора.
            const contactSelectorElement = document.querySelector('.crm-entity-widget-content-block-inner-container'); // Примерный селектор
            if (contactSelectorElement && contactSelectorElement.firstChild && contactSelectorElement.firstChild.hasAttribute('data-item-id')) {
                newContactId = contactSelectorElement.firstChild.getAttribute('data-item-id');
            }
        }

        if (newContactId !== currentContactId) {
            currentContactId = newContactId;
            displayContactPosition(currentContactId);
        }
    };

    const observer = new MutationObserver(callback);
    observer.observe(targetNode, config);
    
    // Первоначальный вызов для уже выбранного контакта при загрузке страницы
    callback(); 

});

Важно:

Замените UF_CRM_YOUR_POSITION_FIELD на реальный ID вашего пользовательского поля должности, если вы используете его. Если вы используете стандартное поле, то contactData.POST должно сработать.
Селектор для contactSelectorField (например, document.querySelector('[data-field-id="CONTACT_ID"]')) может потребовать корректировки в зависимости от вашей версии Битрикс24 и настроек формы сделки. Используйте инструменты разработчика в браузере для определения правильного селектора элемента, к которому или после которого вы хотите добавить информацию о должности.
Представленный код с MutationObserver является одним из подходов для отслеживания изменений в динамически обновляемых формах. В некоторых случаях может потребоваться более точная привязка к событиям конкретных UI-компонентов Битрикс24, если их API это позволяет (например, события BX.Crm.EntityEditor).

Визуализация процесса настройки

Для лучшего понимания всего процесса, представим его в виде ментальной карты. Эта карта иллюстрирует основные этапы, начиная от подготовки и заканчивая тестированием.

mindmap root["Отображение 'Должности' контакта в сделке Битрикс24"] ["A. Подготовка"] A1["Проверка/Создание поля 'Должность' в Контактах"] A1a["Через интерфейс CRM Настройки"] A1b["Через REST API (crm.contact.userfield.add)"] A2["Определение ID поля 'Должность' (например, POST или UF_CRM_XXXXX)"] ["B. Реализация на JavaScript"] B1["Использование Bitrix24 JS API (BX.ready, BX24.callMethod)"] B2["Обработчик события выбора/изменения контакта в сделке"] B2a["Идентификация элемента выбора контакта (DOM-селектор или API события)"] B3["Получение ID выбранного контакта"] B4["Запрос данных контакта через REST API (crm.contact.get)"] B4a["Передача ID контакта"] B4b["Извлечение значения поля 'Должность'"] B5["Отображение 'Должности' в интерфейсе сделки"] B5a["Создание/поиск DOM-элемента для вывода информации"] B5b["Обновление содержимого элемента (innerText, innerHTML)"] ["C. Тестирование и отладка"] C1["Проверка на контактах с заполненной должностью"] C2["Проверка на контактах без указания должности"] C3["Отладка JavaScript кода в консоли браузера"]

Эта схема поможет вам структурировать работу и не упустить важные детали.

Ключевые факторы для успешной реализации

Успех внедрения этой кастомизации зависит от нескольких ключевых факторов. Оценим их важность по 5-балльной шкале (где 5 - максимальная важность/требуемый уровень навыка):

Как видно из диаграммы, глубокое понимание JavaScript, включая работу с DOM и событиями, а также знание принципов работы REST API Битрикс24 являются критически важными. Также необходим административный доступ к CRM для настройки полей и точное определение DOM-селекторов для взаимодействия с элементами страницы.

Обзор используемых методов REST API и JS Битрикс24

Для реализации описанного функционала ключевую роль играют определенные методы REST API и функции JavaScript библиотеки Битрикс24. Ниже представлена таблица с их кратким описанием.

Метод / Функция	Тип	Описание	Пример использования в задаче
`crm.contact.userfield.add`	REST API	Создает новое пользовательское поле для сущности "Контакт".	Добавление поля "Должность", если оно отсутствует как стандартное или требуется специфическое пользовательское поле.
`crm.contact.get`	REST API	Получает детальную информацию о контакте по его ID.	Запрос данных выбранного в сделке контакта для извлечения значения поля "Должность".
`crm.contact.fields`	REST API	Возвращает описание всех доступных полей (стандартных и пользовательских) для сущности "Контакт".	Может использоваться для определения точного ID (например, `UF_CRM_XXXXXX`) пользовательского поля "Должность".
`BX24.callMethod(method, params, callback)`	JS API Битрикс24	Универсальная JavaScript-функция для вызова методов REST API из клиентского скрипта в окружении Битрикс24.	Обертка для выполнения запросов `crm.contact.get` и других методов API.
`BX.ready(callback)`	JS API Битрикс24	Обеспечивает выполнение JavaScript-кода после полной загрузки DOM и инициализации API Битрикс24.	Гарантирует, что скрипт начнет работу, когда все необходимые элементы и функции Битрикс24 будут доступны.
`document.querySelector(selector)`	JavaScript (DOM API)	Находит первый элемент в документе, соответствующий указанному CSS-селектору.	Поиск элемента для выбора контакта и элемента для отображения должности.
`element.addEventListener(event, callback)`	JavaScript (DOM API)	Прикрепляет обработчик к указанному событию на элементе (не используется в примере с MutationObserver, но является стандартным подходом).	Отслеживание события изменения значения в поле выбора контакта (если поле статично).
`MutationObserver`	JavaScript (DOM API)	Позволяет отслеживать изменения в DOM-дереве.	Используется для отслеживания выбора контакта в динамически обновляемых формах Битрикс24.

Видео-руководство по работе с полями в Битрикс24

Для лучшего понимания того, как создавать и настраивать поля в карточках CRM Битрикс24, рекомендуем посмотреть следующее видео. Хотя оно может не затрагивать конкретно JavaScript-кастомизацию, оно даст хорошее представление об основах работы с полями, что является предпосылкой для нашей задачи.

В этом видео объясняется, как создавать поля в карточках лида, сделки, контакта и компании в Битрикс24.

Понимание того, как устроены поля в Битрикс24, поможет вам более эффективно применять JavaScript для их кастомизации и отображения дополнительной информации.

Часто задаваемые вопросы (FAQ)

Нужно ли быть администратором Битрикс24 для добавления такого функционала?

Да, для создания пользовательских полей через интерфейс CRM или для внедрения JavaScript-кода (например, через разработку собственного приложения или виджета) обычно требуются права администратора портала Битрикс24. Для вызова REST API методов также необходим соответствующий доступ (токен авторизации с нужными правами).

Что делать, если поле "Должность" не отображается после внедрения кода?

Проверьте следующие моменты:

Ошибки в JavaScript: Откройте консоль разработчика в браузере (обычно F12) и посмотрите, нет ли там ошибок.
ID поля: Убедитесь, что вы используете правильный ID для поля "Должность" (POST для стандартного или UF_CRM_XXXXXX для пользовательского). Его можно уточнить через метод crm.contact.fields или в настройках пользовательских полей.
Заполнение поля: Проверьте, заполнено ли поле "Должность" у выбранного контакта.
Селекторы DOM: Убедитесь, что CSS-селекторы, используемые для поиска поля выбора контакта и места для вставки должности, корректны для вашей текущей разметки страницы. Разметка может меняться между версиями Битрикс24.
Права доступа REST API: Если вы используете токен, убедитесь, что у него есть права на чтение контактов (scope crm).
Место внедрения JS: Убедитесь, что ваш JavaScript-код выполняется в правильном контексте и в нужное время (после загрузки необходимых элементов DOM).

Будет ли это работать в коробочной версии Битрикс24 и в облачной?

Да, описанный подход с использованием JavaScript и REST API применим как для облачной версии Битрикс24, так и для коробочной. REST API и JavaScript API (BX24, BX) работают схожим образом в обеих версиях. Однако, способы внедрения самого JavaScript кода могут несколько отличаться (например, в коробочной версии у вас больше свободы для модификации шаблонов компонентов, если это необходимо, хотя использование REST API и JS-событий является более предпочтительным и универсальным методом).

Как найти правильный селектор для элемента выбора контакта?

Используйте инструменты разработчика вашего браузера (обычно вызываются клавишей F12). Перейдите на вкладку "Elements" (Элементы) и используйте инструмент инспектирования (часто иконка курсора или лупы), чтобы кликнуть на поле выбора контакта на странице сделки. В дереве DOM вы увидите HTML-структуру этого элемента, его классы, ID и атрибуты (например, data-field-id). На основе этой информации вы сможете составить корректный CSS-селектор для JavaScript функции document.querySelector(). Учтите, что если форма загружается динамически, селектор может быть доступен не сразу, и использование MutationObserver или подписка на события инициализации компонентов Битрикс24 может быть более надежным решением.