Пользовательские поля (UF): Как получать и обновлять их в GetList и D7 ORM*

Пользовательские поля (User Fields, UF-поля) — это стандартный механизм Битрикс для расширения сущностей (пользователей, разделов инфоблоков, HL-блоков и др.) новыми полями без изменения структуры базы данных.

Работа с ними имеет свои особенности.

Что такое UF-поля?

Физически значения UF-полей хранятся в отдельной таблице b_uts_…, а их описание — в b_user_field. ORM и старое API абстрагируют эту сложность, позволяя работать с UF-полями так, будто они являются частью основной таблицы.

Все UF-поля имеют префикс UF_. Например, UF_MY_COLOR.

Работа с UF-полями в старом API (на примере CIBlockSection)

1. Выборка (GetList)

Чтобы получить значение UF-поля, его нужно просто добавить в массив $arSelect.

CModule::IncludeModule('iblock');

$arFilter = [
    'IBLOCK_ID' => 5,
    'ACTIVE'    => 'Y',
];

// Добавляем UF-поля в select
$arSelect = ['ID', 'NAME', 'UF_SECTION_BANNER', 'UF_SHOW_ON_MAIN'];

$rsSections = CIBlockSection::GetList(['SORT' => 'ASC'], $arFilter, false, $arSelect);

while ($arSection = $rsSections->GetNext()) {
    echo "Раздел: " . $arSection['NAME'];
    // UF_SECTION_BANNER вернет ID файла
    if ($arSection['UF_SECTION_BANNER']) {
        echo " | Баннер: " . CFile::GetPath($arSection['UF_SECTION_BANNER']);
    }
    echo "<br>";
}

2. Фильтрация

Фильтрация по UF-полям происходит так же, как и по обычным, с указанием префикса UF_.

$arFilter = [
    'IBLOCK_ID' => 5,
    'ACTIVE'    => 'Y',
    '=UF_SHOW_ON_MAIN' => 1 // Найти разделы, у которых UF-свойство "Показывать на главной" (тип "Да/Нет") равно "Да"
];

3. Добавление и обновление

При вызове CIBlockSection::Add или Update значения UF-полей передаются в основном массиве $arFields с префиксом UF_.

$bs = new CIBlockSection;

$arFields = [
    "IBLOCK_ID"      => 5,
    "NAME"           => "Новый раздел с UF-полями",
    // Задаем значения UF-полей
    "UF_CUSTOM_COLOR" => "#FF0000",
    "UF_SHOW_ON_MAIN" => 0 // "Нет"
];

$ID = $bs->Add($arFields);

if ($ID > 0) {
    // Обновим поле
    $bs->Update($ID, ["UF_SHOW_ON_MAIN" => 1]);
} else {
    echo "Ошибка: " . $bs->LAST_ERROR;
}

Работа с UF-полями в D7 ORM

D7 ORM делает работу с UF-полями еще проще и прозрачнее. Они становятся частью сущности, как и обычные поля.

1. Выборка (getList)

Просто укажите UF_-поле в select. Никаких runtime или ReferenceField для этого не нужно!

use Bitrix\Main\Loader;
use Bitrix\Iblock\SectionTable;

Loader::includeModule('iblock');

$result = SectionTable::getList([
    'select' => ['ID', 'NAME', 'UF_SECTION_BANNER', 'UF_SHOW_ON_MAIN'],
    'filter' => ['=IBLOCK_ID' => 5, '=ACTIVE' => 'Y']
]);

while ($section = $result->fetch()) {
    // Данные доступны напрямую
    echo $section['NAME'] . ' | Показывать на главной: ' . ($section['UF_SHOW_ON_MAIN'] ? 'Да' : 'Нет') . '<br>';
}

2. Фильтрация

Аналогично, UF-поля используются в filter как обычные.

$result = SectionTable::getList([
    'select' => ['ID', 'NAME'],
    'filter' => [
        '=IBLOCK_ID' => 5,
        '=UF_SHOW_ON_MAIN' => true // ORM понимает boolean для полей "Да/Нет"
    ]
]);

3. Добавление и обновление (add, update)

UF-поля передаются в массиве данных наравне со всеми остальными.

$data = [
    "IBLOCK_ID" => 5,
    "NAME" => "Новый D7 раздел с UF",
    "UF_CUSTOM_COLOR" => "#0000FF",
    "UF_SHOW_ON_MAIN" => false
];

$result = SectionTable::add($data);

if ($result->isSuccess()) {
    $id = $result->getId();
    // Обновление
    SectionTable::update($id, ['UF_CUSTOM_COLOR' => '#FFFFFF']);
}

Вывод:
Пользовательские поля — мощный инструмент кастомизации сущностей Битрикс. D7 ORM значительно упрощает работу с ними, интегрируя их в объектную модель как «родные» поля. При работе со старым API важно помнить, что UF-поля передаются в тех же массивах, что и системные поля, но всегда с префиксом UF_.

Пользовательские поля, UF поля, Битрикс, GetList с UF, D7 ORM UF, CUserTypeManager, обновление UF полей, разделы инфоблоков.