Руководство по использованию CFile::ResizeImageGet в 1С-Битрикс

В этом руководстве мы подробно рассмотрим один из важнейших инструментов работы с изображениями в 1С-Битрикс — статический метод CFile::ResizeImageGet. Он позволяет автоматически создавать уменьшенные копии (т.н. «превью») изображений, а также накладывать фильтры (например, «шарпинг» или водяной знак). Ниже мы разберём его параметры, особенности кэширования и покажем, как эффективно применять его в ваших проектах.

1. Назначение и принцип работы CFile::ResizeImageGet

Метод CFile::ResizeImageGet берёт исходный файл (по идентификатору или массиву описания) и генерирует уменьшенную копию, которую затем помещает в специальную кэш-папку:

/upload/resize_cache/...

Это даёт целый ряд преимуществ:

1. Уменьшенное изображение физически хранится на сервере. При повторном обращении к тому же файлу с теми же параметрами масштабирования сервер не будет тратить ресурсы на повторную обработку.
2. Гибкие настройки и фильтры. Вы можете не только изменить размеры картинки, но и улучшить её чёткость (фильтр sharpen), наложить водяной знак или задать качество сжатия JPEG.
3. Удобная дальнейшая работа с полученными миниатюрами. Метод возвращает массив, содержащий путь к уменьшенной картинке (src), а также (при необходимости) ширину и высоту миниатюры.

2. Сигнатура метода и основные параметры

Метод описан в файле bitrix/modules/main/classes/general/file.php и имеет следующий формат:

array CFile::ResizeImageGet(
    mixed file,
    array arSize,
    const resizeType = BX_RESIZE_IMAGE_PROPORTIONAL,
    bool bInitSizes = false,
    array arFilters = false,
    bool bImmediate = false,
    bool jpgQuality = false
);

Рассмотрим каждый параметр подробнее:

1. file
   • Может быть идентификатором файла (число) из таблицы b_file
   • Или массивом вида Array("FILE_NAME", "SUBDIR", "WIDTH", "HEIGHT", "CONTENT_TYPE"), который обычно возвращается методом CFile::GetFileArray().
2. arSize
   • Массив с ключами width и height, задающими желаемые размеры миниатюры:

   array("width" => 150, "height" => 150)

   • Оба параметра (width, height) должны присутствовать.
3. resizeType
   • Константа, определяющая принцип масштабирования:
   • BX_RESIZE_IMAGE_EXACT — «Жесткое» масштабирование в заданные width × height с сохранением пропорций и обрезанием лишнего.
   • BX_RESIZE_IMAGE_PROPORTIONAL — Пропорциональное уменьшение (или увеличение) изображения, вписываясь в прямоугольник width × height.
   • BX_RESIZE_IMAGE_PROPORTIONAL_ALT — Улучшенный алгоритм пропорционального масштабирования, более корректно обрабатывающий вертикальные изображения.
4. bInitSizes
   • Логический флаг (true / false). Если true, то в результат вернутся точные размеры полученной миниатюры (width и height). Если false, возвратится 0 в полях размеров.
5. arFilters
   • Массив массивов, позволяющий применять фильтры к изображению.
   • Пример:

   array(
          array("name" => "sharpen", "precision" => 15)
        )

   • Фильтр sharpen используется по умолчанию для «подчёркивания» мелких деталей (повышения резкости) в миниатюрах.
   • Если вы хотите отключить повышение резкости (например, чтобы не получить артефакты у PNG с прозрачностью), можно указать precision = 0.
6. bImmediate
   • Логический флаг, который передаётся в обработчик события OnBeforeResizeImage. По смыслу указывает, нужно ли выполнить масштабирование сразу («неотложно») при вызове метода или, возможно, отложить.
7. jpgQuality
   • Числовое значение, определяющее качество JPEG в процентах. Чем больше значение, тем лучше качество, но больше итоговый размер файла.

3. Возвращаемый результат

Возвращается ассоциативный массив следующего вида:

array(
    "src"    => "...", // Путь к уменьшенному изображению относительно корня сайта
    "width"  => ...,   // Ширина миниатюры (если bInitSizes = true), иначе 0
    "height" => ...,   // Высота миниатюры (если bInitSizes = true), иначе 0
    "size"   => ...,   // Размер файла (в байтах), если в коде предусмотрена передача этого значения
);

В случае ошибки метод вернёт false.

4. Примеры использования на практике

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

4.1. Уменьшение аватарки пользователя

Предположим, у нас есть пользователь с ID = $uID, чьи данные мы хотим вывести и при этом сжать его фото до размеров 150×150:

//$uID - идентификатор пользователя
$uDBInfo = CUser::GetByID($uID);
if ($uInfo = $uDBInfo->GetNext())
{
    if ($uInfo['PERSONAL_PHOTO'])
    {
        $file = CFile::ResizeImageGet(
            $uInfo['PERSONAL_PHOTO'],
            array('width' => 150, 'height' => 150),
            BX_RESIZE_IMAGE_PROPORTIONAL,
            true
        );

        $img = '';
        $uInfo['PERSONAL_PHOTO'] = $img;
    }

    $arResult['ITEMS'][$k]['USER_INFO'] = $uInfo;
}

Здесь мы:

1. Получаем данные пользователя.
2. Проверяем, что у него есть фотография.
3. Вызываем ResizeImageGet, указывая нужные размеры и тип масштабирования.
4. Сохраняем результат в виде тега img для удобного вывода на странице.

4.2. Наложение водяного знака

Чтобы добавить водяной знак, нам нужно передать массив фильтров с типом «image» и указанием пути к файлу водяного знака. Например:

$arWaterMark = array(
    array(
        "name"     => "watermark",
        "position" => "bottomright",       // Позиция
        "type"     => "image",
        "size"     => "real",
        "file"     => $_SERVER["DOCUMENT_ROOT"].'/upload/copy.png',
        "fill"     => "exact",
    )
);

$arFileTmp = CFile::ResizeImageGet(
    $arElement["DETAIL_PICTURE"],
    array("width" => 250, "height" => 127),
    BX_RESIZE_IMAGE_EXACT,
    true,
    $arWaterMark
);

Параметр position задаёт расположение водяного знака (например, bottomright — справа снизу).

fill со значением exact означает «заполнить» водяным знаком указанное пространство.

4.3. Отключение фильтра «sharpen» (пример для PNG)

Если у вас возникают артефакты (например, ореолы и некорректная полупрозрачность) при автоматическом применении sharpen, вы можете обнулить его:

$arPhotoSmall = CFile::ResizeImageGet(
   $arElement["PREVIEW_PICTURE"]["ID"],
   array('width' => 100, 'height' => 420),
   BX_RESIZE_IMAGE_PROPORTIONAL,
   true,
   array(
      array("name" => "sharpen", "precision" => 0)
   )
);

Обратите внимание, что precision = 0 фактически «отключает» данный фильтр.

4.4. Генерация миниатюр для дополнительных фотографий (more_photo)

Часто в каталоге или карточке товара выводят сразу несколько фотографий: основное изображение и «галерею» (more_photo). Для каждой дополнительной картинки можно сделать миниатюру, а при клике — показать полноразмерную версию:

<? if (count($arResult["MORE_PHOTO"]) > 0): ?>
    <? foreach ($arResult["MORE_PHOTO"] as $PHOTO): ?>
        <? $file = CFile::ResizeImageGet(
                $PHOTO,
                array('width' => 120, 'height' => 120),
                BX_RESIZE_IMAGE_EXACT,
                true
        ); ?>

        <a href="<?=$PHOTO["SRC"]?>" name="more_photo" target="_blank">
            <img border="0"
                 src="<?=$file["src"]?>"
                 width="<?=$file["width"]?>"
                 height="<?=$file["height"]?>"
                 alt="<?=$arResult["NAME"]?>"
                 title="<?=$arResult["NAME"]?>" />
        </a>

    <? endforeach; ?>
<? endif ?>

Здесь важно:

• Использовать одинаковые размеры (120×120) и тип BX_RESIZE_IMAGE_EXACT, чтобы все миниатюры были одинаковы по ширине/высоте и красиво выстраивались в сетку.
• При клике мы ведём пользователя на полный размер, который находится в $PHOTO["SRC"].

5. Рекомендации по оптимизации и особенностям кэширования

1. Проверяйте наличие исходного файла. Если передан неверный идентификатор или файл не существует, метод вернёт false.
2. Используйте корректные типы масштабирования.
   • BX_RESIZE_IMAGE_EXACT обрезает лишнюю область, если пропорции не совпадают.
   • BX_RESIZE_IMAGE_PROPORTIONAL уменьшает, сохраняя пропорции, вплоть до полного вхождения в заданные размеры.
   • BX_RESIZE_IMAGE_PROPORTIONAL_ALT — то же, но более «дружественно» к вертикальным картинкам.
3. Экспериментируйте с качеством JPEG (jpgQuality).
   • Слишком высокое качество приводит к очень большим «весам» картинок и замедляет загрузку.
   • Слишком низкое качество приводит к пикселизации и потере чёткости.
4. Учтите, что метод кэширует результат. Повторное обращение с теми же параметрами масштабирования вернёт уже существующее изображение, не тратя время на перерасчёт.
5. Отключайте sharpen, если картинка с прозрачностью выглядит искажённой. Для этого указывайте precision = 0 в фильтре.
6. При работе с водяными знаками (или другими фильтрами) будьте аккуратны с размерами. Если исходное изображение маленькое, водяной знак может занять большую часть картинки.

6. Заключение

Метод CFile::ResizeImageGet является универсальным инструментом в 1С-Битрикс для генерации миниатюр, наложения фильтров и оптимизации изображений. Его главные преимущества — кэширование уменьшенных файлов и возможность гибкой настройки масштабирования под различные задачи: создание галерей, аватаров пользователей, превью к новостям, брендинг изображений с помощью водяного знака и т.д.

Используйте его возможности, чтобы оптимизировать вывод графики на вашем сайте и ускорить загрузку страниц. Грамотное применение CFile::ResizeImageGet поможет достичь аккуратного и профессионального внешнего вида вашего проекта на 1С-Битрикс при одновременном учёте требований поисковых систем (скорость загрузки, удобство для пользователей) и актуальных трендов веб-разработки.