README

在优化图片的同时解锁隐藏武器库，节省时间和认知负荷。这是一个不错的交易。

需求

此插件需要 Imager X 4.5+/5.0+ 和 Craft CMS 4.0+/5.0+。

安装

要安装此插件，请按照以下说明操作

通过在项目目录中运行 composer require spacecatninja/imager-x-power-pack 使用 composer 安装。
在 Craft 控制面板的设置→插件下安装插件，或从命令行通过 ./craft plugin/install imager-x-power-pack 安装。

用法

Power Pack 包含一些方便的模板函数，可以帮助您制作最优化的响应式图片。它可能不适用于所有用例，并且有些主观，但旨在为您的 大多数 需求提供动力。

主要功能封装在 pppicture 模板函数中，用于快速简单地生成复杂的 <picture> 标记，以及 ppimg，用于生成单个 <img> 标签。这两个函数都假设您熟悉并利用了 srcset 和 sizes（您应该这样做）。它们还利用了 Imager 的命名转换和快速转换语法，以提供紧凑且易于维护的标记。

Power Pack 还包含一些配置设置，可用于自定义输出。例如，备用文本将自动从 Craft 的原生 alt 字段中提取，但您也可以配置它使用不同的字段。默认情况下，loading 策略将设置为 lazy，decoding 将设置为 auto，但您也可以在全局配置中更改，或者在模板中根据情况直接更改。默认情况下，SVG 和动画 GIF 不会进行转换，将按原样无缝使用，但您也可以重新配置，以便实际上让 Imager 处理它们。

还支持 出色的 lazySizes 库，这使得交付优化的图片更加容易和快速。只需启用 lazysizes 配置设置，如果您的代码中尚未包含 lazySizes JS 包，则可选地启用 autoloadLazysizes，然后您就完成了。

有关更多详细信息，请继续阅读。

模板函数

pppicture($sources[, $params=[], $config=[]])

输出带有所有功能的完整 <picture> 标签。

sources 参数是一个数组，其中每个源都有以下参数

[image, transform, mediaQuery, format]

image 和 transform 可以是您通常传递到 craft.imagerx.transformImage() 中的任何内容。最后两个参数与图片元素的源标签相关，并将添加 media 和/或 type 属性。让我们通过几个例子来说明。

让我们从简单开始，我们有一个经过艺术指导的图片，希望在浏览器宽度达到750px之前使用命名的转换mySmallTransforms，然后在使用myLargeTransforms。对于较小的尺寸，我们希望使用资产imageMobile，而对于较大尺寸则使用image。

{# Template code #}
{{ pppicture(
    [
        [image, 'myLargeTransforms', 750],
        [imageMobile, 'mySmallTransforms']
    ]
) }}

{# Resulting markup #}
<picture>
    <source srcset="..." 
        sizes="100vw"
        width="1200" height="675" 
        media="(min-width: 768px)"> 
    <img src="..." srcset="..." 
        sizes="100vw" 
        width="800" height="800" 
        alt="The quick brown fox jumps" 
        loading="lazy" decoding="auto" 
        style="object-position: 50% 50%;">
</picture>

有很多属性在发挥作用（我已经从src和srcset中移除了实际的转换以使内容更易于阅读），但关键在于我们有一个<picture>元素，其中包含一个具有媒体查询的<source>元素，该查询将触发浏览器宽度为768px及以上的情况，以及一个带有回退源的<img>元素和必要的属性。

让我们在此基础上添加对支持WebP的浏览器的额外支持。

{# Template code #}
{{ pictureMarkup = pppicture(
    [
        [image, 'myLargeWebpTransforms', 750, 'webp'],
        [image, 'myLargeTransforms', 750],
        [imageMobile, 'mySmallWebpTransforms', 'webp'],
        [imageMobile, 'mySmallTransforms']
    ]
) }}

{# Resulting markup #}
<picture>
    <source srcset="..." width="1200" height="675" media="(min-width: 768px)" type="image/webp" sizes="100vw">
    <source srcset="..." width="1200" height="675" media="(min-width: 768px)" sizes="100vw">
    <source srcset="..." width="800" height="800" type="image/webp" sizes="100vw">
    <img src="..." srcset="..." width="800" height="800" alt="The quick brown fox jumps" sizes="100vw" loading="lazy" decoding="auto" style="object-position: 50% 50%;">
</picture>

正如您所看到的，已经添加了额外的源，如果浏览器支持WebP，则将触发。

请注意，源的正确语法相当宽松，如果您不需要媒体查询作为第三个参数，只需添加格式即可。

当使用基于宽度的媒体查询时，建议仅使用一个整数作为最小宽度，如上所示。如果您这样做，Power Pack将能够对源进行排序，以确保顺序始终正确（记住，浏览器将选择与它匹配的第一个<source>，而不是最具体的源）。

但是，如果您想的话，也可以提供一个完整的媒体查询。所有这些示例都是有效的。

[image, 'myTransforms', 750]
[image, 'myTransforms', '(min-width: 750px)'] // same as the above
[image, 'myTransforms', '(max-width: 749px)'] // using max-width
[image, 'myTransforms', '(min-aspect-ratio: 16/9)'] // using aspect ratio maybe
[image, 'myTransforms', '(min-width: 1200px) and (orientation: landscape)'] // getting specific
[image, 'myTransforms', 'landscape'] // very nifty shortcut!

[image, 'myTransforms', 750, 'avif'] // and for format, you can do this
[image, 'myTransforms', 'avif'] // or this

除了sources参数外，pppicture还接受两个额外的参数；params，这是额外的参数，以及config，它将覆盖默认配置。以下示例显示了所有有效的参数，以及覆盖一些配置设置的示例。

{{ pppicture(
    [
        [image, [1000, 2000, 16/9], 768],
        [imageMobile, [500, 1000, 1]
    ],
    {
        sizes: '(min-width: 768px) 33vw, 100vw',
        class: 'absolute full',
        loading: 'eager',
        decoding: 'async',
        alt: 'This is a custom alternative text!',
        defaults: { effects: { sharpen: true } },
        imagerOverrides: {
            transformer: 'craft'
        }
    }, 
    {
        lazysizes: true,
        placeholder: 'blurhash'
    }) }}

最值得注意的是sizes，您必须提供它，以便浏览器知道图像的目标大小。默认值为100vw，这对于全宽图像是合适的，但请确保为其他内容进行自定义。除非您使用（令人惊叹的）lazySizes，在这种情况下，它将设置为auto，您将永远不必再考虑它。

class参数用于向<img>标签添加类，这不仅适用于<picture>内部的正常类，也适用于使用lazySizes时<noscript>标签内的回退图像。如果您想添加类或其他属性到图片标签本身，请使用输出直接上的本地attr过滤器。

所有最终成为标记属性的自定义参数都将通过与使用本地attr过滤器相同的过滤器。这意味着您可以向class和filter传递字符串，但您也可以使用类数组（例如class: ['absolute', 'full', shouldHaveSpecialClass ? 'special-class']）或对象表示法（例如style: { background: 'red' }）。

请注意，此示例使用Imager中的新快速语法，它提供了一种非常紧凑的方式来生成完整源集，如果您只需要一系列大小。

让我们以一个非常简单的示例来结束，该示例输出一个从1000px到2000px范围的响应式图像，16/9格式，可选支持WebP和Avif。

{{ pppicture(
    [
        [image, [1000, 2000, 16/9, 'avif'], 'avif'],
        [image, [1000, 2000, 16/9, 'webp'], 'webp'],
        [image, [1000, 2000, 16/9]]
    ]
) }}

ppimg($image, $transform[, $params=[], $config=[]])

输出单个<img>标签。它几乎与pppicture相同，但它接受image和transform参数，而不是sources数组。

一个简单的示例，创建一个带有基于配置的属性的单一<img>标签。

{# Template code #}
{{ ppimg(image, [1000, 2000, 16/9]) }}

{# Resulting markup #}
<img src="..." srcset="..." width="1000" height="563" alt="" sizes="100vw" loading="lazy" decoding="auto" style="object-position: 50% 50%;">

ppimg接受与pppicture相同的参数。

{{ 
    ppimg(image, 'myNamedTransform', {
        sizes: '(min-width: 1024px) calc(100vw-80px), calc(100vw-40px)'
        class: 'absolute full',
        loading: 'eager'
    }, {
        lazysizes: true,
        placeholder: 'blurhash'
    }) 
}}

ppplaceholder($image[, $output='attr', $type='dominantColor', $config=[]])

输出占位符，可以是完整的样式属性（当 output 设置为 attr 时），也可以是仅 CSS 样式（当 output 设置为 style 时）。默认情况下，创建一个主导色背景，但可以更改为占位符的有效值之一，例如 dominantColor、blurup 或 blurhash。

<div class="relative w-full h-0 pb-[56.25%]" {{ ppplaceholder(image, 'attr', 'blurup') }}>
    {{ 
        ppimg(image, [1000, 2000, 16/9], { class: 'absolute full' })
    }}
</div>

这是自动占位符功能的替代方案，它将占位符添加到 img 标签中，同时使用这两种方法没有意义。

请注意，使用此方法将使用原生的 craft 转换器创建一个转换后的图像。

顺便说一下，这是一个受益于命名参数的函数

{{ ppplaceholder(image, type='blurup')

pptransform($image, $transforms[, $defaults=null, $config=null])

这只是 craft.imagerx.transformImage 的包装，因为这样输入很多。它还尊重 transformSvgs 和 transformAnimatedGifs 配置设置，如果这些设置为 false，则资产将返回未转换的。

{% set transforms = pptransform(image, [1000, 2000]) %}
{{ transforms|srcset }}

配置

您可以通过在配置文件夹中创建一个名为 imager-x-power-pack.php 的文件来配置适配器，并根据需要覆盖设置。

altTextHandle [字符串]

默认：'alt'
要在图像标签上使用的资产字段处理程序名称。默认为内置的 alt 字段，但可以更改为自定义字段。

placeholder [字符串]

默认：''
可能的值：'', 'dominantColor', 'blurup', 'blurhash'
当启用时，将在图像标签上添加 CSS 占位符，并在图像加载前显示。

请注意，使用占位符功能将使用原生的 craft 转换器创建一个转换后的图像。

placeholderSize [整数]

默认：16
当使用 blurup 或 blurhash 风格的占位符时，这是生成并用作模糊占位符的小图像的基本大小（宽度）。更高的值将创建更详细的占位符，但会增加 base64 编码图像和文档大小。

blurupTransformParams [数组]

默认：['effects' => ['blur' => true]]
传递给 Imager 用于转换作为模糊占位符的图像的额外参数。默认添加标准模糊以改善视觉效果。

loading [字符串]

默认：'lazy'
设置图像标签的加载策略。通常希望将其设置为 'lazy'，但对于可能成为您的最大内容渲染时间 (LCP) 元素的图像，您希望使用 'eager'。

decoding [字符串]

默认：'auto'
设置图像标签的解码提示。

objectPosition [布尔值]

默认：true
当启用（默认）时，将自动添加一个 object-position CSS 样式，该样式使用 Craft 的焦点，以确保在图像用作具有不同宽高比的包装器时考虑图像的焦点。图像和包装器的样式由您负责添加。

defaultTransformParams [数组]

默认：[]
默认转换将合并到所有转换中。

如果您使用自动生成，请确保在命名转换中明确包含这些默认设置。否则，自动生成将毫无用处。

transformSvgs [布尔值]

默认：false
当禁用（默认状态）时，SVG 图像将不会被 Imager 转换，直接以原始形式输出到 pppicture 或 ppimg。会根据源文件添加 width 和 height 等属性。

这可能导致在使用过程中出现意外结果，因此请考虑此设置是否符合您的需求，或者您是否需要在外部处理此功能。

transformAnimatedGifs [布尔值]

默认：false
当禁用（默认状态）时，动画 GIF 不会通过 Imager 转换，直接以原始形式输出到 pppicture 或 ppimg。会根据源文件添加 width 和 height 等属性。

这可能导致在使用过程中出现意外结果，因此请考虑此设置是否符合您的需求，或者您是否需要在外部处理此功能。

lazysizes [布尔值]

默认：false
启用时，生成的标记将与（非常棒）的 lazySizes 库配合。将设置 data-sizes 为 auto，源文件集将放入 data-srcset 属性中，并自动创建一个带有备用图像的 <noscript> 标签。

lazysizesClass [字符串]

默认值：'lazyload'
lazySizes 配置使用的类名。

autoloadLazysizes [布尔值]

默认：false
当启用时，如果设置了 autoloadLazysizes，则会在需要时自动加载 lazysizesURL 中指定的懒加载包。

lazysizesURL [字符串]

默认值：'https://cdnjs.cloudflare.com/ajax/libs/lazysizes/5.3.2/lazysizes.min.js'
如果设置了 autoloadLazysizes 为 true，则将加载的懒加载包的 URL。

（但我们建议将 lazySizes 包含在自己的 JS 包中，这样您将拥有更多控制权）

价格、许可证和支持

此插件在 MIT 许可下发布。它需要 Imager X，这是一个商业插件，可在 Craft 插件商店中获取 [此处](https://plugins.craftcms.com/imager-x)。

spacecatninja / imager-x-power-pack

维护者

详细信息