Как использовать изображения в шаблонах

Тэг image вставляет совместимый с XHTML элемент img на страницу, устанавливая его src, width, height и alt. Смотрите также Больше управления тегом img.

Синтаксис тега:

{% image [image] [resize-rule] %}

И изображение, и правило изменения размера должны быть переданы тегу шаблона.

Например:

{% load wagtailimages_tags %}
...

<!-- Display the image scaled to a width of 400 pixels: -->
{% image page.photo width-400 %}

<!-- Display it again, but this time as a square thumbnail: -->
{% image page.photo fill-80x80 %}

В приведенном выше примере синтаксиса [image] — это объект Django, ссылающийся на изображение. Если в вашей модели страницы определено поле с именем «photo», то [image], вероятно, будет page.photo. [resize-rule] определяет, как изображение будет измененено по размеру при вставке на страницу. Поддерживаются различные методы изменения размера, чтобы удовлетворить различные потребности (например, изображения для заголовков, занимающие всю ширину страницы, или миниатюры, обрезаемые до фиксированного размера).

Обратите внимание, что пробел отделяет [image] и [resize-rule], но правило изменения размера не должно содержать пробелов. Ширина всегда указывается перед высотой. Изменённые по размеру изображения сохранят исходное соотношение сторон, за исключением использования правила fill, что может привести к обрезке некоторых пикселей.

Доступные методы изменения размера

Доступные методы изменения размера:

`max`

(принимает две размерности)

{% image page.photo max-1000x500 %}

Вписывание в заданные размеры.

Самая большая сторона будет уменьшена до соответствующей заданной размерности. Например, портретное изображение шириной 1000 пикселей и высотой 2000 пикселей, обработанное правилом max-1000x500 (формат пейзажа), приведет к уменьшению изображения так, чтобы высота была 500 пикселей, а ширина — 250 пикселей.

Example of max filter on an image

Пример: изображение сохранит свои пропорции, но впишется в заданные размеры (зеленая линия).

`min`

(принимает две размерности)

{% image page.photo min-500x200 %}

Заполнение заданных размеров.

Это может привести к тому, что изображение будет немного больше, чем заданные размеры. Квадратное изображение шириной 2000 пикселей и высотой 2000 пикселей, обработанное правилом min-500x200 , изменит высоту и ширину на 500, то есть, соответствует ширине правила изменения размера, но больше, чем высоте.

Example of min filter on an image

Пример: изображение сохранит свои пропорции, заполняя заданные размеры (зелёная линия) как минимум.

`width`

(принимает одну размерность)

{% image page.photo width-640 %}

Уменьшает ширину изображения до указанной размерности.

`height`

(принимает одну размерность)

{% image page.photo height-480 %}

Уменьшает высоту изображения до указанной размерности.

`scale`

(принимает процент)

{% image page.photo scale-50 %}

Изменяет размер изображения до указанного процента.

`fill`

(принимает две размерности и необязательный -c параметр)

{% image page.photo fill-200x200 %}

Изменяет размер и обрезает для заполнения точности заданных размеров.

Это может быть особенно полезно для веб-сайтов, требующих квадратных миниатюр произвольных изображений. Например, изображение пейзажа шириной 2000 пикселей и высотой 1000 пикселей, обработанное правилом fill-200x200 , уменьшит высоту до 200 пикселей, а затем ширину (обычно 400) обрезает до 200 пикселей.

Это правило изменения размера обрезает изображение до точки фокусировки, если она установлена. В противном случае обрезает по центру изображения.

Example of fill filter on an image

Пример: изображение масштабируется и обрезается (красная линия), чтобы максимально возможное изображение поместилось в заданные размеры.

На изображениях, которые не будут масштабироваться вверх

Возможно запросить изображение с fill размерами, которые изображение не может поддерживать без увеличения. Например, изображение шириной 400 пикселей и высотой 200 пикселей с запросом fill-400x400. В этой ситуации соотношение запрашиваемого заполнения будет соответствовать, но размер не будет. Так, например, изображение 400x200 (соотношение 2:1) может стать 200x200 (соотношение 1:1, соответствующее правилу изменения размера).

Обрезка ближе к точке фокусировки

По умолчанию Wagtail будет обрезать только достаточно, чтобы изменить соотношение сторон изображения на соотношение в правиле изменения размера.

В некоторых случаях (например, миниатюры) предпочтительнее обрезать ближе к точке фокусировки, чтобы объект изображения был более заметен.

Это можно сделать, добавив -c<percentage> в конце правила изменения размера. Например, если вы хотите, чтобы изображение обрезалось как можно ближе к своей точке фокусировки, добавьте -c100:

{% image page.photo fill-200x200-c100 %}

Это позволит обрезать изображение как можно больше, не обрезая при этом точку фокусировки.

Если вы обнаружите, что -c100 слишком близко, вы можете попробовать -c75 или -c50. Принимается любое целое число от 0 до 100.

Example of fill filter on an image with a focal point set

Пример: точка фокусировки смещена от центра, поэтому изображение масштабируется и обрезается, как заполнение, но точка центра обрезки размещается ближе к точке фокусировки.

Example of fill and closeness filter on an image with a focal point set

Пример: с установленным -c75, окончательная обрезка будет ближе к точке фокусировки.

`original`

(не принимает размерностей)

{% image page.photo original %}

Отображает изображение в исходном размере.

Примечание

Wagtail не позволяет изменять форму или растягивать изображения. Соотношения сторон изображения всегда сохраняются. Wagtail также не поддерживает увеличение изображения. Небольшие изображения, которые вынуждены отображаться в большем размере, будут «максимально» соответствовать своим исходным размерам.

Больше управления тегом `img`

Wagtail предоставляет два сокращения для большего контроля над элементом img:

1. Добавление атрибутов к тегу {% image %}

Дополнительные атрибуты можно указать с помощью синтаксиса attribute="value":

{% image page.photo width-400 class="foo" id="bar" %}

Таким образом, можно установить более релевантный alt атрибут, переопределив атрибут, автоматически сгенерированный из заголовка изображения. Также можно переопределить атрибуты src, width и height, если это необходимо.

Также можно добавить атрибуты по умолчанию ко всем изображениям (например, по умолчанию класс или атрибут данных) — см. Добавление атрибутов по умолчанию ко всем изображениям.

2. Генерация изображения «как foo» для доступа к отдельным свойствам

Wagtail может назначить данные изображения другой переменной, используя синтаксис Django as:

{% image page.photo width-400 as tmp_photo %}

<img src="{{ tmp_photo.url }}" width="{{ tmp_photo.width }}"
    height="{{ tmp_photo.height }}" alt="{{ tmp_photo.alt }}" class="my-custom-class" />

Примечание

Свойство изображения, используемое для атрибута src — это image.url, а не image.src.

Этот синтаксис предоставляет разработчику доступ к базовому представлению изображения (tmp_photo). «Представление» содержит информацию, специфичную для того, как вы запросили форматировать изображение с помощью правила изменения размера, размеров и исходного URL.

Доступны следующие свойства:

`url`

URL измененной версии изображения. Это может быть локальный URL (например, /static/images/example.jpg) или полный URL (например, https://assets.example.com/images/example.jpg), в зависимости от настройки статических файлов.

`width`

Ширина изображения после изменения размера.

`height`

Высота изображения после изменения размера.

`alt`

Альтернативный текст для изображения, обычно взятый из заголовка изображения.

`attrs`

Сокращение для вывода атрибутов src, width, height и alt сразу:

<img {{ tmp_photo.attrs }} class="my-custom-class" />

`full_url`

То же самое, что и url, но всегда возвращает полный абсолютный URL. Для этого необходимо установить WAGTAILADMIN_BASE_URL в настройках проекта.

Это полезно для изображений, которые будут повторно использоваться за пределами текущего сайта, например, для изображений для обмена в социальных сетях:

<meta name="twitter:image" content="{{ tmp_photo.full_url }}">

Если ваш сайт определяет пользовательскую модель изображения с помощью AbstractImage, любые дополнительные поля, которые вы добавите к изображению (например, правообладатель), не включаются в представление.

Поэтому, если вы добавили поле author в свой AbstractImage в приведенном выше примере, вы получите к нему доступ с помощью {{ page.photo.author }}, а не {{ tmp_photo.author }}.

(Из-за ссылок в базе данных между представлениями и их родительскими изображениями, вы можете получить к нему доступ как {{ tmp_photo.image.author }}, но это снижает читаемость.)

Добавление атрибутов по умолчанию ко всем изображениям

Мы можем настроить приложение wagtail.images для указания дополнительных атрибутов, которые нужно добавить к изображениям. Это делается путем настройки пользовательского класса AppConfig в папке вашего проекта (например, папке, содержащей модули верхнего уровня настроек и URL).

Для этого создайте или обновите существующий файл apps.py следующим образом:

from wagtail.images.apps import WagtailImagesAppConfig


class CustomImagesAppConfig(WagtailImagesAppConfig):
    default_attrs = {"decoding": "async", "loading": "lazy"}

Затем замените wagtail.images в settings.INSTALLED_APPS на путь к CustomUsersAppConfig:

INSTALLED_APPS = [
    ...,
    "myapplication.apps.CustomImagesAppConfig",
    # "wagtail.images",
    ...,
]

Теперь изображения, созданные с помощью {% image %} , будут дополнительно иметь атрибуты decoding="async" loading="lazy" . Это также относится к изображениям, добавленным в блоки Rich Text и ImageBlock.

Альтернативные HTML теги

Ключевое слово as позволяет использовать альтернативные HTML теги изображений (например, <picture> или <amp-img>). Например, для использования тега <picture>:

<picture>
    {% image page.photo width-800 as wide_photo %}
    <source srcset="{{ wide_photo.url }}" media="(min-width: 800px)">
    {% image page.photo width-400 %}
</picture>

И для использования тега <amp-img> (на основе примера «Горы» из документации AMP):

{% image image width-550 format-webp as webp_image %}
{% image image width-550 format-jpeg as jpeg_image %}

<amp-img alt="{{ image.alt }}"
    width="{{ webp_image.width }}"
    height="{{ webp_image.height }}"
    src="{{ webp_image.url }}">
    <amp-img alt="{{ image.alt }}"
        fallback
        width="{{ jpeg_image.width }}"
        height="{{ jpeg_image.height }}"
        src="{{ jpeg_image.url }}"></amp-img>
</amp-img>

Встроенные изображения в формате Rich Text

Указанная выше информация относится к изображениям, определенным в полях модели, специфичных для изображений. Однако изображения также могут быть произвольно встроены в поля Rich Text редактором страницы (см. Rich Text (HTML)).

Изображения, встроенные в поля Rich Text, не могут быть так легко контролированы разработчиком шаблона. Нет объектов изображений для работы, поэтому тег {% image %} шаблона использовать нельзя. Вместо этого редакторы могут выбрать один из нескольких форматов изображений при вставке изображений в текст.

Wagtail поставляется с тремя предопределенными форматами изображений, но разработчик может определить больше форматов на языке Python. Эти форматы:

`Full width`

Создаёт представление изображения, используя width-800, придавая тегу CSS-класс full-width.

`Left-aligned`

Создаёт представление изображения, используя width-500, придавая тегу CSS-класс left.

`Right-aligned`

Создаёт представление изображения, используя width-500, придавая тегу CSS-класс right.

Примечание

CSS-классы, добавляемые к изображениям, не поставляются с какими-либо связанными стилями CSS или встроенными стилями. Например, класс left по умолчанию не будет ничего делать. Разработчик должен добавить эти классы в свои файлы CSS для определения, что подразумевают left, right или full-width.

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

Формат выходного изображения

Wagtail может автоматически изменять формат некоторых изображений при их изменении размера:

Изображения PNG и JPEG не изменяют формат
Изображения GIF без анимации преобразуются в PNG
Изображения BMP преобразуются в PNG
Изображения WebP преобразуются в PNG

Также возможно переопределить формат вывода на основе тега, используя фильтр format после правила изменения размера.

Например, чтобы всегда преобразовывать изображение в JPEG, используйте format-jpeg:

{% image page.photo width-400 format-jpeg %}

Также можно использовать format-png или format-gif.

Беспотернющее WebP

Вы можете закодировать изображение в формат бес потерного WebP, используя фильтр format-webp-lossless:

{% image page.photo width-400 format-webp-lossless %}

Цвет фона

Форматы изображений PNG и GIF поддерживают прозрачность, но если вы хотите преобразовать изображения в формат JPEG, прозрачность нужно будет заменить твёрдым цветом фона.

По умолчанию Wagtail устанавливает фон в белый цвет. Но если белый фон не подходит для вашего дизайна, вы можете указать цвет, используя фильтр bgcolor.

Этот фильтр принимает один аргумент — шестнадцатеричный код цвета CSS из 3 или 6 символов, который вы хотите использовать:

{# Sets the image background to black #}
{% image page.photo width-400 bgcolor-000 format-jpeg %}

Качество изображения

Настройки качества изображений JPEG и WebP Wagtail по умолчанию установлены в 85 (что довольно высокое значение). Это можно изменить глобально или на основе отдельного тега.

Глобальное изменение

Используйте настройки WAGTAILIMAGES_JPEG_QUALITY и WAGTAILIMAGES_WEBP_QUALITY для изменения глобальных значений качества JPEG и WebP:

# settings.py

# Make low-quality but small images
WAGTAILIMAGES_JPEG_QUALITY = 40
WAGTAILIMAGES_WEBP_QUALITY = 45

Обратите внимание, что это не повлияет на ранее сгенерированные изображения, поэтому вы можете захотеть удалить все представления, чтобы они могли быть пересозданы с новым значением. Это можно сделать из оболочки Django:

# Replace this with your custom rendition model if you use one
>>> from wagtail.images.models import Rendition
>>> Rendition.objects.all().delete()

Вы также можете напрямую использовать команду управления изображениями из консоли для перегенерации представлений:

./manage.py wagtail_update_image_renditions --purge

Дополнительную информацию об этой команде можно найти в wagtail_update_image_renditions

Изменение по тегу

Также можно задавать разные значения качества JPEG и WebP для отдельных тегов, используя фильтры jpegquality и webpquality. Это всегда переопределит значение по умолчанию:

{% image page.photo_jpeg width-400 jpegquality-40 %}
{% image page.photo_webp width-400 webpquality-50 %}

Обратите внимание, что это не повлияет на файлы PNG или GIF. Если вы хотите, чтобы все изображения имели низкое качество, вы можете использовать этот фильтр с format-jpeg или format-webp (что принудительно делает все изображения выходными в формате JPEG или WebP):

{% image page.photo width-400 format-jpeg jpegquality-40 %}
{% image page.photo width-400 format-webp webpquality-50 %}

Генерация представлений изображений в Python

Все вышеупомянутые преобразования изображений также могут использоваться непосредственно в коде Python. См. Генерация представлений в Python.