Image — одно управляемое изображение, Gallery — упорядоченный набор. Вы загружаете файл, сервер обрабатывает его и создаёт нужные размеры. После сохранения записи изображение связывается с ней. Это отличается от строкового поля с произвольным URL.
Как добавить поле
В Content → Add field выберите Image или Gallery, укажите имя и профиль — например, cover для обложки или avatar для аватара. Проверьте размеры, качество и возможность оставить значение пустым. Нажмите Finish и выполните Generate.
| Параметр | По умолчанию | Что можно задать |
|---|---|---|
profile |
photo |
photo, avatar, cover, custom. |
formats |
jpeg,png,webp |
Один или несколько этих входных форматов, без повторений. |
maxCount |
10 | От 1 до 10 изображений в галерее. |
maxBytes |
10485760 | От 1 до 10485760 байт на файл. |
maxPixels |
25000000 | От 1 до 25000000 пикселей. |
quality |
85 | От 1 до 100. |
output |
auto |
auto, jpeg, png. |
aspect |
Исходные пропорции; для avatar — 1, для cover — 16/9 |
0 сохраняет пропорции; другое значение — от 0.01 до 100. |
sizes |
sm — 320, md — 768, lg — 1600 |
От 1 до 4 вариантов с width от 1 до 4096. Для avatar по умолчанию — 64/128/256. |
Имена sizes должны быть уникальными строчными идентификаторами. master зарезервирован для основного изображения.
Для image и gallery не поддерживаются первичный ключ, уникальность, индексы, общий поиск, сортировка, фильтрация, default, автогенерация, Hidden, Readonly и обычные ограничения скалярных полей. Необязательное поле image может хранить null.
Что происходит при загрузке
В форме записи выберите файл, для Gallery — несколько файлов в нужном порядке. Если отдельный файл не загрузился, повторите его загрузку или удалите из списка. Подготовленные изображения привяжутся к записи при её сохранении. Сам факт загрузки ещё не меняет сохранённую статью.
Обрезка, замена и Update sizes создают новую версию. Существующая опубликованная запись не меняется до сохранения. Новый выходной формат применяется при следующей обработке.
После нормализации ориентации исходный загруженный файл удаляется. Для повторной обрезки остаётся master в PNG; метаданные удаляются. Обработка не гарантирует точность печатных процессов и работу с ICC-профилями расширенного цветового охвата.
Где лежат файлы
Для локального диска MEDIA_ROOT задаёт абсолютный постоянный каталог вне исходников. Значение по умолчанию — ~/.local/share/<project>/media. Разным БД нужны разные каталоги. Для S3 используйте руководство по хранилищу.
Generate сохраняет реальные изображения и custom-код. Но некоторые изменения модели — переименование или удаление медиа-поля, переход между image и gallery, ужесточение обязательности — могут быть заблокированы до генерации.
Если вы впервые добавляете медиа в существующий проект, может потребоваться обновить зависимости вручную. Генератор не переписывает ваш go.mod и не устанавливает пакеты.
Что получает внешний клиент
External API persistent- и virtual-сущностей возвращает готовые ссылки:
{"image":{"assetId":"...","alt":"Интерфейс проекта","size":{"sm":"/api/external/v1/_media/.../files/sm","md":"/api/external/v1/_media/.../files/md","lg":"/api/external/v1/_media/.../files/lg"}}}
Ключи карты size соответствуют вариантам из настройки поля. Клиенту не нужен отдельный запрос метаданных. Галерея возвращает такие данные для каждого элемента. Публикуются только подготовленные варианты привязанного изображения; master не выдаётся. Контракт административной загрузки и выбора остаётся отдельным.
Полученный URL открывает файл. Если позже скрыть запись external-правилом, прежняя ссылка не отзывается. Текущий Cache-Control допускает кеширование на пять минут. Этот способ выдачи не предназначен для обещания закрытого доступа к конфиденциальным файлам.
Свой компонент или SQL
Собственный элемент управления подключайте через imageFields: он работает с готовыми типизированными ссылками. Если вы записываете данные своим SQL в обход сгенерированных репозиториев, поддерживайте реестр привязок самостоятельно. Иначе очистка не сможет правильно соотнести файлы и записи.
Дополнительно: настройка через CLI
Настройки поля можно передать JSON-параметром:
admingen-cli --path ./docs-demo field add Article cover --type image --nullable \
--image-settings '{"profile":"cover","quality":85,"output":"auto"}'
Как очистить непривязанные файлы
Очистка — отдельная операция обслуживания. Кнопки фоновой очистки в редакторе нет. Из каталога backend, с тем же окружением, что у приложения, выполните:
go run ./cmd/media-cleanup --limit 100
--limit принимает от 1 до 100. Удаляются просроченные данные без привязки к записям. Автоматическое расписание не создаётся. При создании снимка или восстановлении согласованно остановите и запись, и очистку.
Поля формы описаны в Content: изображения, размещение файлов — в эксплуатации хранилища, очистка — в командах приложения.