Инфоблоки тема 20 из 27

Картинки: ресайз и каталог загрузок

Группа /api/image отдаёт уменьшенные копии картинок для разметки витрины и список файлов каталога /upload/. Все методы открыты гостю и сессию не начинают.

в этой теме 6
  1. Методы картинок
  2. Ресайз: тип и размер
  3. Каталог загрузок
  4. Где настраиваются хосты и файлы картинок
  5. Ограничения ресайза
  6. Что почитать после картинок

Методы картинок

МетодАдресКто вызываетНачинает сессию
Уменьшенная копия по ID файлаGET /api/image/{resizeType}/{width}/{height}/{imageId}гость и вошедшийнет
Уменьшенная копия по пути или URLGET /api/image/{resizeType}/{width}/{height}?imagePath=...гость и вошедшийнет
Содержимое папки в /upload/GET /api/image/directory?path=/upload/...гость и вошедшийнет

Ресайз: тип и размер

resizeType — тип масштабирования:

ТипЧто делает
exactмасштабирует в прямоугольник width x height с сохранением пропорций, обрезая лишнее
proportionalмасштабирует с сохранением пропорций, размер ограничивается width x height
proportionalAltто же, но за ширину берётся максимум из высоты и ширины; лучше обрабатывает вертикальные картинки

width и height — размеры в пикселях, целые числа. Ответ — не JSON, а содержимое картинки с заголовками кеша браузера, поэтому адрес подставляется прямо в src.

По ID файла

ID файла Битрикса (например, из полей элемента):

html
<img src="https://example.ru/api/image/exact/200/200/1024">
bash
curl -o preview.jpg "https://example.ru/api/image/exact/200/200/1024"

По пути или URL

Когда ID файла нет, адрес передаётся параметром imagePath: путь на сайте (/upload/...) или полный URL.

html
<img src="https://example.ru/api/image/proportional/400/400?imagePath=/upload/iblock/abc/photo.jpg">

Исходник — JPEG, PNG или WebP. Внешний URL принимается только с хоста сайта, хоста папки UPLOAD или из списка разрешённых хостов (адреса локальной сети запрещены всегда).

Ошибки ресайза

json
{
    "success": false,
    "error": "Неизвестный тип ресайза: exact, proportional или proportionalAlt"
}
СтатусКогда
400resizeType не exact, не proportional и не proportionalAlt (ресайз по пути); исходник не JPEG, PNG и не WebP
403URL с хоста, которого нет в списке разрешённых
404по адресу нет файла или он не картинка

Каталог загрузок

GET /api/image/directory?path=/upload/brand/ — файлы папки для выбора в редакторе контента. Путь должен начинаться с /upload/ и лежать глубже самого /upload/: параметр path нужно передавать всегда (без него берётся сам /upload/ и ответ — 403). Выход через .. тоже запрещён (403).

json
{
    "data": {
        "0a1": ["/upload/iblock/0a1/upat2ucqeplyti3owxgl2y6tw6vt2qai.jpg"],
        "0a2": ["/upload/iblock/0a2/a35rt5u0ozf3kopunldixcaz2af5wuvt.jpg"]
    }
}

Файлы папки — массив путей, вложенные папки — ключи с массивами их файлов. Глубина — 2 уровня: файлы папки и файлы вложенных папок; у папок третьего уровня остаются только названия (пустой массив). Если папки нет, data = []. Результат кешируется.

Где настраиваются хосты и файлы картинок

Настройки модуля -> вкладка «Основное»:

ОпцияНа что влияет
«Хост папки UPLOAD, если файлы отдаются с другого адреса»картинки с этого хоста ресайз считает своими
«Сайты, с которых /api/image может брать внешние картинки»список хостов для внешних URL; допустимы маски, см. Маски хостов картинок
«Типы файлов в списке /api/image/directory»расширения файлов, которые видны в каталоге

Размеры картинок в ответах инфоблоков (анонс, детальная, MORE_PHOTO) задаются не здесь, а в наборе элемента: Состав ответа.

Ограничения ресайза

  • Адреса ресайза по пути принимают путь только параметром imagePath.
  • Часть ошибок приходит телом {errors: [...]}, часть — {success: false, error: текст} (например, 403 каталога приходит в первой форме): читайте текст из error или errors[0].message.

Что почитать после картинок

Подключим BIK.REST-API к вашему сайту

Оставьте заявку — установим и настроим модуль, ответим на вопросы по API.

c заботой о вас, мы используем cookie на своем сайте, чтобы интернет был чистым и прекрасным