README

由Thumbor提供动力的Craft CMS图像转换

配置

将配置选项添加到您的配置文件夹中的 thumbro.php 文件中。

在设置Thumbor时，我们建议使用 thumbor.loaders.file_loader_http_fallback 加载器来处理带有和没有公共URL的文件（请参阅 图像加载器）。

域名 [字符串]

Thumbor可以访问的域名（包括端口）。

securityKey [字符串]

在您的Thumbor配置文件中定义的安全密钥。请参阅 安全性。

autoFocalPoint [布尔值]

默认: true

将自动设置图像的焦点为Craft中定义的焦点。 (请参阅 位置)

autoCompress [布尔值]

默认: true

将自动压缩生成的图像。

imageUrlModifier [可调用|null]

默认: null

在将图像URL传递给Thumbor之前，您有机会修改图像的公共URL。这在使用Docker时特别有用。

return [
    'imageUrlModifier' => function ($url, $isRemoteAsset) {
        // Replace the site's URL with the internal docker container name (web)
        return str_replace(getenv('DEFAULT_SITE_URL'), 'web', $url);
    },
];

$isRemoteAsset 如果将URL字符串传递给以下任一转换方法，则将为true。

thumborUrlModifier [可调用|null]

默认: null

在插件尝试通过 picture 方法访问文件内容时，您有机会修改Thumbor返回的URL。它的工作方式与 imageUrlModifier 相同。

用法

img(Asset|string $asset, array $transforms, array $config = [])

将单个图像转换为一个或多个尺寸。配置数组将被合并到每个转换中。您可以通过传递资产或字符串URL作为第一个参数。

{% set img = craft.assets.one() %}
{% set transformedImage = craft.thumbro.img(img, {
    width: 100,
    height: 100,
}, {
    position: img.getFocalPoint(),
}) %}

{% set img = craft.assets.one() %}
{% set transformedImage = craft.thumbro.img(img, [
    { width: 100, height: 100, format: 'webp' },
    { width: 100, height: 100, format: 'jpg' },
]) %}

picture(Asset|string $asset, array $transform, array $config = [])

将以 picture 标签的形式输出图像，用于动态延迟加载，并带有低质量占位符。函数签名与 img 方法相同，唯一不同的是 $transform 只接受单个转换对象，而不是多个对象的数组。

您可以通过传递资产或字符串URL作为第一个参数。

此函数将注入必要的JavaScript以动态加载图像。您可以通过将 noJs 选项传递给 $config 并将其设置为 true 来禁用此功能。

{{ craft.thumbro.picture(img, { width: 1000, height: 1000 }, { aboveFold: true }) }}

配置选项

除了常规的转换配置选项之外，picture 还有额外的独特选项

noJs [布尔值]

将禁用自动注入延迟加载JavaScript。

aboveFold [布尔值]

当为true时，将延迟加载转换为即时加载，这意味着在大多数情况下图像将立即加载。

title [字符串]

将输出到图像标签中的标题。

JS

您可以通过调用以下内容重新初始化thumbro动态图片函数

window.thumbro();

CSS

您需要包含一些CSS以确保图片标签正确显示。以下是我们的建议

picture {
    position: relative;
    z-index: 1;
    display: block;
    width: 100%;

    font-size: 0;
}

picture > img {
    position: absolute;
    top: 0;
    left: 0;

    width: 100%;
    height: auto;
    vertical-align: middle;
}

picture > img:first-child:last-child {
    position: relative;
}

picture > img:first-child {
    z-index: -1;
    height: 100%;
    object-fit: cover;
}

picture > img:last-child {
    z-index: 0;
    transition: opacity 0.15s ease;
}

转换选项

format [字符串]

默认: null
允许的值： null，'jpg'，'png'，'gif'，'webp'

创建图像的格式。如果未设置（默认值），它将与源图像相同的格式。

trim [布尔值|字符串]

默认: false

可以使用trim选项移除图像周围的空白。

除非指定，裁剪默认使用左上角像素颜色且不设置容差（关于容差的更多信息见下文）。

如果您需要指定获取像素颜色的方向，只需将值设置为 top-left 以获取左上角像素颜色，或设置为 bottom-right 以获取右下角像素颜色。

裁剪还支持颜色容差。参考像素颜色与周围像素颜色之间的欧几里得距离被使用。如果距离在容差范围内，它们将被裁剪。对于RGB图像，容差范围是0-442。

模式 [字符串]

默认值: crop
允许的值: crop、fit、stretch

crop: 裁剪图像到指定的大小，按比例缩放图像以尽可能填充该大小。
fit: 缩放图像以适应给定的大小，同时保持原始图像的宽高比。
stretch: 缩放图像到给定的大小，如果宽高比与原始图像不同，则拉伸图像。

宽度 [整数|字符串]

图像宽度，以像素为单位。

如果您省略此值或将它设置为0，Thumbor将确定该维度与原始图像成比例。

设置为 orig 以使用原始图像的大小。例如，如果原始图像的宽度为400px，则新图像也将具有相同的宽度。

负值将翻转图像。设置 '-0'（引号内）将翻转图像而不进行缩放。

高度 [整数|字符串]

图像高度，以像素为单位。

如果您省略此值或将它设置为0，Thumbor将确定该维度与原始图像成比例。

设置为 orig 以使用原始图像的大小。例如，如果原始图像的高度为400px，则新图像也将具有相同的高度。

负值将翻转图像。设置 '-0'（引号内）将翻转图像而不进行缩放。

比例 [整数|浮点数]

一个宽高比（宽度/高度），当没有提供宽度或高度时用于计算缺失的大小。

{ ratio: 16/9 }

效果 [数组]

一个键值数组，用于在图像上执行效果，键是效果的名称，值是效果的参数。参见下文的效果。

位置 [字符串|数组]

裁剪的基准位置。可以是包含%位置的字符串 20% 65%，或命名位置 middle-right，或x/y十进制位置的数组 ['x' => 0.2, 'y' => 0.65]。

智能 [布尔值]

裁剪图像时将使用Thumbor的智能焦点检测。

放大 [布尔值]

默认: false

如果为true，则将图像放大以适应给定的大小。

效果

autojpg [布尔值]

当设置为 true 时，将非透明PNG图像转换为JPG。

backgroundColor [字符串]

将背景层设置为指定的颜色。这特别适用于将透明图像（PNG）转换为JPEG。

值应该是颜色名称（如HTML中）或没有“#”字符的十六进制rgb表达式（例如，参见Web颜色）。如果颜色是 auto，则会智能选择颜色（基于图像像素）作为填充颜色。

blur [整数|数组]

对图像应用高斯模糊。

接受一个整数作为模糊的 radius，或一个匹配 [radius, sigma] 的数组。

• radius 用于高斯函数生成矩阵，最大值为150。半径越大，图像越模糊。
• sigma 是可选的，默认值与 radius 相同。Sigma用于高斯函数。

brightness [整数]

增加或减少图像亮度。

接受一个从-100到100的整数。更改图像亮度的百分比。正数使图像变亮，负数使图像变暗。

contrast [整数]

增加或减少图像对比度。

接受一个从-100到100的整数。更改图像对比度的百分比。正数增加对比度，负数减少对比度。

卷积 [数组]

对图像执行卷积矩阵（或核）操作。有关过程细节，请参阅核（图像处理）。边缘像素始终扩展到图像区域之外。

接受一个参数数组 [matrix_items, number_of_columns, should_normalize]。

• matrix_items 分号分隔的矩阵项
• number_of_columns 矩阵中的列数
• should_normalize 是否将每个矩阵项除以所有项的总和

示例

-1 -1 -1
-1  8 -1
-1 -1 -1

{{ craft.thumbro.img(img, {
    effects: {
        convolution: ['-1;-1;-1;-1;8;-1;-1;-1;-1', 3, false],
    },
}) }}

equalize [布尔值]

均衡图像中的颜色分布。

fill [字符串|数组]

将所选颜色填充到所需大小的图像的缺失部分，返回一个与其比例完全匹配的图像。只有当 mode 设置为 fit 时才有效。

接受一个字符串 color 或一个数组 [color, fill_transparent]。

• color 接受
  • 颜色名称（如HTML中）或没有“#”字符的十六进制RGB表达式（例如，请参阅Web颜色）。
  • 如果颜色是“透明”并且图像格式支持透明度，则填充颜色为透明。
  • 如果颜色是“auto”，则智能选择颜色作为填充颜色（基于图像像素）。
  • 如果颜色是“blur”，则用模糊的原始图像填充缺失部分。
• fill_transparent 指定是否填充图像的透明区域。接受的值是 true、false、1 或 0。此参数是可选的，默认值是 false。

grayscale [布尔值]

将图像转换为灰度。

maxBytes [整数]

自动降低图像质量，直到图像大小低于指定的字节数。

noise [整数]

向图像添加噪声。接受一个介于 0 - 100 之间的值作为添加到图像中的噪声量（百分比）。

proportion [浮点数]

将比例应用于传递给裁剪的高度和宽度。接受一个介于 0 - 1 之间的浮点数作为比例的百分比（例如，0.5 将在裁剪后使图像缩小到 50%）。

quality [整数]

设置JPEG图像的整体质量（对于PNG或GIF不起作用）。期望的值是介于 0 - 100 之间的质量级别（百分比）。

rgb [数组]

将颜色量更改到三个通道中的每一个。

接受一个RGB值的数组 [r, g, b]，范围从 -100 到 100。

rotate [整数]

根据传递的角度值旋转给定的图像。应设置为 0 - 359 之间的角度。大于或等于 360 的数字将被转换为 0 和 359 之间的等效角度。

sharpen [数组]

增强图像的明显清晰度。它基于Marco Rossini的优秀小波锐化GIMP插件。

接受一个包含以下值的数组：[sharpen_amount, sharpen_radius, luminance_only]

• sharpen_amount - 锐化量。典型值在 0.0 到 10.0 之间。
• sharpen_radius - 锐化半径。典型值在 0.0 到 2.0 之间。
• luminance_only - 仅锐化亮度通道。值可以是 true 或 false