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

Тег 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, что может привести к обрезке некоторых пикселей.

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

Больше контроля над тегом 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" />

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

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

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

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

Сокращение attrs

Вы также можете использовать свойство attrs в качестве сокращения для вывода атрибутов src, width, height и alt одним разом:

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

Альтернативные теги 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 https://amp.dev/documentation/components/amp-img/#example:-specifying-a-fallback-image):

{% 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>

Изображения, вставленные в форматированный текст

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

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

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

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

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

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.

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

{# 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()

Изменение для каждого тега

Также можно задать разное качество 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.