README

在 Craft CMS 中从给定资产渲染 BlurHash。

BlurHash 是图像占位符的紧凑表示。图像的模糊版本，在加载完整分辨率的图像时显示。

此插件使用 kornrunner 的 PHP 实现 BlurHash，php-blurhash。

要求

Craft CMS 3.X, 4.X 或 5.X
PHP 7.4+
GD / ImageMagick（如 Craft CMS 所需）

安装

按照以下步骤安装插件

打开您的终端并转到您的 Craft 项目
```
cd /path/to/project
```

然后告诉 Composer 加载插件

composer require dodecastudio/craft-blurhash

在控制面板中，转到设置 → 插件，并点击 BlurHash 的“安装”按钮。

BlurHash 概述

BlurHash 插件将从 craft 资产生成 BlurHash 图像。以下是您可以期望的示例

输入

结果

使用 BlurHash

常用

要使用此插件，首先从 Craft 中获取一个资产，可能如下所示

{% set testAsset = craft.assets().id(101).one() %}

然后，您可以传递您的资产到插件的 blurhash 函数，该函数将返回一个作为数据-url 的 blurhash 图像，非常适合用于 img 元素，如下所示

<img src="{{ blurhash(testAsset) }}" width="{{testAsset.width}}" height="{{testAsset.height}}" style="aspect-ratio: {{testAsset.width}} / {{testAsset.height}};" />

注意：由于 blurhash 图像的紧凑尺寸，其宽高比可能与源材料略有不同。如果您尝试防止 CLS，请确保任何图像标记正确渲染基于源标记的宽高比。一种实现方法是在上面示例中使用 CSS aspect-ratio 属性。

其他功能

生成 blurhash 字符串

如果您只想从给定资产生成 blurhash 字符串，可以使用 blurhash 过滤器，如下所示

{{ testAsset|blurhash }}

这将返回类似以下内容

f+IrKQogj]j[ayj[_4ofj[j[ayj[%NazayfQj[j[t6ayWBayofj[Rjj[j@fQj[ay

您可能想以某种方式存储此内容，以供以后使用。

从 blurhash 字符串生成 blurhash 图像

如果您已经有一个 blurhash 字符串并想从中生成图像，可以使用 blurhashToUri 函数，如下所示

<img src="{{ blurhashToUri('f+IrKQogj]j[ayj[_4ofj[j[ayj[%NazayfQj[j[t6ayWBayofj[Rjj[j@fQj[ay') }}" width="256" height="256" alt="Blurhash image" />

请注意，blurhash 字符串不包含有关图像大小或缩放的数据。您可能需要其他信息才能显示正确的宽高比。

返回图像的平均颜色

BlurHash 字符串包含图像的平均颜色。您可以从 BlurHash 字符串解码此值并返回它作为 Craft ColorData 对象。

{{ averageColor('f+IrKQogj]j[ayj[_4ofj[j[ayj[%NazayfQj[j[t6ayWBayofj[Rjj[j@fQj[ay') }}
{{ averageColor('f+IrKQogj]j[ayj[_4ofj[j[ayj[%NazayfQj[j[t6ayWBayofj[Rjj[j@fQj[ay').getRgb() }}

...或直接从资产中返回

{{ testAsset|averageColor }}
{{ averageColor(testAsset) }}
{{ averageColor(testAsset).getRgb() }}

返回内存信息

为了读取并生成 blurhash，图像需要加载到内存中。此辅助函数将告诉您给定图像大约需要多少内存（以字节为单位）。

{{ testAsset|memoryInfo }}

GraphQL 支持

从 v1.1.0 版本开始，可以通过 Graph QL 使用插件。与 Twig 函数提供的功能相同，现在可以通过 Graph QL 指令使用。

从资产字段返回 blurhash 数据 URI

资产字段可以通过使用 @assetToBlurHash 指令返回为模糊哈希图像的数据 URI。也可以通过将 asUri 参数设置为 false 来返回模糊哈希字符串。

{
  entries(section: "news") {
    title
    ... on news_article_Entry {
      asset {
        blurhashString: url @assetToBlurHash(asUri: false)
        blurhashUri: url @assetToBlurHash
      }
    }
  }
}

这将返回一些类似于这样的 JSON

{
  "data": {
    "entries": [
      {
        "title": "An important news item",
        "asset": [
          {
            "blurhashString": "f+IrKQogj]j[ayj[_4ofj[j[ayj[%NazayfQj[j[t6ayWBayofj[Rjj[j@fQj[ay",
            "blurhashUri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAAB..."
          }
        ]
      }
    ]
  }
}

从纯文本模糊哈希字符串渲染模糊哈希图像

如果您在 Craft 中保存了一个模糊哈希字符串，您可以使用 @blurhashToUri 指令将其渲染为数据 URI。在这个例子中，我们新闻文章条目中有一个名为 blurhashStringField 的纯文本字段。

{
  entries(section: "news") {
    title
    blurhashStringField
    blurhashUri: blurhashStringField @blurhashToUri
  }
}

然后这将给我们一些类似于这样的 JSON

{
  "data": {
    "entries": [
      {
        "title": "An important news item",
        "blurhashStringField": "f+IrKQogj]j[ayj[_4ofj[j[ayj[%NazayfQj[j[t6ayWBayofj[Rjj[j@fQj[ay",
        "blurhashUri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAAB..."
      }
    ]
  }
}

获取图像的平均颜色

如果您想返回 Craft 中保存的图像的平均颜色，您可以使用 @averageColor 指令。这将以字符串形式返回十六进制颜色值。

{
  entries(section: "news") {
    title
    ... on news_article_Entry {
      blurhashStringField @averageColor
      asset {
        averageColor: url @averageColor
      }
    }
  }
}

这将返回一些类似于这样的 JSON

{
  "data": {
    "entries": [
      {
        "title": "An important news item",
        "blurhashStringField": "#a3a696",
        "asset": [
          {
            "averageColor": "#817c82"
          }
        ]
      }
    ]
  }
}

设置

默认设置可以被覆盖。请参阅 blurhash-config.php 文件以获取详细信息。

许可证 🌳

此软件包为 Treeware。如果您在生产环境中使用它，我们要求您 为世界买一棵树。
为什么不呢？通过为 Treeware 森林做出贡献，您将为当地家庭创造就业机会并恢复野生动物栖息地。

谢谢！🙌

向 @olsp 为购买 100 棵树表示敬意，以及向 @mokopan 为购买 25 棵树表示敬意。

如果您通过 Ecologi 购买了树木，作为 Treeware 许可证的一部分，请让我们知道以便为您鸣谢。

dodecastudio / craft-blurhash

维护者

详细信息