README

生成 <picture> 元素。

查看 v1 分支查看 Craft 2 版本，查看 v2 分支查看 Craft 3 和 4 版本

安装

1. 从您的项目目录使用 Composer 安装 composer require marionnewlevant/picture
2. 在 Craft 控制面板下的设置 > 插件中安装插件

或

1. 通过插件商店安装

图片概览

为资产创建转换，并生成一个 <picture> 或 <img> 元素，或者简单地返回转换后的图片 URL。大部分工作在于编写描述不同图像样式的配置。

插件提供了四个变量：craft.picture.element 生成 <picture> 和 <img> 元素，其中包含单个图像的多个转换 URL。 craft.picture.url 生成单个 URL，当图像是 background-image 时很有用。此外，craft.picture.imageStyles 返回定义的图像样式的名称数组，而 craft.picture.urlTransforms 返回定义的 URL 转换的名称数组。

配置图片

您需要一个配置文件，craft/config/picture.php。该文件定义了您项目中的不同图像样式。

以下是一个示例配置文件

<?php

return [
  // array of image styles. The name of the style will be the key,
  // and the configuration of the style will be the value.
  // These styles are used to generate picture and img elements
  // with craft.picture.element
  'imageStyles' => [

    // this is the 'thumb' style. It will generate an img like:
    // <img
    //   srcset="transform75pxUrl 75w, transform150pxUrl 150w"
    //   sizes="75px"
    //   src="transform75pxUrl"
    // />
    'thumb' => [
      // since the 'thumb' style has no sources, it will generate
      // an img element, not a picture element
      'img' => [
        // optional aspect ratio, width / height. Will use the
        // native aspect ratio of the asset if not specified
        // This will be square
        'aspectRatio' => 1,
        // the 'sizes' attribute of the element
        'sizes' => '75px',
        // pixel widths for the generated images. The first
        // element in the array will be the width of the default
        // src
        'widths' => [75, 150]
      ]
    ],

    // the 'art' style will generate a picture element with two
    // nested source elements and a nested img element
    'art' => [

      // since there is a sources array, this will generate a
      // picture element. sources is an array of source
      // configurations
      'sources' => [
        // on narrow screens, we are going to have a 4x3
        // small image. This source element will look like:
        // <source
        //   media="(max-sidth: 600px)"
        //   srcset="t100pxUrl 100w, t200pxUrl 200w"
        //   sizes="100px"
        // />
        [
          // optional 'media' attribute for this source
          // (the 'media' attribute is required on all but
          // the last source)
          'media' => '(max-width: 600px)',
          // optional aspect ratio
          'aspectRatio' => 4/3,
          'sizes' => '100px',
          'widths' => [100, 200],
        ],
        // on other screens we are going to use the native aspect
        // ratio. The image will be 1/2 the screen width up to
        // 1000px, and 500px after that. The source element:
        // <source
        //   srcset="t500pxUrl 500w, t1000pxUrl 1000w"
        //   sizes="(max-width: 1000px) 50vw, 500px"
        // />
        [
          // sizes is just a string, but we can use php to make it
          // easier to construct
          'sizes' => implode(', ', [
            '(max-width: 1000px) 50vw',
            '500px'
          ]),
          'widths' => [500, 1000]
        ]
      ],

      // the img element is required. We just need a fallback src,
      // this will be 500px wide (no srcset when there is only one
      // width).
      // <img src="t500pxUrl" />
      'img' => [
        'widths' => [500]
      ],

      // transform is optional, and specifies parameters for
      // the Craft transforms for the style
      'transform' => [
        'format' => 'jpg'
      ]
    ],

    // the 'lazyLoaded' style for elements that use lazysizes for lazyloading.
    // See also lazysizesTrigger config value
    // <img
    //   class="lazyload"
    //   data-srcset="transform500pxUrl 500w, transform1000pxUrl 1000w"
    //   data-sizes="25vw"
    //   data-src="transform500pxUrl"
    // />
    'lazyLoaded' => [
      // optional lazysizes. Can be boolean (true = lazysizes, false = no lazysizes) or
      // string (uses string value for src attribute value)
      'lazysizes' => true,
      'img' => [
        'sizes' => '25vw',
        'widths' => [500, 1000]
      ]
    ],

    // the default style will be used when none is specified.
    'default' => [
      'img' => [
        'widths' => [500],
      ]
    ]
  ],

  // the urlTransforms are used to specify individual urls for
  // craft.picture.url
  'urlTransforms' => [
    // the 'hero' transform - these image will be 7:3, and 1000px wide
    'hero' => [
      'aspectRatio' => 7/3,
      'width' => 1000
    ]
  ],

  // lazysizesTrigger is an optional override for elements loaded with
  // lazysizes. It changes the class value from 'lazyload'
  'lazysizesTrigger' => 'js-lazyload'
];

总结，配置文件指定了生成 <picture> 和 <img> 元素的 imageStyles，用于生成单个图像 URL 的 urlTransforms，以及如果您想使用具有不同触发类名的 lazyload，则还指定了 lazysizesTrigger。

imageStyles 中的每个单独元素都有一个可选的 sources 数组和一个 img。img 可以有

• 大小：可选的大小属性
• 宽度：像素宽度的数组。必须至少有一个
• 长宽比：可选的长宽比，宽 / 高。小于 1 为肖像，大于 1 为风景。
• 转换：额外的 Craft 转换参数（宽度由插件设置，如果指定了长宽比，高度也是如此）

每个源都可以有所有这些，加上

• 媒体：可选的媒体属性

此外，整个样式还可以有

• 转换：可选的 Craft 转换参数
• lazysizes：可选值，用于确定元素是否使用 lazysizes 进行懒加载。将生成 data-srcset、data-sizes 和 data-src 属性，而不是 srcset、sizes 和 src。将添加一个具有值 class="lazyload" 的 class 属性，或将 lazyload 添加到任何现有的 class 属性中。值是
  • false - 不进行懒加载（默认值）
  • true - 懒加载，无回退 src 属性
  • 字符串 - 懒加载，值将是 src 属性值。

urlTransforms 中的每个单独元素都可以有

• 宽度：单个像素宽度。这是必需的。
• 长宽比：可选的长宽比
• 转换：额外的 Craft 转换参数

尽可能避免生成会放大原始图像的转换。

使用 craft.picture.element

在模板中使用 craft.picture.element 如此

{{ craft.picture.element(asset, style, options) }}

• asset 是一个 Asset 元素 - 一个常规 Craft 资产 OR asset 是 Craft 资产的数组，在这种情况下，第一个资产用于第一个源，第二个资产用于第二个源，等等，如果源比资产多，则重复资产循环。
• style 是图像样式的名称。它是可选的，如果缺失，将使用 默认 样式。
• options 是一个可选的选项哈希表。
  • transform - 附加的 Craft 转换参数
  • lazysizes - 覆盖配置文件中图像样式中任何 lazysizes 值。
  • 其他任何内容都将作为 <img> 元素的属性。

例如，创建一个具有 thumb 样式、thumbAlt 替换文本、bottom-right 裁剪位置和 80 质量的图像

{{ craft.picture.element(
     entry.image.one,
     'thumb',
     {
       alt: 'thumbAlt',
       transform: {
         position: 'bottom-right',
         quality: 80
       }
     }
) }}

例如，创建一个具有不同尺寸不同图像的 art 样式图像

{{ craft.picture.element([
     entry.mobileImage.one, entry.desktopImage.one
  ], 'art') }}

使用 craft.picture.url

用于作为背景图像的 hero 图像

<div
  class="hero"
  style="background-image: url({{ craft.picture.url(entry.hero.one, 'hero') }})"
></div>

与 ImageOptimize 集成

ImageOptimize 插件会自动运行 jpegoptim 等图像优化器对您的转换图像进行优化。它与该插件配合良好，无需进行任何额外更改。

与 lazysizes 集成

可以在 config/picture.php 中的样式配置或传递给 craft.picture.element 的选项中设置 lazysizes 值。通过在选项中指定 lazysizes，您可以

• 关闭“折叠之上”图像的懒加载
• 使用 ImageOptimize 占位符图像 作为 src 属性

此外，如果您想为懒加载的图像使用不同于 lazyload 的类，您可以使用 lazysizesTrigger 配置值更改该类。

提示

我在调用 craft.picture.element 之前使用一个 twig 宏来处理缺失的图像。

我定义了一个包含所有不同转换的 preparse 样式，并在资产保存到 Preparse 字段时生成该样式，以预构建转换。

由 Marion Newlevant 提供。图标由 Setyo Ari Wibowo 设计