README

此插件处于测试版，不应在生产环境中使用

安装

composer require craftsnippets/craft-image-helpers

用法

craft.imageHelpers.picture(image, transform, htmlAttributes)

此函数从图像资源对象生成 <picture> HTML 元素。

如果已安装 imager 或 imager-x，插件默认会使用它们中的任何一个进行图像转换。否则，将使用原生 Craft 图像转换。对于 SVG 图像，除非在设置中另行决定，否则将使用原生 craft 转换而不是 Imager。这是因为 Imager 与 SVG 一起使用可能会导致问题。

函数的第一个参数应包含图像对象（不是查询对象 - 因此对于条目的资产字段，应为 entry.assetField.one() 而不是 entry.assetField）。

第二个参数是包含图像转换设置的数组。这些设置可以与原生 Craft 图像转换中使用的设置相同。转换设置实际上是可选的 - 您可以在不提供这些设置的情况下使用 picture() 函数。这在这种情况下是有意义的，如果您只想利用下面描述的 webp 创建功能。

函数的第三个，可选参数可以包含一个数组，该数组包含将设置在 <img> 元素内的 <picture> 上的 HTML 属性。这些设置需要与 tag() 或 attr() Twig 函数接受的格式相同。有关这些函数的更多信息，请参阅这篇文章。

如果图像缺失（图像对象等于 null），则将根据转换的 width 和 height 设置生成占位符。如果缺少 width 或 height，则占位符将根据 width/height 形成正方形。占位符是内联 SVG 图像，具有特定的 CSS 类，可将其与其他非占位符图像区分开来，并允许您对其进行样式设置。

将自动创建图像的附加 webp 版本，作为图片元素中的一个 <source>，假设以下条件成立：

我们未在插件设置文件中禁用该行为，使用 useWebp 设置。
图像不是 SVG 格式。
我们未在转换设置中将该行为禁用，对于特定的图片添加 useWebp 设置为 false。
我们的服务器支持 webp 图像。
我们尚未将图像转换设置为 webp（这将创建两个相同的 webp 变体）。
我们的源图像不是 webp，未在转换设置中设置格式（这也会创建两个相同的 webp 变体）。

包含 webp 版本的 <source> 将具有 type 属性设置为 image/webp，因此不支持 webp 的浏览器将能够使用具有其他格式的 <source>。这将是在转换设置中设置的格式，或者未指定格式 - 包含原始格式图像的源。

如果您使用imager-x（或imager），您可能需要在转换设置中设置额外的filenamePattern参数。这将允许您设置转换文件名模式。更多信息请参阅imager-x文档。

craft.imageHelpers.pictureMedia(image, transforms, commonSettings, htmlAttributes)

此函数将生成具有多个来源的<picture>元素，每个来源基于特定的图像转换，并为特定的媒体查询显示。transforms数组需要按如下结构组织

{
	'(max-width: 600px)': {
		width: 100,
		height: 200,
		mode: 'crop',
	},
	'(max-width: 999px)': {
		width: 400,
		height: 500,
		mode: 'fit',
	},
	'(min-width: 1000px)': null,
}

这将渲染<picture>如下（出于简洁考虑，禁用了webp版本生成）

<picture>
<source type="image/jpeg" srcset="http://test/web/img/_100x200_crop_center-center_none/x.jpg" media="(max-width: 600px)">
<source type="image/jpeg" srcset="http://test/web/img/_400x500_fit_center-center_none/x.jpg" media="(max-width: 999px)">
<source srcset="data:image/svg+xml;charset=utf-8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%220%22%20height%3D%220%22%2F%3E" media="(min-width: 1000px)">
<img class="zzz" src="http://test/web/img/_100x200_crop_center-center_none/x.jpg">
</picture>

以下是一些需要注意的事项

数组键是用于每个<source> media属性的媒体查询字符串。
数组值是每个来源的转换设置。
如果数组值设置为null，这意味着对于特定的断点<source>将只包含透明像素。如果我们不想在特定断点显示图片，这很有用——如果我们只是用CSS隐藏它，浏览器仍然会下载它。
图片元素包含一个<img>标签，该标签作为不支持<picture>的浏览器的回退（有关支持信息，请参阅caniuse）。第一个图像转换将用于回退图像。

函数的第三个参数commonSettings包含适用于所有转换的通用转换设置。它可以用来避免为每个转换设置相同的设置。

例如，此代码

{% set sources = {
    '(min-width: 1000px)': {
        width: 500,
        height: 200,
    },
    '(max-width: 999px)': {
        width: 200,
        height: 200,
    },    
} %}
{% set common = {
    format: 'png',
    mode: 'stretch',
} %}

{{craft.imageHelpers.pictureMedia(glob.pole.one(), sources, common,{
    class: 'some-class',
})}}

将生成具有每个源为png格式和转换模式stretch的<picture>。请注意，单个转换的设置将覆盖来自commonSettings的任何冲突设置。

除此之外，pictureMedia()的行为与picture()相同——它可以生成图像的占位符或webp版本。

craft.imageHelpers.pictureMin(image, transforms, commonSettings, htmlAttributes)

此函数的行为与pictureMedia()类似，但我们不使用媒体查询字符串作为转换数组键。我们使用最小屏幕宽度。这将在内部转换为适当的断点。因此，例如

{
	300: {
		width: 100,
		height: 200,
		mode: 'crop',
	},
	600: {
		width: 400,
		height: 500,
		mode: 'fit',
	},
}

这将生成如下<picture>元素

<picture>
<source type="image/jpeg" srcset="http://test/web/img/_100x200_crop_center-center_none/x.jpg" media="(min-width: 600px)">
<source type="image/jpeg" srcset="http://test/web/img/_400x500_fit_center-center_none/x.jpg" media="(min-width: 300px)">
<img class="zzz" src="http://test/web/img/_100x200_crop_center-center_none/xt.jpg">
</picture>

请注意，浏览器将使用符合媒体查询的第一个<source>。因此，如果您在宽度为1024px的屏幕上，并且第一个来源具有媒体查询(min-width: 300px)，则将使用它——即使存在其他来源，其设置是(min-width: 600px)。这就是为什么在这个函数中，来源是从最大最小宽度排序到最小。

craft.imageHelpers.pictureMax(image, transforms, commonSettings, htmlAttributes)

与pictureMin()相同，但我们使用max-width媒体查询。来源将按max-width值从小到大排序。

craft.imageHelpers.placeholder(transform)

此函数将根据内联SVG图像生成占位符。您可以将图像转换设置数组传递给它——此数组中的width和height值将被使用。

如果只提供宽度或只提供高度，则图像将呈现为正方形。

设置

将这些设置放置在 config/image.helpers.php

useWebp - 如果应该自动生成图片的webp版本。默认值：true。
useImager - 如果应该使用imager或imager-x进行转换（假设已安装这些插件之一）。默认值：true。
usePlaceholders - 如果图片缺失（图片对象等于 null）时应该生成占位符。默认值：true。
placeholderClass - 如果显示占位符图片，则添加到 <picture> 元素的CSS类。默认值：is-placeholder。
useImagerForSvg - 如果imager也应该用于SVG图片。默认值：false。

craftsnippets / craft-image-helpers

维护者

详细信息