Пользовательские поля UF_ в Битрикс: настройка и вывод

Пользовательские поля — способ добавить свои данные к штатным сущностям 1С-Битрикс, не трогая структуру базы. Дополнительное поле в профиле пользователя, реквизиты у заказа, поле у раздела инфоблока — всё это UF-поля.

Они узнаются по префиксу UF_ в названии и работают одинаково для всех сущностей, которые их поддерживают. Разберём, как создать поле, как получить и записать значение из кода и в чём разница между UF-полями и свойствами инфоблока.

Где они поддерживаются

Важный момент, который часто путают: у элементов инфоблока пользовательских полей нет — там свои свойства. UF-поля есть у разделов инфоблока, но не у элементов.

UF-поля и свойства инфоблока

Создание поля

Поле создаётся через интерфейс. Ключевые параметры:

• Код поля. Обязан начинаться с UF_. Дальше — латиница в верхнем регистре: UF_MIDDLE_NAME.
• Тип. Строка, число, дата, список, файл, привязка к элементу или разделу, логическое значение.
• Множественное. Определяет, хранится одно значение или массив. Изменить потом непросто — решайте сразу.
• Обязательное. Проверяется при сохранении через интерфейс.
• Заголовки и подписи. Их стоит заполнить: иначе в админке будет отображаться технический код.

Работа со значениями

Поля пользователя

UF-поля возвращаются вместе с остальными данными пользователя:

<?php

$user = CUser::GetByID(1)->Fetch();

echo $user['UF_MIDDLE_NAME'];

Запись через тот же класс:

<?php

$cUser = new CUser();

$cUser->Update(1, [
    'UF_MIDDLE_NAME' => 'Иванович',
    'UF_DEPARTMENT'  => [5, 7],   // множественное поле — массив
]);

Обзор класса и остальных его методов — в статье CUser в Битрикс.

Поля разделов инфоблока

Здесь есть нюанс: UF-поля разделов не приходят автоматически. Их нужно явно запросить в списке полей:

<?php

$result = CIBlockSection::GetList(
    ['SORT' => 'ASC'],
    ['IBLOCK_ID' => 5],
    false,
    ['ID', 'NAME', 'UF_BANNER', 'UF_SEO_TEXT']  // перечисляем явно
);

while ($section = $result->Fetch()) {
    echo $section['UF_SEO_TEXT'];
}

Забытое перечисление — самая частая причина «поле создал, значение записал, а в выборке его нет».

Универсальный способ через CUserTypeEntity

Значения UF-полей любой сущности можно получить через универсальный механизм. Он полезен, когда работаете с сущностью, у которой нет удобного класса:

<?php

global $USER_FIELD_MANAGER;

// все значения UF-полей раздела инфоблока
$values = $USER_FIELD_MANAGER->GetUserFields(
    'IBLOCK_5_SECTION',   // код сущности
    $sectionId,
    LANGUAGE_ID
);

foreach ($values as $code => $field) {
    echo $code . ': ' . print_r($field['VALUE'], true);
}

Коды сущностей строятся по шаблону:

Поля типа «файл»

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

<?php

$fileId = $section['UF_BANNER'];

if ($fileId) {
    $path = CFile::GetPath($fileId);
}

Подробнее о работе с файлами — в статье CFile::GetPath в Битрикс.

Для записи файла в UF-поле используется массив в формате загрузки:

<?php

$file = CFile::MakeFileArray($_SERVER['DOCUMENT_ROOT'] . '/upload/banner.jpg');

$cUser->Update($userId, ['UF_PHOTO' => $file]);

Поля типа «список»

Списочное поле хранит идентификатор варианта, а не его текст. Чтобы вывести человеку читаемое значение, нужно получить список вариантов:

<?php

$enum = new CUserFieldEnum();

$result = $enum->GetList([], ['USER_FIELD_NAME' => 'UF_STATUS']);

$values = [];

while ($row = $result->GetNext()) {
    $values[$row['ID']] = $row['VALUE'];
}

echo $values[$user['UF_STATUS']];

Это тоже частый источник недоумения: в поле лежит число вместо ожидаемого текста.

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

• Код без префикса UF_. Поле просто не создастся.
• UF-поля разделов не указаны в выборке. Значения не приходят, хотя в базе они есть.
• Ожидание текста от списочного поля. В нём хранится идентификатор варианта.
• Ожидание пути от файлового поля. В нём хранится ID файла.
• Запись строки в множественное поле. Множественные поля принимают только массив.
• Смена признака множественности после запуска. Данные при этом можно потерять — проверяйте на копии.
• Обязательность проверяется не всегда. При программной записи через API проверка обязательных полей может не сработать — валидируйте сами.

Итог

Пользовательские поля добавляют свои данные к пользователям, разделам инфоблоков, заказам и другим сущностям без изменения структуры базы. Код поля всегда начинается с UF_, а поведение зависит от типа: списки хранят идентификаторы вариантов, файловые поля — идентификаторы файлов, множественные — массивы.

Главное, о чём стоит помнить при работе из кода: UF-поля разделов инфоблока нужно явно перечислять в списке выбираемых полей, иначе они не придут в выборку. Именно на этом чаще всего теряют время.