README

生成与 Imgix、Imagekit 和 Servd 兼容的图片变换 URL。

使用方便的方法生成响应式图片的 URL。
使用相同的变换参数与所有图片提供者。
通过将 Craft 的原生图片变换与 Imgix 或 Imagekit 渲染交换来加速模板和控制面板。
在 Servd.host 上托管？使用 Servd 内置的图片变换服务。

需求

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

安装

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

打开您的终端并转到您的 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(
        
            // Provider: either 'imgix', 'imagekit' or 'servd' (defaults to 'imgix')
            'provider' => 'imgix',

            // The image service endpoint or source domain
            'endpoint'   => 'my-domain.imgix.net',

            // Optionally specify a subfolder path to prefix the path
            // of generated URLs after the source domain.
            'subfolder' => '', 
            
            // The private key used to sign images. 
            // Imgix: get this from the source details screen at https://imgix.com
            // Imagekit: https://imagekit.io/dashboard/developer/api-keys
            // Servd: not required
            'privateKey'   => '12345',
            
            // A public key used to access the image transform API 
            // Imgix: not required 
            // Imagekit: https://imagekit.io/dashboard/developer/api-keys
            // Servd: not required
            'publicKey'   => '12345',
            
            // Set to true if you want images to be signed with your private key.
            'signed'    => true,
            
            // Define any default parameters here:
            'defaultParams' => array(
                'auto' => 'compress,format',
                'fit' => 'crop',
                'ar' => '3:2',
                'step' => '100'
            )
        ),
        'heroBanners' => array(
            'provider' => 'imagekit',
            'endpoint'   => 'https://ik.imagekit.io/render/my-identifier',
            'privateKey'   => '12345',
            'publicKey'   => '67890',
            'signed'    => true,
            'defaultParams' => array(
                'auto' => 'compress,format',
                'fit' => 'crop',
                'ar' => '16:9',
                'q' => '80'
            )
        ),
        'portraits' => array(
            'provider' => 'imgix',
            'endpoint'   => 'another-domain.imgix.net',
            'privateKey'   => '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(
            'provider' => 'imgix',
            'endpoint' => 'my-domain.imgix.net',
            'privateKey' => '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 来源

Servd Assets Platform v2

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

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

Servd Assets Platform v3

在 Imgix 中设置一个 Web Folder 来源，并将基本 URL 设置为您的项目 Servd file 域名，例如 https://my-served-project-slug.files.svdcdn.com（如果您已设置自定义文件域名，请使用该域名）。
建议：勾选使用安全 URL 的选项，并记下密钥。
在 imgixer.php 配置中创建一个新的来源

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

2. 使用 Servd 的自身图片变换服务

Servd 的资产平台提供了一种图片变换服务，它支持 Imgix 渲染 API 的一小部分，并覆盖了大多数用例。如果您在 Servd 上托管，这可能是您所需要的全部。

Servd Assets Platform v2

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

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

Servd Assets Platform v3

在 imgixer.php 配置中创建一个来源，添加 servd 作为资产提供者。将 Servd 的 transform 域名作为来源的端点（如果您已设置自定义变换域名，请使用该域名）。

'my-servd-assets' => array(
   'provider' => 'servd',
   'endpoint' => 'https://my-served-project-slug.transforms.svdcdn.com',
   'defaultParams' => array(
       'auto' => 'format',
       'fit' => 'crop',
       'q' => '80'
   )
),

核心参数集

由 Imgix、Imagekit 和 Servd 支持.

fm - 输出格式

可以是以下之一：webp、png、jpeg | jpg、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)" 的松散格式颜色。

crop - 调整大小模式

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

crop=focalpoint

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

crop=entropy

围绕具有最高香农熵的区域裁剪图像。

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 没有透明通道，则将其返回为 jpeg。

auto=compress

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

扩展参数集

仅由 Imgix 和 Imagekit 支持。由于参数的行为在不同服务之间并不总是直接相关，因此图像输出可能存在一些差异。

blur

对图像应用高斯风格的模糊，平滑图像噪声。

有效值范围从 0 到 2000。默认值为 0，不改变图像。

border

向图像添加边框。它接受两个参数 - 边框的宽度和边框的颜色： border=<border-width>,<hex code>

con - 对比度

(0) 调整图像的对比度。有效值范围是 -100 – 100。默认值是 0，不改变图像。

注意

Imagekit：任何超过 0 的值都应用自动对比度调整。

fit=facearea

查找包含所有面部或图像中特定面部的区域，并将其缩放到指定的宽度和高度尺寸。非常适合缩略图肖像。

注意

当使用 Imgix 时，添加 facepad=1.6 以近似 Imagekit 提供的默认面部填充（面部填充在 Imagekit 中不可配置）。
Imgix 不会在 fit=facearea 时应用宽高比（ar）参数，因此在使用此参数时，应始终提供宽度和高度参数。

fit=fillmax

调整图像大小以适应请求的宽度和高度尺寸，同时保留原始宽高比且不丢弃任何原始图像数据。如果请求的宽度和高度超过原始尺寸，则原始图像保持相同大小。使用 fill-color 参数指定要使用的背景颜色。

注意

Imgix 不会在 fit=fillmax 时应用宽高比（ar）参数，因此在使用此参数时，应始终提供宽度和高度参数。

fp-z - 焦点缩放

必须是一个介于1和100（含）之间的浮点数。默认值为1，表示图像的原始大小，每个完整的步长相当于100%的缩放（例如，fp-z=2等同于查看图像为200%）。建议的范围是1 – 10。要设置图像焦点，必须同时设置fit=crop和crop=focalpoint。

无损

lossless参数启用支持无损压缩格式的无损图像传输（JPEG XR和WEBP）。有效值是true和false。

radius

用于指定图像角落的像素半径。圆角图像的背景将是透明的。

注意

Imagekit：如果你指定了边框，它将不会圆角。

rot

根据指定的值旋转图像。有效值范围是0 – 359，旋转是逆时针的，其中0（默认）位于图像顶部。

sat=-100

输出一个完全去饱和的灰度图像。

sharp - 锐化

使用亮度（仅影响黑白值）来锐化图像，提供清晰细节，最小化颜色伪影。

推荐值范围是0 – 100。默认值是0，表示图像保持不变。

trim

裁剪图像以去除图像周围的均匀边框。

trim=auto

根据边框颜色自动裁剪图像。

trim=color

Imgix仅支持：将根据trim-color参数指定的十六进制颜色裁剪图像。

trim-tol

trim容差定义了在裁剪操作停止之前颜色可以有多少不同。Imgix要求设置trim=color，此参数才生效。

服务特定参数集

如果你希望能够轻松地在服务提供商之间切换，请尽量坚持使用上述核心或扩展参数集。然而，每个支持的图像转换服务的完整参数集都可以在此找到

Imgix: https://docs.imgix.com/apis/rendering
Imagekit: https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations
Servd: 仅支持上述描述的核心参数集

Element 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或Imagekit作为代理时，你需要提供要代理的图像的绝对URL。你可以在模板级别（如果你需要代理多个域名）或创建配置中的每个代理域的source，并将代理域名传递给subfolder。

例如，你可以有这样的配置...

return [
   'my-proxy' => array(
      'provider' => 'imgix',
      'endpoint' => 'my-proxy-source.imgix.net',
      'subfolder' => 'https://www.my-proxied-website.com/',
      'privateKey' => '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(
            'provider' => 'imgix',
            'endpoint' => 'my-proxy-source.imgix.net',
            'privateKey' => 'XXXXXXXXXXXX',
            'defaultParams' => array(
                'auto' => 'compress,format',
                'fit' => 'crop',
                'q' => '80'
            )
        ),
   )
];

...并在模板中使用它

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

资产清理

当在Craft的图像编辑器中编辑控制面板中的图像时，Imgixer不会自动向图像提供商发出API请求以从其CDN中清除相应的URL。请参考Imgix文档

为确保更新资产完全符合要求，最好通过重命名文件为资产赋予新的路径。只有在绝对必要时才建议清理资产。

请要求编辑器在控制面板中编辑图像时始终'另存为新资产'。如果图像编辑器从条目中调用，条目资产字段将自动更新以链接到新资产。

croxton / imgixer

维护者

详细信息

README

需求

安装

配置 Imgixer

使用 Imgixer

使用 Servd.host 资产来源与 Imgixer 一起使用

1. 使用 Imgix Web Folder 来源

Servd Assets Platform v2

Servd Assets Platform v3

2. 使用 Servd 的自身图片变换服务

Servd Assets Platform v2

Servd Assets Platform v3

核心参数集

fm - 输出格式

w - 宽度

h - 高度

q - 质量

ar - 宽高比

dpr - 设备像素比

fit - 调整大小模式

fill-color

crop - 调整大小模式

crop=focalpoint

crop=entropy

crop=top,left (或 bottom, right)

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

auto

auto=format

auto=compress

扩展参数集

blur

border

con - 对比度

fit=facearea

fit=fillmax

fp-z - 焦点缩放

无损

radius

rot

sat=-100

sharp - 锐化

trim

trim=auto

trim=color

trim-tol

服务特定参数集

Element API

Web代理

资产清理