Чтение значений списочного поля CRM в Битрикс24: метод CUserFieldEnum::GetList

Область применения и ключевые сущности

Метод CUserFieldEnum::GetList используется для получения справочных значений пользовательских полей типа «список» или «множественный список». Понимание этой связки необходимо при:

• Выводе значения поля в публичной части — преобразование ID сохранённого значения в читаемый текст
• Построении выпадающих списков в формах — получение всех вариантов для селекта
• Экспорте данных — подстановка текстовых значений вместо ID
• Отчётах и дашбордах — группировка данных по значениям списочных полей
• Миграции данных — проверка существующих значений при импорте

Ключевые сущности:

Таблица / Класс	Описание
b_user_field	Пользовательские поля системы (хранит мета-информацию)
b_user_field_enum	Значения списочных пользовательских полей
CUserFieldEnum	Класс для работы со значениями списочных полей
CCrmLead / CCrmDeal и др.	Классы CRM-сущностей, содержащие пользовательские поля
\Bitrix\Crm\Service\Container	Современный DI-контейнер для работы с CRM-сущностями

Параметры метода CUserFieldEnum::GetList

Метод имеет следующую сигнатуру:

php

public static function GetList($arOrder = [], $arFilter = [])

Параметр $arOrder (сортировка)

Определяет порядок сортировки значений списка:

php

$arOrder = [
    'SORT' => 'ASC',      // по полю сортировки (по умолчанию)
    'VALUE' => 'ASC',     // по названию значения
    'ID' => 'DESC'        // по ID
];

Доступные ключи: ID, VALUE, SORT, XML_ID.

Параметр $arFilter (фильтрация)

Основной и обязательный фильтр — USER_FIELD_NAME (символьный код пользовательского поля). Дополнительные фильтры:

Ключ	Описание	Пример
USER_FIELD_NAME	Символьный код поля (обязательный)	'UF_CRM_1617204193'
ID	Фильтр по ID значения	123
VALUE	Фильтр по названию значения	'Трейд-ин'
XML_ID	Фильтр по внешнему коду	'TRADE_IN'

Возвращаемое значение

Метод возвращает объект CDBResult, который содержит записи из таблицы b_user_field_enum. Каждая запись включает поля

Поле	Описание
ID	Уникальный идентификатор значения
USER_FIELD_ID	ID пользовательского поля
VALUE	Название значения (отображается пользователю)
SORT	Порядок сортировки
XML_ID	Внешний код (используется в REST API)

Практические примеры

Пример 1. Базовое получение значений списочного поля

php

// Читаем значения поля "Источник TRADE-IN"
$UF_CRM_1617204193 = [];

$enum = new CUserFieldEnum();
$rsEnum = $enum->GetList(
    ['SORT' => 'ASC'],                    // сортировка
    ['USER_FIELD_NAME' => 'UF_CRM_1617204193']  // код поля
);

while ($arEnum = $rsEnum->Fetch()) {
    $UF_CRM_1617204193[$arEnum['ID']] = $arEnum['VALUE'];
}

echo "<pre>UF_CRM_1617204193: ";
print_r($UF_CRM_1617204193);
echo "</pre>";

Пример 2. Универсальная функция для чтения любого списочного поля

php

/**
 * Получает значения списочного пользовательского поля
 * 
 * @param string $userFieldName Символьный код поля (например, 'UF_CRM_1617204193')
 * @param string $order Поле сортировки ('SORT', 'VALUE', 'ID')
 * @param string $direction Направление ('ASC' или 'DESC')
 * @return array Массив значений в формате [ID => VALUE]
 */
function getCrmEnumFieldValues(string $userFieldName, string $order = 'SORT', string $direction = 'ASC'): array
{
    if (empty($userFieldName)) {
        return [];
    }
    
    $values = [];
    
    if (\Bitrix\Main\Loader::includeModule('crm')) {
        $enum = new \CUserFieldEnum();
        $rsEnum = $enum->GetList(
            [$order => $direction],
            ['USER_FIELD_NAME' => $userFieldName]
        );
        
        while ($arEnum = $rsEnum->Fetch()) {
            $values[$arEnum['ID']] = $arEnum['VALUE'];
        }
    }
    
    return $values;
}

// Использование
$sourceValues = getCrmEnumFieldValues('UF_CRM_1617204193');
echo '<pre>'; print_r($sourceValues); echo '</pre>';

Пример 3. Получение значений с XML_ID (для REST-интеграций)

php

function getCrmEnumFieldWithXmlId(string $userFieldName): array
{
    $values = [];
    
    $enum = new CUserFieldEnum();
    $rsEnum = $enum->GetList(
        ['SORT' => 'ASC'],
        ['USER_FIELD_NAME' => $userFieldName]
    );
    
    while ($arEnum = $rsEnum->Fetch()) {
        $values[$arEnum['ID']] = [
            'VALUE'  => $arEnum['VALUE'],
            'XML_ID' => $arEnum['XML_ID'],
            'SORT'   => $arEnum['SORT']
        ];
    }
    
    return $values;
}

Пример 4. Получение значения по XML_ID

php

function getEnumValueByXmlId(string $userFieldName, string $xmlId): ?string
{
    $enum = new CUserFieldEnum();
    $rsEnum = $enum->GetList(
        [],
        [
            'USER_FIELD_NAME' => $userFieldName,
            'XML_ID' => $xmlId
        ]
    );
    
    if ($arEnum = $rsEnum->Fetch()) {
        return $arEnum['VALUE'];
    }
    
    return null;
}

// Пример: получаем название значения по XML_ID = 'TRADE_IN'
$value = getEnumValueByXmlId('UF_CRM_1617204193', 'TRADE_IN');
echo $value; // "Трейд-ин"

Пример 5. Преобразование сохранённого ID в название для элемента CRM

php

function getLeadEnumFieldValue(int $leadId, string $userFieldName): ?string
{
    if (!\Bitrix\Main\Loader::includeModule('crm')) {
        return null;
    }
    
    // Получаем значение поля из лида
    $lead = \CCrmLead::GetByID($leadId);
    $fieldValue = $lead[$userFieldName] ?? null;
    
    if (empty($fieldValue)) {
        return null;
    }
    
    // Для множественных списков поле может содержать массив ID
    $ids = is_array($fieldValue) ? $fieldValue : [$fieldValue];
    
    // Получаем все возможные значения списка
    $enumValues = getCrmEnumFieldValues($userFieldName);
    
    // Преобразуем ID в названия
    $result = [];
    foreach ($ids as $id) {
        if (isset($enumValues[$id])) {
            $result[] = $enumValues[$id];
        }
    }
    
    return implode(', ', $result);
}

// Использование
$leadId = 12345;
$sourceName = getLeadEnumFieldValue($leadId, 'UF_CRM_1617204193');
echo "Источник лида: " . $sourceName;

Пример 6. Получение всех списочных полей для сущности

php

function getAllEnumFieldsForEntity(string $entityType): array
{
    if (!\Bitrix\Main\Loader::includeModule('crm')) {
        return [];
    }
    
    // Соответствие типов сущностей
    $entityMap = [
        'lead'    => \CCrmOwnerType::Lead,
        'deal'    => \CCrmOwnerType::Deal,
        'contact' => \CCrmOwnerType::Contact,
        'company' => \CCrmOwnerType::Company
    ];
    
    $entityTypeId = $entityMap[$entityType] ?? null;
    if (!$entityTypeId) {
        return [];
    }
    
    // Получаем все пользовательские поля для сущности
    $userFields = $GLOBALS['USER_FIELD_MANAGER']->GetUserFields(
        'CRM_' . ucfirst($entityType),
        0,
        LANGUAGE_ID
    );
    
    $enumFields = [];
    
    foreach ($userFields as $fieldName => $field) {
        if ($field['USER_TYPE']['USER_TYPE_ID'] === 'enumeration') {
            $enumValues = getCrmEnumFieldValues($fieldName);
            $enumFields[$fieldName] = [
                'LABEL' => $field['EDIT_FORM_LABEL'],
                'VALUES' => $enumValues
            ];
        }
    }
    
    return $enumFields;
}

// Использование
$leadEnumFields = getAllEnumFieldsForEntity('lead');
echo '<pre>'; print_r($leadEnumFields); echo '</pre>';

Пример 7. Добавление нового значения в списочное поле

php

function addEnumFieldValue(string $userFieldName, string $value, int $sort = 500): ?int
{
    if (!\Bitrix\Main\Loader::includeModule('crm')) {
        return null;
    }
    
    // Получаем ID пользовательского поля
    $dbRes = \CUserFieldEnum::GetList(
        [],
        ['USER_FIELD_NAME' => $userFieldName]
    );
    
    $userFieldId = null;
    if ($field = $dbRes->Fetch()) {
        $userFieldId = $field['USER_FIELD_ID'];
    }
    
    if (!$userFieldId) {
        return null;
    }
    
    // Добавляем новое значение
    $enum = new \CUserFieldEnum();
    $result = $enum->SetEnumValues($userFieldId, [
        'n0' => [
            'VALUE' => $value,
            'SORT' => $sort,
            'DEF' => 'N'
        ]
    ]);
    
    if ($result) {
        // Получаем ID добавленного значения
        $dbRes = \CUserFieldEnum::GetList(
            ['ID' => 'DESC'],
            [
                'USER_FIELD_NAME' => $userFieldName,
                'VALUE' => $value
            ]
        );
        
        if ($newEnum = $dbRes->Fetch()) {
            return $newEnum['ID'];
        }
    }
    
    return null;
}

Пример 8. Работа с множественным списочным полем (D7 Style)

php

use Bitrix\Main\Loader;
use Bitrix\Crm\Service\Container;
use Bitrix\Crm\Item;

// Современный подход через D7 (для сделок)
function getDealMultipleEnumValues(int $dealId, string $enumFieldName): array
{
    Loader::includeModule('crm');
    
    $factory = Container::getInstance()->getFactory(\CCrmOwnerType::Deal);
    if (!$factory) {
        return [];
    }
    
    $deal = $factory->getItem($dealId);
    if (!$deal) {
        return [];
    }
    
    // Получаем значение поля (обычно это массив ID)
    $fieldValue = $deal->get($enumFieldName);
    if (empty($fieldValue)) {
        return [];
    }
    
    // Приводим к массиву
    $ids = is_array($fieldValue) ? $fieldValue : [$fieldValue];
    
    // Получаем названия значений
    $enumValues = getCrmEnumFieldValues($enumFieldName);
    
    $result = [];
    foreach ($ids as $id) {
        if (isset($enumValues[$id])) {
            $result[$id] = $enumValues[$id];
        }
    }
    
    return $result;
}

Альтернативные методы

Метод	Описание
CUserFieldEnum::GetList()	Основной метод, описанный выше
CUserFieldEnum::SetEnumValues()	Установка/обновление значений списочного поля
CUserFieldEnum::DeleteEnumValues()	Удаление значений списочного поля
\Bitrix\Crm\Service\Container::getFactory()->getItem()	D7 способ получения значений элемента с пользовательскими полями
$USER_FIELD_MANAGER->GetUserFields()	Получение мета-описания всех пользовательских полей сущности

Структура таблиц для справки

sql

-- b_user_field (пользовательские поля)
-- ID, FIELD_NAME, ENTITY_ID, USER_TYPE_ID

-- b_user_field_enum (значения списочных полей)
-- ID, USER_FIELD_ID, VALUE, SORT, XML_ID

Особенности и рекомендации

1. Обязательная проверка существования поля: Перед вызовом GetList убедитесь, что поле с указанным именем действительно существует. Иначе метод вернёт пустой результат без ошибки.

2. Префикс полей CRM: Пользовательские поля в CRM имеют префикс UF_CRM_, за которым следует числовой ID поля. Например: UF_CRM_1617204193.

3. Множественные списки: Если поле является множественным, значение в элементе CRM хранится как сериализованный массив ID. При работе через D7 автоматически получаете массив.

4. Кеширование: Значения списочных полей редко меняются. Рекомендуется кешировать результат getCrmEnumFieldValues() на время выполнения скрипта или дольше.

5. Сортировка: По умолчанию значения возвращаются в порядке, заданном пользователем в настройках поля (по полю SORT). При переопределении сортировки через $arOrder это поведение меняется.

6. Локализация: Названия значений (VALUE) хранятся на том языке, на котором были созданы. При мультиязычности учитывайте это.

Типичные ошибки и их решение

Ошибка	Решение
Пустой результат при правильном имени поля	Проверьте, что поле действительно типа «список». Для текстовых, числовых и других типов метод не работает.
Некорректное отображение значения в карточке	Убедитесь, что вы используете ID значения, а не XML_ID для поиска в массиве $values[$id].
Ошибка при работе с множественным полем	Проверьте, что правильно обрабатываете массив ID, а не скалярное значение.

Заключение

CUserFieldEnum::GetList — это основной метод для получения значений списочных пользовательских полей CRM в коробочной версии Битрикс24. В связке с данными элемента из CCrmLead::GetByID или через D7-контейнер он позволяет гибко преобразовывать сохранённые ID в понятные пользователю названия. Понимание этого метода необходимо каждому разработчику, который работает с пользовательскими полями типа «список» в CRM, строит формы, отчёты или экспортирует данные.