image 标记将 XHTML 兼容的 img 元素插入页面中，设置其 src 、 width 、 height 和 alt 。另请参见 对 img 标签的更多控制 。

该标签的语法如下：

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

图像和调整大小规则都必须传递给模板标记。

示例：

{% load wagtailimages_tags %}
...

<!-- 显示缩放至 400 像素宽度的图像：-->
{% image page.photo width-400 %}

<!-- 再次显示，但这次显示为方形缩略图：-->
{% image page.photo fill-80x80 %}

在上面的语法示例中， [image] 是引用图像的 Django 对象。如果您的页面模型定义了一个名为“照片”的字段，那么 [image] 可能是 page.photo 。 [resize-rule] 定义图像插入页面时如何调整大小。支持各种调整大小方法，以满足不同的使用情况（例如，跨越页面整个宽度的引导图像，或将缩略图裁剪为固定大小）。

请注意， [image] 和 [resize-rule] 之间以空格分隔，但调整大小规则不得包含空格。宽度始终在高度之前指定。除非使用 fill 规则，否则调整大小的图像将保持其原始宽高比，这可能会导致某些像素被裁剪。

多种格式

要以多种格式呈现图像，可以使用 picture 标签：

{% picture page.photo format-{avif,webp,jpeg} width-400 %}

与 image 相比，这将呈现一个 <picture> 元素，其中包含一个后备 <img> 元素，每个额外的格式一个 <source> 元素。浏览器选择它支持的第一种格式，或者默认使用后退 <img> 元素。例如，上面的代码将呈现如下 HTML：

<picture>
    <source srcset="/media/images/pied-wagtail.width-400.avif" type="image/avif">
    <source srcset="/media/images/pied-wagtail.width-400.webp" type="image/webp">
    <img src="/media/images/pied-wagtail.width-400.jpg" alt="A pied Wagtail" width="400" height="300">
</picture>

在这种情况下，如果浏览器支持 AVIF 格式，它将加载 AVIF 文件。否则，如果浏览器支持 WebP 格式，它将尝试加载 WebP 文件。如果这些格式都不受支持，浏览器将加载 JPEG 图像。所提供格式的顺序是不可配置的- Wagtail 将始终以以下顺序输出源元素:AVIF, WebP, JPEG, PNG, GIF。这确保尽可能提供最优化的格式。

picture 标签还可以与多个调整图像大小规则一起使用，以生成响应式图像。

响应式图像

Wagtail 提供了 picture 和 srcset_image 模板标签，它们可以生成带有 srcset 属性的图像元素。这允许浏览器根据响应式图像规则选择最合适的图像文件来加载。

srcset_image 的语法与 image 相同，但有两个例外：

{% srcset_image [image] [resize-rule-with-brace-expansion] sizes="[my source sizes]" %}
  • resize 规则应该以大括号扩展模式提供多个大小，如 width-{200,400} 。这将生成 srcset 属性，其中包含与 resize 规则中定义的大小一样多的 URL，以及每个 URL 一个宽度描述符。提供的第一个大小将始终用作 src 属性，并定义图像的宽度和高度属性作为回调。
  • sizes 属性是必不可少的。这告诉浏览器图像在页面上显示的大小，以便它可以选择最合适的图像来加载。

下面是一个 srcset_image 的例子，它生成了一个 srcset 属性：

{% srcset_image page.photo width-{400,800} sizes="(max-width: 600px) 400px, 80vw" %}

输出为：

<img srcset="/media/images/pied-wagtail.width-400.jpg 400w, /media/images/pied-wagtail.width-800.jpg 800w" src="/media/images/pied-wagtail.width-400.jpg" alt="A pied Wagtail" sizes="(max-width: 600px) 400px, 80vw" width="400" height="300">

这里有一个 picture 标签的例子:

{% picture page.photo format-{avif,webp,jpeg} width-{400,800} sizes="80vw" %}

输出为：

<picture>
    <source sizes="80vw" srcset="/media/images/pied-wagtail.width-400.avif 400w, /media/images/pied-wagtail.width-800.avif 800w" type="image/avif">
    <source sizes="80vw" srcset="/media/images/pied-wagtail.width-400.webp 400w, /media/images/pied-wagtail.width-800.webp 800w" type="image/webp">
    <img sizes="80vw" srcset="/media/images/pied-wagtail.width-400.jpg 400w, /media/images/pied-wagtail.width-800.jpg 800w" src="/media/images/pied-wagtail.width-400.jpg" alt="A pied Wagtail" width="400" height="300">
</picture>

可用的调整大小方法

可用的调整大小方法如下：

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

覆盖给定的尺寸。

这可能会导致图像略大于您指定的尺寸。使用 min-500x200 规则处理宽度为 2000、高度为 2000 的方形图像，其高度和宽度将更改为 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 %}

调整大小并裁剪以填充指定的精确尺寸。

这对于需要任意图像的方形缩略图的网站特别有用。例如，使用 fill-200x200 规则处理宽度为 2000、高度为 1000 的风景图像时，其高度将减小为 200，然后其宽度（通常为 400）将裁剪为 200。

如果已设置，此调整大小规则将裁剪到图像的焦点。如果没有，它将裁剪到图像的中心。

Example of fill filter on an image

示例：图像被缩放并被裁剪（红线），以尽可能多地适应所提供的尺寸内的图像。

在不会升级的图像上

可以请求具有 fill 尺寸的图像，而该图像在不升级的情况下无法支持。例如，使用 fill-400x400 请求宽度 400、高度 200 的图像。在这种情况下，请求的填充比例将匹配，但尺寸不会匹配。因此，示例 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 也不支持升级。被迫以较大尺寸显示的小图像将以其原始尺寸“最大化”。 {class="text-info"}

对 img 标签的更多控制

Wagtail 提供了两个快捷键来更好地控制 img 元素：

1.为 {% image %} 标签添加属性

可以使用语法 attribute="value" 指定额外属性：

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

您可以通过这种方式设置更相关的 alt 属性，覆盖从图像标题自动生成的属性。如有必要，还可以覆盖 src 、 width 和 height 属性。

您还可以向所有图像添加默认属性（例如默认类或数据属性） - 请参阅 Adding default attributes to all images 。

2. 生成图像“as foo”来访问各个属性

Wagtail 可以使用 Django 的 as 语法将图像数据分配给另一个变量，以访问底层图像呈现 ( renditions ) ( tmp_photo )：

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

这也可以用 srcset_image 标签，检索多个大小的呈现:

{% srcset_image page.photo width-{200,400} as tmp_photo %}

<img
    src="{{ tmp_photo.renditions.0.url }}"
    width="{{ tmp_photo.renditions.0.width }}"
    height="{{ tmp_photo.renditions.0.height }}"
    alt="{{ tmp_photo.renditions.0.alt }}"
    srcset="{{ tmp_photo.renditions.0.url }} 200w, {{ tmp_photo.renditions.1.url }} 400w"
    sizes="100vw"
    class="my-custom-class"
/>

并且使用 picture 标签，检索多种格式：

{% picture page.photo format-{avif,jpeg} as tmp_photo %}

{{ tmp_photo.avif.0.url }}
{{ tmp_photo.jpeg.0.url }}

注意：
用于 src 属性的图像属性是 image.url ，而不是 image.src 。 {class="text-info"}

“呈现”包含特定于您请求使用调整大小规则、尺寸和源 URL 格式化图像的方式的信息。可以使用以下属性：

url

已调整大小的图像版本的 URL。这可能是本地 URL（例如 /static/images/example.jpg ）或完整 URL（例如 https://assets.example.com/images/example.jpg ），具体取决于 static 文件的配置方式。

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 应用程序来指定要添加到图像的其他属性。这是通过在项目文件夹（即包含顶级设置和 url 模块的包）中设置自定义 AppConfig 类来完成的。

为此，请使用以下内容创建或更新现有的 apps.py 文件：

from wagtail.images.apps import WagtailImagesAppConfig


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

然后，将 settings.INSTALLED_APPS 中的 wagtail.images 替换为 CustomUsersAppConfig 的路径：

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

现在，使用 {% image %} 创建的图像将额外具有 decoding="async" loading="lazy" 属性。这也适用于添加到富文本和 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 文档中的 Mountains example ）：

{% 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 (HTML) ）。

模板开发人员无法轻松控制嵌入在富文本字段中的图像。没有可使用的图像对象，因此无法使用 {% image %} 模板标签。相反，编辑者可以在将图像插入文本时从多种图像“格式”中选择一种。

Wagtail 具有三种预定义的图像格式，但开发人员可以在 Python 中定义更多图像格式。这些格式是：

Full width

使用 width-800 创建图像再现，给出标记 CSS 类 full-width 。

Left-aligned

使用 width-500 创建图像再现，给出标记 CSS 类 left 。

Right-aligned

使用 width-500 创建图像再现，给出标记 CSS 类 right 。

注意：
添加到图像的 CSS 类不附带任何随附的样式表或内联样式。例如，默认情况下， left 类不会执行任何操作。开发人员需要将这些类添加到他们的前端 CSS 文件中，以准确定义他们想要 left 、 right 或 full-width 的含义。 {class="text-info"}

有关图像格式的更多信息，包括创建您自己的图像格式，请参阅 Image Formats in the Rich Text Editor 。

输出图像格式

Wagtail 在调整某些图像大小时可能会自动更改其格式：

  • PNG 和 JPEG 图像不改变格式
  • 没有动画的 GIF 图像将转换为 PNG
  • AVIF 图像被转换为 PNGs
  • BMP 图像转换为 PNG
  • WebP 图像转换为 PNG

还可以在调整大小规则后使用 format 过滤器覆盖每个标签的输出格式。

例如，要使标签始终将图像转换为 JPEG，请使用 format-jpeg ：

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

您也可以使用 format-png 或 format-gif 。

无损 AVIF 和 WebP

您可以使用 format-avif-lossless 或 format-webp-lossless 滤镜将图像编码为无损 AVIF 或 WebP 格式：

{% image page.photo width-400 format-avif-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 %}

Image quality

Wagtail 的 JPEG 图像质量设置默认为 85 (这是相当高的)。AVIF 和 WebP 默认为 80。这可以在全局或基于每个标签的基础上进行更改。

Changing globally

使用 WAGTAILIMAGES_AVIF_QUALITY ， WAGTAILIMAGES_JPEG_QUALITY 和 WAGTAILIMAGES_WEBP_QUALITY 设置更改 AVIF ， JPEG 和 WebP 质量的全局默认值：

# settings.py

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

请注意，这不会影响任何以前生成的图像，因此您可能需要删除所有再现，以便它们可以使用新设置重新生成。这可以从 Django shell 完成：

# 如果您使用自定义再现模型，请将其替换为您的自定义再现模型
>>> from wagtail.images.models import Rendition
>>> Rendition.objects.all().delete()

您还可以直接使用控制台中的图像管理命令来重新生成再现：

./manage.py wagtail_update_image_renditions --purge

您可以从 wagtail_update_image_renditions 阅读有关此命令的更多信息

Changing per-tag

通过使用 avifquality ， jpegquality 和 webpquality 过滤器，还可以在各个标签上具有不同的 AVIF ， JPEG 和 WebP 质量。这将始终覆盖默认设置：

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

请注意，这对 PNG 或 GIF 文件没有影响。如果您希望所有图像都是低质量的，您可以将此过滤器与 format-avif ， format-jpeg 或 format-webp 一起使用（强制所有图像以 AVIF ， JPEG 或 WebP 格式输出）：

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

在 Python 中生成图像呈现

上述所有图像转换也可以直接在 Python 代码中使用。参见 Generating renditions in Python 。

SVG 图像

Wagtail 支持使用可缩放矢量图形和光栅图像。为了允许 Wagtail 用户上传和使用 SVG 图像，通过配置 WAGTAILIMAGES_EXTENSIONS 将“SVG”添加到允许的图像扩展列表中：

WAGTAILIMAGES_EXTENSIONS = ["gif", "jpg", "jpeg", "png", "webp", "svg"]

SVG 图像可以通过 iamge 模板标签包含在模板中，就像光栅图像一样。但是，目前不支持对 SVG 图像进行栅格化的操作。这包括直接的格式转换，例如 format-webp 和 bgcolor 指令。裁剪和调整大小操作不需要栅格化，因此可以自由使用(参见可用的调整大小的方法)。

image 标签的 preserve-svg 位置参数可用于将应用于 SVG 图像的操作限制为仅适用于不需要光栅化的操作。这在单个 image 标签声明应用于多个源图像的情况下可能很有用，例如：

{% for picture in pictures %}
    {% image picture fill-400x400 format-webp preserve-svg %}
{% endfor %}

在本例中，任何 SVG 图像对象将只对其应用 fill-400x400 操作，而光栅图像将同时应用 fill-400x400 和 format-webp 操作。如果在本例中未使用 preserve-svg 参数，则在尝试将 SVG 图像转换为 WebP 时将引发错误，因为如果没有光栅化库，这是不可能的。

安全注意事项

Wagtail 的底层图像库 Willow 被配置为通过拒绝可疑文件来减少已知的 XML 解析器漏洞(例如 billion laughs, quadratic blowup )。

当通过 image 标签在模板中包含 SVG 图像时，它们将被呈现为 html img 元素。在这种情况下，SVG 中的 script 元素将不会被执行，从而减轻了 XSS 攻击。

如果用户直接导航到 SVG 文件的 URL，则可能会执行嵌入式脚本，具体取决于服务器 / 存储配置。这可以通过为 SVG 响应设置适当的 Content-Security-Policy 或 Content-Disposition 头来缓解：

  • 设置 Content-Security-Policy: default-src ‘none’ 将阻止脚本被加载或执行(以及其他资源 - 更宽松的 script-src 'none' 策略也可能是合适的); 和
  • 设置 Content-Disposition:attachment 将导致文件被下载，而不是立即在浏览器中呈现，这意味着脚本不会被执行(注意：如果用户下载并随后在浏览器中打开 SVG 文件，这不会阻止脚本运行 )。

为特定响应设置报头所需的步骤会有所不同，这取决于 Wagtail 应用程序的部署方式。