Bitrix API. Встроенный редактор изображений: UI не заменяет серверный контракт

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

В исходной заметке полезен сам вызов `Bitrix\Main\UI\FileInput`. Теперь рядом с ним нужен контроль жизненного цикла: UI создаёт данные для формы, сервер проверяет вход, а сущность хранит итоговую связь. Каждый слой должен иметь собственную проверку.

Bitrix API. Встроенный редактор изображений: UI не заменяет серверный контракт: схема границ проверки — Иллюстрация показывает границу между симптомом, техническим механизмом и проверяемым действием.

Что сохраняем из исходной заметки

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

Поэтому может возникнуть желании использовать его на сайте. Но как это сделать? На самом деле это не так сложно. Класс компонента графического редактора является \Bitrix\Main\UI\FileInput и располагается в файле /bitrix/modules/main/lib/ui/fileinput.php

Для вывода кода компонента необходимо создать экземляр класс с помощью статического метода createInstance. Затем получить код на вывод через метод show. Полный код вызова компонента будет иметь следующий вид:

<?=\Bitrix\Main\UI\FileInput::createInstance([
	"name" => "picture",
	"description" => true,
	"upload" => true,
	"allowUpload" => "I",
	"medialib" => true,
	"fileDialog" => true,
	"cloud" => true,
	"delete" => true,
	"maxCount" => 1
	])->show($id);
?>

Переменная $id содержит идентификатор картинки в системе.

name – задаёт параметр формы, в котором будут переданы данные файла;
description – можно ли задавать описание к файлу;
upload – можно ли загружать файл;
allowUpload – какой тип файлов разрешён к загрузке (F – файлы, I – картинки, A – все типы, по умолчанию);
allowUploadExt – какие типы расширений разрешены к загрузке (*.zip,*.rar,*.doc и пр.);
medialib – можно ли использовать медиа-библиотеку;
fileDialog – разрешён ли файловый диалог для загрузки;
cloud – использовать ли модуль облачного хранилища для загрузки файлов;
delete – можно ли удалять картинку;
edit – можно ли редактировать картинку:
maxCount – максимальное количество файлов;
maxSize – максимальный размер файла (байт).

Также необходимо учитывать, что некоторые параметры будут работать только при определённых условиях, как, например, medialib и cloud.

Завершение интеграции

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

В параметрах компонента отдельно проверьте allowUpload, medialib, fileDialog, cloud, delete, edit и maxCount. Не все параметры будут иметь эффект в любой установке Bitrix: часть зависит от подключённых модулей, прав пользователя и контекста страницы.

$fileId = (int)$_POST['picture'];

if ($fileId > 0) {
    $file = CFile::GetFileArray($fileId);
    if ($file && str_starts_with($file['CONTENT_TYPE'], 'image/')) {
        // сохраняем ID картинки в своей сущности
    }
}

Если редактор не открывается, проверьте подключение модулей main и fileman, права на загрузку, административные JS-расширения и наличие сессии пользователя. В публичной части сайта проблема часто оказывается не в FileInput, а в том, что на странице не подключены нужные скрипты Bitrix.

Рабочая схема такая: выводим FileInput, разрешаем только картинки, ограничиваем количество, после отправки формы валидируем ID файла и сохраняем его в свою сущность. Тогда встроенный редактор становится нормальной частью формы, а не просто красивой кнопкой загрузки.

Механизм без лишних обещаний

Компонент FileInput умеет показать диалог и собрать поля формы, но не знает бизнес-правило, к какой записи относится файл. Идентификатор сущности и имя поля должны приходить из серверного контекста, а не из DOM.

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

Результат сохранения проверяется чтением сущности. Наличие `ID` файла в ответе формы ещё не доказывает, что связь записана в нужное свойство инфоблока.

Минимальный воспроизводимый пример

Ниже — маленькая проверка, которую можно запустить или адаптировать в отдельном тестовом окружении. Значения демонстрационные; проектные идентификаторы, пути и версии нужно заменить своими и сохранить рядом с результатом.

<?php
$field = \Bitrix\Main\UI\FileInput::createInstance([
    "name" => "picture",
    "upload" => true,
    "allowUpload" => "I",
    "maxCount" => 1,
    "delete" => true,
]);

echo $field->show($elementId);

// После POST проверяем результат API, а не только состояние виджета.
$fileId = (int)($request->getPost("picture") ?? 0);
if ($fileId <= 0) {
    throw new RuntimeException("Файл не выбран");
}

Матрица диагностики

Участок: рабочая матрица проверки
Участок	Вопрос	Проверка
Форма	Поля отправились?	POST содержит ожидаемое имя и ID
Права	Кто меняет файл?	Пользователь может редактировать сущность
Файл	Что реально загружено?	Размер, MIME, расширение и содержимое
Связь	Куда записан ID?	Повторное чтение свойства элемента

Порядок действий

Назвать сущность, поле и владельца операции до подключения редактора.
Показать FileInput с ограничением количества и разрешённых типов.
Проверить POST на сервере и отклонить неожиданные поля или пустой ID.
Сохранить связь через API Bitrix и обработать `LAST_ERROR` или исключение.
Повторно прочитать свойство элемента и проверить опубликованный сценарий.
Для замены файла отдельно зафиксировать поведение старого файла и откат при ошибке.

Ограничения и безопасный следующий шаг

Названия параметров и доступные режимы зависят от версии Bitrix; перед переносом сверяйте API своего проекта.

Встроенный редактор не заменяет антивирусную и серверную проверку загрузки.

Пример не содержит реального ID или данных пользователя.

После проверки должен остаться конкретный артефакт: вывод команды, тест, diff конфигурации или запись результата. Если его нет, формулировку нужно вернуть к симптому и не выдавать гипотезу за исправление.

Что записать в ревью

Короткая запись должна отвечать на четыре вопроса: какой вход использовали, какой результат увидели, какая граница была проверена и какое действие разрешено дальше. Такая форма полезнее длинного вывода «всё работает»: другой инженер сможет повторить проверку и понять, где заканчивается пример.

Если результат зависит от версии Windows, PHP, Bitrix, D или браузера, версию фиксируем рядом с командой. Если проверка не охватывает сеть, production или реальные пользовательские данные, это ограничение пишем прямо. Тогда следующий шаг расширяет evidence, а не расширяет обещание.

Проверяемые источники

Bitrix: FileInput — показывает API компонента загрузки
Bitrix: CIBlockElement — описывает работу с элементом инфоблока
OWASP: File Upload Cheat Sheet — даёт независимый список серверных проверок