Свойства элементов Битрикс: Работа со Списком, Файлом и Привязкой

При добавлении или обновлении элементов через API (CIBlockElement::Add/Update) работа с простыми свойствами (строка, число) интуитивно понятна.

Однако сложные типы, такие как «Список», «Файл» и «Привязка к элементам», требуют передачи данных в строго определенном формате.

Общий принцип: PROPERTY_VALUES и SetPropertyValuesEx

• При добавлении (Add) или полной перезаписи всех свойств (Update) используется ключ PROPERTY_VALUES в основном массиве полей.
• При точечном обновлении одного или нескольких свойств без затрагивания остальных, всегда используйте CIBlockElement::SetPropertyValuesEx.

1. Свойство типа «Список» (List)

Как хранится: В базе хранится не само значение («Да», «Нет», «Красный»), а ID этого значения из настроек свойства.

Как обновлять:
Нужно передавать ID значения списка.

// Допустим, у свойства "Цвет" (код COLOR) есть значения:
// Красный (ID: 15)
// Синий (ID: 16)

$elementId = 123;
$iblockId = 5;

// Устанавливаем значение "Красный"
CIBlockElement::SetPropertyValuesEx($elementId, $iblockId, [
    'COLOR' => 15
]);

// Для множественного списка передаем массив ID
CIBlockElement::SetPropertyValuesEx($elementId, $iblockId, [
    'COLORS' => [15, 16]
]);

Ошибка новичка: Пытаться передать строковое значение (‘COLOR’ => ‘Красный’). Это не сработает.

2. Свойство типа «Файл» (File)

Как хранится: Хранится ID файла из таблицы b_file.

Как обновлять:
Нужно передать массив, подготовленный функцией CFile::MakeFileArray().

$elementId = 123;
$iblockId = 5;

// Готовим массив файла
$arFile = CFile::MakeFileArray($_SERVER["DOCUMENT_ROOT"]."/upload/my_image.jpg");

// Устанавливаем значение
CIBlockElement::SetPropertyValuesEx($elementId, $iblockId, [
    'MORE_PHOTO' => $arFile
]);

Для множественного свойства:
Для добавления нового файла к существующим нужно передавать массив, где ключ — это n<порядковый_номер>, а значение — массив файла.

$arFiles = [];
$arFiles['n0'] = CFile::MakeFileArray(...);
$arFiles['n1'] = CFile::MakeFileArray(...);

CIBlockElement::SetPropertyValuesEx($elementId, $iblockId, ['GALLERY' => $arFiles]);

Удаление файла:
Чтобы удалить файл, нужно передать массив с ключом del и значением Y.

// Удаляем файл из одиночного свойства
CIBlockElement::SetPropertyValuesEx($elementId, $iblockId, [
    'DOC_FILE' => ['del' => 'Y']
]);

3. Свойство типа «Привязка к элементам/разделам» (Binding)

Как хранится: Хранится ID привязанного элемента или раздела.

Как обновлять:
Нужно передавать ID элемента/раздела.

$elementId = 123; // ID нашего элемента
$iblockId = 5;
$relatedElementId = 456; // ID элемента, который мы хотим привязать

// Устанавливаем привязку
CIBlockElement::SetPropertyValuesEx($elementId, $iblockId, [
    'RELATED_PRODUCTS' => $relatedElementId
]);

// Для множественной привязки передаем массив ID
CIBlockElement::SetPropertyValuesEx($elementId, $iblockId, [
    'RELATED_PRODUCTS' => [456, 457, 458]
]);

4. Свойство со значением и описанием

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

// Обновляем множественное свойство "Телефоны" с описаниями
$arPhones = [
    ['VALUE' => '+7 (495) 111-22-33', 'DESCRIPTION' => 'Основной'],
    ['VALUE' => '+7 (495) 444-55-66', 'DESCRIPTION' => 'Дополнительный'],
];

CIBlockElement::SetPropertyValuesEx($elementId, $iblockId, ['PHONES' => $arPhones]);

Для множественных свойств с описанием при добавлении новых значений к существующим, нужно использовать сложный формат с ключами n<X>.

Вывод:
Правильное формирование массива данных для сложных свойств — ключ к успешной работе с API Битрикс.

Запомните главное: Список — ID значения, Файл — массив MakeFileArray, Привязка — ID элемента/раздела. 

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

CIBlockElement::SetPropertyValuesEx, свойства инфоблока, свойство список, привязка к элементам, свойство файл, PROPERTY_VALUES, Битрикс.