Пользовательские поля

С помощью пользовательских полей можно создать новые поля к объектам Bitrix Framework. Например, добавить дополнительные данные к пользователю, задаче, сделке.

Для каждого объекта можно создать произвольное количество пользовательских полей. Код пользовательского поля всегда начинается с префикса UF_: UF_PHONE, UF_BIRTHDATE, UF_RATING.

Чем отличаются поля и свойства инфоблоковЧем отличаются поля и свойства инфоблоков

Нужно различать два понятия:

• пользовательские поля — универсальный механизм, который работает с разными объектами системы: пользователями, CRM, задачами, календарями,

• свойства инфоблоков — применяются только для элементов и разделов инфоблоков.

В формах интерфейса можно встретить название пользовательские свойства. Оно означает пользовательские поля, а не свойства.

В каких объектах доступны поляВ каких объектах доступны поля

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

Не все модули поддерживают пользовательские поля, но вы можете:

• использовать объекты информационных блоков, если модуль с ними связан,

• создать собственный объект.

Типы данныхТипы данных

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

Когда системных типов недостаточно, можно создать собственные с помощью API.

Как создать поле через интерфейсКак создать поле через интерфейс

Создайте пользовательское поле одним из двух способов.

1. На странице Настройки > Настройки продукта > Пользовательские поля нажмите Добавить.

   

2. В форме редактирования объекта, где доступны пользовательские поля, перейдите по ссылке Добавить пользовательское свойство. Например, в форме редактирования пользователя, раздела инфоблока, блога или сущности CRM.

   

Как задать настройки поляКак задать настройки поля

В форме укажите следующие параметры:

• Тип данных — выберите один из типов данных. Тип можно задать только для нового поля. Обязательный параметр.

• Объект — укажите код объекта для нового поля. Система заполняет параметр автоматически, если поле создано из формы объекта. Обязательный параметр.

• Код поля — укажите код пользовательского поля заглавными латинскими буквами. Префикс UF_ обязателен. Код можно задать только для нового поля. Обязательный параметр.

• XML_ID — задайте идентификатор поля для работы с внешними источниками.

• Сортировка — введите число, которое определяет положение поля в общем списке. Чем меньше число, тем выше поле в списке.

• Множественное — отметьте опцию, чтобы значение поля было множественным. Параметр можно настроить только для нового поля.

• Обязательное — отметьте опцию, чтобы поле было обязательным для заполнения.

• Показывать в фильтре списка — укажите способ отображения поля в фильтре:

  • не показывать — поле не будет показано в фильтре,

  • точное совпадение — для поиска поля потребуется точное совпадение условию поиска,

  • поиск по маске — для поиска поля можно использовать маску,

  • поиск по подстроке — поиск поля возможен по подстроке.

• Не показывать в списке — отметьте опцию, чтобы поле не отображалось в списке элементов в месте применения.

• Не разрешать редактирование пользователем — отметьте опцию, чтобы пользователь не мог редактировать значение поля. Работу с полем можно выполнять только через API продукта.

• Значения поля участвуют в поиске — отметьте опцию, чтобы после переиндексации сайта значения поля были доступны в результатах поиска.

В разделе Дополнительные настройки поля настройте параметры, которые зависят от выбранного типа данных.

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

Как работать с полями через APIКак работать с полями через API

За работу с пользовательскими полями отвечают классы CUserTypeEntity в старом ядре и UserField в D7.

Класс UserFieldTable применяют для простого доступа к существующим данным. Для изменения записей используйте CUserTypeEntity.

Как создать новое полеКак создать новое поле

Чтобы создать пользовательское поле, используйте класс CUserTypeEntity и его метод Add. Перед добавлением подготовьте массив с параметрами поля. Параметр USER_TYPE_ID определяет тип поля. Доступные значения смотрите в таблице типов.

Пример создания поля типа СтрокаПример создания поля типа Строка

$userTypeEntity = new CUserTypeEntity();
        
        $userFields = [
            // Идентификатор сущности, к которой будет привязано поле
            'ENTITY_ID' => 'IBLOCK_3_SECTION',
            // Код поля, всегда должен начинаться с UF_ 
            'FIELD_NAME' => 'UF_DEV2DAY_FIELD',
            // Тип нового поля — строка
            'USER_TYPE_ID' => 'string',
            // XML_ID пользовательского свойства используется при выгрузке
            'XML_ID' => 'XML_ID_DEV2DAY_FIELD',
            // Сортировка 
            'SORT' => 500,
            // Является поле множественным или нет 
            'MULTIPLE' => 'N',
            // Обязательное или нет свойство 
            'MANDATORY' => 'N',
            // Показывать в фильтре списка. Возможные значения: не показывать = N, точное совпадение = I,
            // поиск по маске = E, поиск по подстроке = S
            'SHOW_FILTER' => 'N',
            // Не показывать в списке. Если передать какое-либо значение, значит флаг выставлен
            'SHOW_IN_LIST' => '',
            // Пустая строка разрешает редактирование. Если передать какое-либо значение, значит флаг выставлен
            'EDIT_IN_LIST' => '',
            // Значения поля участвуют в поиске 
            'IS_SEARCHABLE' => 'N',
            // Дополнительные настройки поля зависят от типа
            'SETTINGS'  => [
                'DEFAULT_VALUE' => '',
                'SIZE'  => '20',
                'ROWS'  => '1',
                'MIN_LENGTH'  => '0',
                'MAX_LENGTH'  => '0',
                'REGEXP' => '',
            ],
            // Подпись в форме редактирования
            'EDIT_FORM_LABEL' => [
                'ru' => 'Пользовательское свойство',
                'en' => 'User field',
            ],
            // Заголовок в списке
            'LIST_COLUMN_LABEL' => [
                'ru' => 'Пользовательское свойство',
                'en' => 'User field',
            ],
            // Подпись фильтра в списке
            'LIST_FILTER_LABEL' => [
                'ru' => 'Пользовательское свойство',
                'en' => 'User field',
            ],
            // Сообщение об ошибке, необязательное
            'ERROR_MESSAGE' => [
                'ru' => 'Ошибка при заполнении пользовательского свойства',
                'en' => 'An error in completing the user field',
            ],
            // Помощь 
            'HELP_MESSAGE' => [
                'ru' => '',
                'en' => '',
            ],
        ];
        
        $userFieldId = $userTypeEntity->Add($userFields); 
        

Пояснения к коду

1. Код создает пользовательское поле UF_DEV2DAY_FIELD типа Строка для разделов инфоблока с ID=3.

2. Устанавливает параметры. Основные из них:

   • ENTITY_ID — сущность, к которой привязывается поле,

   • FIELD_NAME — код поля,

   • USER_TYPE_ID — тип данных, в данном случае string,

   • XML_ID — идентификатор для выгрузки данных,

   • EDIT_FORM_LABEL — подпись в форме редактирования,

   • SETTINGS — дополнительные настройки для поля типа Строка.

3. Если поле добавлено успешно, $userFieldId будет содержать ID нового поля. Если произошла ошибка, возвращает false.

Как добавить значение поляКак добавить значение поля

Способ добавления значений зависит от типа пользовательского поля. Для большинства типов значение присваивается напрямую при создании или обновлении сущности.

Для поля типа Список значения хранятся отдельно в таблице b_user_field_enum. Чтобы добавить значения, используйте методы CUserFieldEnum и SetEnumValue.

Пример добавления значения в поле типа СписокПример добавления значения в поле типа Список

$enumField = new CUserFieldEnum();
        
        $addEnum = [];
        $addEnum['n'.$i] = [
            'XML_ID' => $key,
            'VALUE' => $value,
            'DEF' => 'N',
            'SORT' => $i*10
        ];
        
        $enumField->SetEnumValues($newID, $addEnum);
        

Пояснения к коду

1. Код добавляет варианты выбора в поле типа Список.

2. Ключ массива должен начинаться с n — это обязательное правило Bitrix Framework.

Как обновить полеКак обновить поле

При обновлении пользовательского поля нельзя менять параметры:

• USER_TYPE_ID — тип данных,

• ENTITY_ID — объект,

• FIELD_NAME — код поля,

• MULTIPLE — признак множественности.

Это может вызвать ошибки связей значений и сущностей. Чтобы изменить одно из этих полей, сначала создайте новое поле, перенесите в него значения и удалите старое.

Другие параметры поля можно обновить.

Пример обновления поляПример обновления поля

Код делает поле обязательным для заполнения.

$userTypeEntity->Update($userFieldId, [
            'MANDATORY' => 'Y',
        ]);
        

Как обновить значения поляКак обновить значения поля

Чтобы обновить значения поля, используйте класс CUserTypeManager и метод Update.

В примере метод принимает три параметра:

• ENTITY_ID — тип сущности, например, IBLOCK_3_SECTION,

• ID — идентификатор записи, в данном случае идентификатор раздела,

• массив значений полей, где ключ — код поля UF_DEV2DAY_FIELD, а значение — новое значение.

global $USER_FIELD_MANAGER;
        
        $section = \CIBlockSection::GetList([], [
            'IBLOCK_CODE' => 'shop_news',
            'CODE' => 'test_section',
        ])->Fetch();
        
        if (!$section)
        {
            throw new \Exception('Секция не найдена');
        }
        
        $USER_FIELD_MANAGER->Update('IBLOCK_3_SECTION', $section['ID'], [
            'UF_DEV2DAY_FIELD' => 'updated value',
        ]);
        

В случае успешного обновления метод Update вернет true.

Как удалить полеКак удалить поле

В метод Delete класса CUserTypeEntity передайте идентификатор пользовательского поля.

$userTypeEntity->Delete($userFieldId);
        

Выборка, фильтрация и сортировкаВыборка, фильтрация и сортировка

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

В класс таблицы MyTable добавьте статический метод getUfId(). Он должен возвращать код сущности, для которой созданы пользовательские поля.

Например, если поля созданы для сообщений блога, верните BLOG_POST.

class MyTable extends \Bitrix\Main\ORM\Data\DataManager
        {
            public static function getUfId()
            {
                return 'BLOG_POST';
            }
        
            // ...
        }
        

Теперь можно фильтровать, сортировать и выбирать пользовательские поля.

$rows = MyTable::query()
            ->addSelect('UF_GRATITUDE')
            ->where('UF_GRATITUDE', '>', 50)
            ->addOrder('UF_GRATITUDE', 'DESC')
            ->fetchCollection()
        ;
        

ORM автоматически добавит JOIN к таблице пользовательских полей. Ничего писать вручную не нужно.

После получения коллекции объектов можно работать с пользовательскими полями через геттеры и сеттеры.

foreach ($rows as $row)
        {
            $value = $row->getUfGratitude();
            $row->setUfGratitude($value + 50);
            $row->save();
        }
        

Как добавить поле к любому объектуКак добавить поле к любому объекту

Пользовательские поля можно добавить к любому объекту, который изначально их не поддерживает. Например, для объекта BLOG_RATING необходимо добавить поле Рейтинг.

1. Создайте поле с помощью метода Add класса CUserTypeEntity. В параметрах обязательно передайте:

   • ENTITY_ID — объект. Укажите BLOG_RATING.

   • FIELD_NAME — код поля, например, UF_RATING.

   • USER_TYPE_ID — тип данных. Укажите double — число.

   $type = new \CUserTypeEntity();
           
           $type->Add([
               'ENTITY_ID' => 'BLOG_RATING',
               'FIELD_NAME' => 'UF_RATING',
               'USER_TYPE_ID' => 'double',
               'SETTINGS' => [
                   'DEFAULT_VALUE' => 5,
               ],
               'LIST_COLUMN_LABEL' => [
                   'ru' => 'Рейтинг',
               ],
               'LIST_FILTER_LABEL' => [
                   'ru' => 'Рейтинг',
               ],
               'EDIT_FORM_LABEL' => [
                   'ru' => 'Рейтинг',
               ],
               'HELP_MESSAGE' => [
                   'ru' => 'Подсказка',
               ],
           ]);
           

2. Запишите значение с помощью менеджера полей.

   /**
           * @var \CUserTypeManager $manager
           */
           $manager = \Bitrix\Main\UserField\Internal\UserFieldHelper::getInstance()->getManager();
           $entityId = 'BLOG_RATING';
           $itemId = 123;
           
           $fields = [
               'UF_RATING' => 50,
           ];
           
           $manager->Update($entityId, $itemId, $fields); 
           

3. Прочитайте данные с помощью методов GetUserFieldValue и GetUserFields.

   /**
            * @var \CUserTypeManager $manager
            */
           $manager = \Bitrix\Main\UserField\Internal\UserFieldHelper::getInstance()->getManager();
           $entityId = 'BLOG_RATING';
           $itemId = 123;
           
           $specificValue = $manager->GetUserFieldValue($entityId, 'UF_RATING', $itemId);
           $allFields = $manager->GetUserFields($entityId, $itemId);
           

Такой способ требует ручного управления данными и не работает с методом GetList, но позволяет использовать поля в собственных компонентах и модулях.

СобытияСобытия

Для работы с пользовательскими полями можно использовать события Главного модуля.

• OnUserTypeBuildList — вызывается при построении списка пользовательских полей методом CUserTypeManager::GetUserType.

• OnUserTypeRightsCheck — вызывается при проверке прав доступа на пользовательские поля методом CUserTypeManager::GetRights.