README

Kirby ThumbHash

ThumbHash 是一种替代图片占位符算法。占位符由小至 28 字节哈希表示。它类似于 BlurHash，但具有以下优点

• 在相同空间中编码更多细节
• 还编码了宽高比
• 提供更准确的色彩
• 支持具有 alpha 通道的图像

此插件为 Kirby 添加了 ThumbHash 支持，允许您实现渐进式图像加载或内容感知的占位图像等 UX 改进 如 Mastodon。

如果您想在自己的应用程序中使用 BlurHash，可以自由使用我的 kirby-blurhash 插件。

底层，繁重的工作由 SRWieZ 的 PHP 实现 SRWieZ/thumbhash 完成

要求

• Kirb 3.9.2+ 用于资产方法
• PHP 8.0+
• gd 扩展

安装

下载

下载并复制此存储库到 /site/plugins/kirby-thumbhash。

Composer

composer require tobimori/kirby-thumbhash

用法

客户端解码

$file->thumbhash()

使用 ThumbHash 编码图像，并返回作为字符串的 ThumbHash

ThumbHash 的默认实现假定字符串在客户端进行解码。

这提供了最大的好处，尤其是更好的色彩表示和更小的数据负载大小，但需要在客户端执行此类库，因此最好与无头站点或大量使用客户端无限滚动/加载的站点一起使用。

使用像 unlazy 这样的懒加载库，您可以通过提供 thumbhash 作为属性轻松实现具有客户端解码的懒加载。

<img
  data-thumbhash="<?= $image->thumbhash() ?>"
  data-src="<?= $image->url() ?>" // Original src attribute will be placed by unlazy
  loading="lazy"
  alt="<?= $image->alt() ?>"
/>

服务器端解码

$file->thumbhashUri()

使用 ThumbHash 编码图像，然后解码并光栅化它。最后以数据 URI 的形式返回它，可以在没有客户端库的情况下使用。

除了简单地输出用于客户端使用的 ThumbHash 字符串之外，此插件还提供服务器端解码选项，允许您输出 base64 编码的图像字符串，可以用作占位图像，无需任何客户端库，类似于 Kirby Blurry Placeholder。

这在您网站上的图片很少或不想使用客户端库输出占位符时特别有用。使用这种方法，您仍然可以获得比通常减小图像大小更好的 ThumbHash 算法色彩表示，但图像预览仍然约为 ~1kB 大小。

<img src="<?= $image->thumbhashUri() ?>" />

裁剪图像

Kirby 不支持裁剪图像上的文件方法，因此您必须使用原始图像，并将比率作为属性传递给元素以获取正确的 ThumbHash。

<?php $cropped = $original->crop(500, 400) ?>
<img
  src="<?= $original->thumbhashUri(['ratio' => 5/4]) ?>"
  data-src="<?= $cropped->url() ?>"
  data-lazyload
  alt="<?= $original->alt() ?>"
/>

这也可以通过 $file->thumbhash($ratio) 支持。

处理静态资源（使用 asset() 助手）

自Kirby 3.9.2起，所有方法都作为资产方法可用。

asset('assets/image.jpg')->thumbhash();
asset('assets/image.jpg')->thumbhashUri();

有关asset()辅助函数的更多信息，请在此处阅读.

别名

$file->th(); // thumbhash()
$file->thUri(); // thumbhashUri()

选项

每个方法还允许您将比例和模糊半径作为选项数组指定。

$file->thumbhash([ 'ratio' => 16/9 ]); // will return thumbhash string, cropped to 16:9
$file->thumbhashUri([ 'blur' => 2 ]); // will return placeholder, encoded in an svg with blur filter
$file->thumbhashUri([ 'ratio' => 3/2, 'blur' => 0 ]); // will return placeholder as base64-encoded png without filter, cropped to 3:2

清除缓存

当图像被替换或更新时，编码缓存会自动清除，但是您也可以使用clearCache静态方法手动清除缓存

<?php

use tobimori\ThumbHash;

ThumbHash::clearCache($file);

当您使用第三方插件编辑图像时，这可能会很有用，这些插件不会触发Kirby的内部文件更新钩子，而是使用它们自己的。

选项

选项允许您微调插件的行为。您可以在您的config.php文件中设置它们

return [
    'tobimori.thumbhash' => [
        'sampleMaxSize' => 100,
        'blurRadius' => 1,
    ],
];

鸣谢

• Johann Schopplich的Kirby Blurry Placeholder插件为这个插件设定了基础（许可协议下：MIT许可协议 - 版权© 2020-2022 Johann Schopplich）

许可协议

MIT许可协议 版权© 2023 Tobias Möritz