README

最灵活的 Craft CMS Imgix URL 生成器。

使用方便的方法生成响应式图像的 Imgix URL。
新增: 通过将 Craft 的原生图像转换与 Imgix 渲染交换来加快模板和控制面板的速度并控制。
新增: Servd.host 用户 - 使用 Servd 的内置图像转换而不是 Imgix。

要求

此插件需要 Craft CMS 3.0.0-beta.23 或更高版本。

安装

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

打开您的终端并转到您的 Craft 项目
```
 cd /path/to/project
```
然后告诉 Composer 加载插件
```
 composer require croxton/imgixer
```
在控制面板中，转到设置 → 插件，然后点击 Imgixer 的“安装”按钮。

配置 Imgixer

将 config.php 复制到 Craft 的 config 文件夹，并将其重命名为 imgixer.php。

使用唯一的处理程序定义每个来源。同一个 Imgix 来源域名可能被引用多次，这在您想为特定资产卷中的图像使用不同的默认参数，或者在使用具有相似特征的一组任意图像时非常有用，或者如果您已将 Imgix 来源定义为网络代理并需要引用多个域名。

<?php
return [
    'sources' => array(
        
        // A unique handle that you can reference in your templates.
        'myHandle' => array(

             // The imgix source domain.
            'domain'   => 'my-domain.imgix.net',
            
            // The asset provider (defaults to 'imgix')
            'provider'   => '',

            // Optionally specify a subfolder path to prefix the path
            // of generated URLs after the source domain.
            'subfolder' => '', 
            
            // The private Imgix key used to sign images. 
            // Get this from the source details screen in Imgix.com
            'key'   => '12345',
            
            // Set to true if you want images to be signed with your key.
            'signed'    => true,
            
            // Define any default parameters here:
            'defaultParams' => array(
                'auto' => 'compress,format',
                'fit' => 'crop',
                'ar' => '3:2',
                'step' => '100'
            )
        ),
        'heroBanners' => array(
            'domain'   => 'another-domain.imgix.net',
            'key'   => '12345',
            'signed'    => true,
            'defaultParams' => array(
                'auto' => 'compress,format',
                'fit' => 'crop',
                'ar' => '16:9',
                'q' => '80'
            )
        ),
        'portraits' => array(
            'domain'   => 'another-domain.imgix.net',
            'key'   => '12345',
            'signed'    => true,
            'defaultParams' => array(
                'auto' => 'compress,format,enhance,redeye',
                'fit' => 'facearea',
                'ar' => '3:4'
            )
        ),
        
        // Optional: define a source to use in place of Craft's native image transforms. 
        // This will be used for all transforms used in your templates and in the control panel.
        'assetTransforms' => array(
            'domain'    => 'my-domain.imgix.net',
            'key'       => '12345',
            'signed'    => true
        ),
    ),

    // Optional: set this to the source you want to use in place of Craft's native image transforms. 
    'transformSource' => 'assetTransforms'
];

使用 Imgixer

{% set image = entry.myImage.one() %}

{# Use either as a filter... #}
{{ image | imgix({ ar:'16:9', w:1024 }) }}

{# ...or as a function. #}
{{ set myImageSrc = imgix(image, { ar:'16:9', w:1024 }) }}

{# Optionally, you can pass an image path instead of an asset (this will render the Imgix URL without a date modified parameter (&dm=), meaning the URL won't be automatically updated if you replace the image without renaming it #}
{{ set myImageSrc = imgix(image.path, { ar:'16:9', w:1024 }) }}

{# Create a srcset by defining a range of widths using the `from`, `to` and `step` parameters #}
{{ set myImageSrcset = imgix(image, { ar:'16:9', from:300, to:1600, step:100 }) }}

{# Specify a source handle (by default, Imgixer uses the first source you defined in the config) #}
{{ image | imgix({ ar:'16:9', w:1024, source:'heroBanners' }) }}

{# Example of a responsive <img> #}
<img
  srcset="{{ image | imgix({ ar:'16:9', from:640, to:1600, step:160 }) }}"
  src="{{ image | imgix({ ar:'16:9', w:1024 }) }}"
  alt="">

{# Example of a responsive <picture> where the image proportions change depending on screen width #}
<picture>

    <!-- 21:9 -->
    <source
      media="(min-width: 768px)"
      sizes="100vw"
      srcset="{{ image | imgix({ ar:'21:9', from:800, to:3200, step:160 }) }}">

    <!-- 16:9 -->
    <source
      media="(min-width: 640px)"
      sizes="100vw"
      srcset="{{ image | imgix({ ar:'16:9', from:640, to:1600, step:160 }) }}">

    <!-- 3:2 -->
    <source
      sizes="100vw"
      srcset="{{ image | imgix({ ar:'3:2', from:480, to:1280, step:160 }) }}">

    <!-- older browsers -->
    <img
      src="{{ image | imgix({ ar:'16:9', w:1024 }) }}"
      alt="">

</picture>

使用 Servd.host 资产来源与 Imgixer 结合使用

有几种方法可以将 Imgixer 与 Servd.host 资产来源结合使用，并从 Servd 的自动环境前缀（生成的 URL 前缀为 local、staging 或 production）中受益。

使用任一选项，您首先需要安装 Servd Assets and Helpers。

1. 使用 Imgix Web Folder 来源

在 Imgix 中设置一个 Web Folder 来源，并将基本 URL 设置为您的项目 Servd CDN URL，例如 https://cdn2.assets-servd.host/my-served-project-slug。
推荐：勾选使用安全 URL 的选项，并记下密钥。
在 imgixer.php 配置中创建一个来源，添加 servd 作为资产转换提供者

'my-servd-web-folder' => array(
   'domain' => 'my-domain.imgix.net',
   'provider' => 'servd',
   'key' => '12345',
   'signed' => true,
   'defaultParams' => array(
       'auto' => 'compress,format',
       'fit' => 'crop',
       'q' => '80'
   )
),

2. 使用 Servd 的图像转换服务

Servd 提供自己的图像转换服务，该服务支持 Imgix 渲染 API 的一部分，但足以覆盖大多数用例。这不需要 Imgix 帐户，但请注意，它将消耗分配给您的计划的 Servd 资源。

在 imgixer.php 配置中创建一个来源，添加 servd 作为资产提供者。不要设置域名

'my-servd-assets' => array(
   'provider' => 'servd',
   'defaultParams' => array(
       'auto' => 'format',
       'fit' => 'crop',
       'q' => '80'
   )
),

Servd 的图像转换服务支持以下参数

fm - 输出格式

可以是以下之一：webp、png、jpeg、tiff。

w - 宽度

按提供的宽度缩放图像，同时保持宽高比。

h - 高度

按提供的宽度缩放图像，同时保持宽高比。

q - 质量

(75) - 1-100

ar - 宽高比

(1.0:1.0) - 当 fit=crop 时，可以提供宽高比，如 16:9，可选地带有高度或宽度。如果没有定义高度或宽度，则将使用原始图像大小。

dpr - 设备像素比

(1) - 将请求的图像尺寸乘以此乘数。

fit - 调整大小适合模式

可以是以下之一：fill、scale、crop、clip、min、max。

fill-color

当fit设置为fill时使用，可以是如"red"或"rgb(255,0,0)"这样的非严格格式的颜色。

裁剪 - 调整大小匹配模式

可以是以下之一：focalpoint，entropy，或top，bottom，left，right的任意逗号分隔的组合。

crop=focalpoint

使用fp-x和fp-y参数尽可能接近提供的点进行裁剪。

crop=entropy

围绕Shannon熵最高的区域裁剪图像。

crop=top,left（或bottom，right）

围绕指定的区域裁剪图像。提供最多两个区域标识符，用逗号分隔。

fp-x, fp-y - 焦点x & y

百分比，0到1，表示在focalpoint模式下裁剪时图像关注的区域。

auto

可以是：compress，format的逗号分隔组合。

auto=format

如果auto包括format，服务将尝试确定将图像转换为的最佳格式。规则是

如果浏览器支持，除了gif以外的所有内容都返回为webp。
如果请求png且该png没有alpha通道，则将其返回为jpeg。

auto=compress

compress参数将在返回图像之前尝试对该图像进行后处理优化。

Png图像将通过pngquant处理。

元素API

将图像作为函数的第一个参数传递，并将Imgix参数数组作为第二个参数传递。

<?php

use craft\elements\Entry;
use craft\helpers\UrlHelper;
use croxton\imgixer\twigextensions\ImgixerTwigExtension;

return [
    'endpoints' => [
        'news.json' => function() {
            return [
                'elementType' => Entry::class,
                'criteria' => ['section' => 'news'],
                'transformer' => function(Entry $entry) {
                    $asset = $entry->image->one();
                    return [
                        'title' => $entry->title,
                        'url' => $entry->url,
                        'jsonUrl' => UrlHelper::url("news/{$entry->id}.json"),
                        'summary' => $entry->summary,
                        'image'   => (new ImgixerTwigExtension)->imgix($asset, array(
                            'ar' => '16:9',
                            'w' => 2000,
                            'signed' => true
                        ))
                    ];
                },
            ];
        }
    ]
];

Web代理

当使用Imgix作为代理时，您需要提供要代理的图像的绝对URL。您可以在模板级别这样做（如果您需要代理多个域），或者创建配置中的每个代理域的source，并将代理域名传递给subfolder。

例如，您可以配置如下...

return [
   'my-proxy' => array(
      'domain'   => 'my-proxy-source.imgix.net',
      'subfolder' => 'https://www.my-proxied-website.com/',
      'key'   => 'XXXXXXXXXXXX',
      'defaultParams' => array(
         'auto' => 'compress,format',
         'fit' => 'crop',
         'q' => '80'
      )
   ),
];

...并在模板中使用如下...

{{'uploads/my-image.jpg' | imgix({ source:'my-proxy', ar:'3:2', w:1200, signed: true }) }}

或者，使用如下配置...

return [
   'my-proxy' => array(
            'domain'   => 'my-proxy-source.imgix.net',
            'key'   => 'XXXXXXXXXXXX',
            'defaultParams' => array(
                'auto' => 'compress,format',
                'fit' => 'crop',
                'q' => '80'
            )
        ),
   )
];