README

一个Twig助手，用于从一组imgix转换中生成图片标签。

要求

此插件需要Craft CMS 4.9.0或更高版本，以及PHP 8.0.2或更高版本。

安装

您可以使用Composer安装此插件。

使用Composer

打开您的终端并运行以下命令

# go to the project directory
cd /path/to/my-project.test

# tell Composer to load the plugin
composer require mostlyserious/craft-imgix-picture

# tell Craft to install the plugin
./craft plugin/install imgix-picture

配置

此插件假定您已配置一个资产卷和文件系统（通常是Amazon S3存储桶）以及一个引用该文件系统的imgix源。注意：目前不支持多个imgix源。

要开始使用，请创建一个带有源和API密钥的imgix帐户。

API密钥需要Purge权限，并且仅在Craft的资产事件（如替换）上清除资产时使用。

将您的imgix URL和API密钥添加到.env文件中的环境变量。

IMGIX_URL="https://example.imgix.net"
IMGIX_API_KEY="aXzY....."

然后在config/imgix-picture中添加此配置文件

<?php

return [
    'imgixUrl' => getenv('IMGIX_URL'),
    'imgixApiKey' => getenv('IMGIX_API_KEY'),
    // altTextHandle => 'alternativeText' /* optional */
    // 'defaultParameters' => [] /* optional */
    // 'useNativeTransforms' => false
    // 'fallBackImageSrc' => '/static-assets/default-image-missing-photo.png'
];

• altTextHandle 替代文本：此插件假定Craft的本地alt文本字段已添加到所需的资产字段布局中。如果您正在使用不同的字段作为替代文本，您可以通过在配置文件中提供不同的字段处理程序来覆盖此设置。
• defaultParameters 默认参数：使用您自己的默认值覆盖针对自动格式和质量适中的默认imgix参数。
• useNativeTransforms Craft转换：设置为true以绕过imgix并使用Craft转换。
• fallBackImageSrc 回退图片：Imgix为其源有自己的默认图片，您可以设置。除此之外，如果您希望配置一个在未提供资产给图片函数时显示的图片，您可以在此设置。

用法

使用picture函数从资产生成一个<picture>标签。

{{ picture(
    assetField.one(),
    [
        {
            fit: 'crop',
            width: 120,
            height: 120
        },
        {
            breakpoint: 1024,
            fit: 'crop',
            width: 500,
            height: 500
        },
    ],
    {
        class: [
            'block',
            'w-full h-auto aspect-square',
            'object-cover',
            'lg:absolute lg:inset-0',
            'lg:h-full lg:aspect-auto',
        ],
    }
) }}

picture()函数

此函数使用3个参数调用

1. 第一个参数必须是Craft资产对象。
2. 第二个是一个变换数组。
   • 一个非标准breakpoint属性是一个最小宽度像素值，它将一个最小宽度媒体查询添加到图片内的<source>元素，例如：media="(min-width: 1024px)"。
   • 如果资产有一个焦点，则自动添加焦点参数。
   • 变换可以包含imgix 渲染API中的任何参数。插件作为基线设置了推荐默认属性，但将被您提供的任何属性覆盖。

   /* Defaults are */
   [
       'auto' => 'format,compress',
       'q' => 35,
       'fit' => 'max',
   ];

   • 如果只传递一个变换，将渲染一个<img>标签而不是一个picture标签。
3. 第三个参数是一个对象，表示您希望添加到渲染元素的HTML属性。图像默认是懒加载的，但您可以覆盖此设置，例如

{
    fetchpriority: 'high',
}

其他函数

• singleSrc()创建一个适合src=""属性的单一变换URL
• downloadUrl()创建一个带有dl参数的强制下载链接到imgix资产
• imgixAttrs返回不带图片标签的imgix属性
• 函数 getMaxDimensions 返回在定义的参数内资产的最大尺寸