README

这是一个Statamic插件，它提供了一个用于构建纯HTML响应式图像的自定义标签。它使用Glide调整图像大小、裁剪图像，并在<picture>元素中为不同的DPR和屏幕尺寸创建源。

要了解更多关于响应式图像及其使用方法，请阅读Eric Portis的这篇文章：this article。虽然它是在2014年发布的，但关键要点现在至少与当时一样相关。

如何安装

从您项目的根目录运行以下命令

composer require visuellverstehen/statamic-picturesque

如何使用

该标签作为{{ picture }}或{{ picturesque }}提供，并支持不同的使用方式

基于大小的非断点图像

使用单个源创建图像元素，为所有定义的DPRs提供调整大小/裁剪的图像。

例如：{{ picture:img size="300x200" }}或{{ picture:img size="300|1.5:1" }}

通过size属性接收宽度（可选）和比率，值由管道分隔。结果为

<picture>
    <source type="image/webp" srcset="
        [img-url]?fm=webp&amp;fit=crop&amp;w=300&amp;h=200&amp;s=[…] 1x,
        [img-url]?fm=webp&amp;fit=crop&amp;w=600&amp;h=400&amp;s=[…] 2x
    ">
    <img src="[img-url]?w=300&amp;fit=crop&amp;s=[…]" loading="lazy">
</picture>

不带大小的基于断点的图像

使用为每个提供的断点提供的源创建图像元素，每个源都有一个调整大小/裁剪的图像，适用于所有定义的DPRs。

例如：{{ picture:img default="300|1.5:1" md="1024|1.6:1" lg="1280|2:1" }}

通过断点特定的属性接收宽度（可选）和比率，值由管道分隔。结果为

<picture>
    <source type="image/webp" media="(min-width: 1024px)" srcset="
        [img-url]?fm=webp&amp;fit=crop&amp;w=1280&amp;h=640&amp;s=[…] 1x,
        [img-url]?fm=webp&amp;fit=crop&amp;w=2560&amp;h=1280&amp;s=[…] 2x
    ">
    <source type="image/webp" media="(min-width: 768px)" srcset="
        [img-url]?fm=webp&amp;fit=crop&amp;w=1024&amp;h=640&amp;s=[…] 1x,
        [img-url]?fm=webp&amp;fit=crop&amp;w=2048&amp;h=1280&amp;s=[…] 2x
    ">
    <source type="image/webp" media="(min-width: 0px)" srcset="
        [img-url]?fm=webp&amp;fit=crop&amp;w=300&amp;h=200&amp;s=[…] 1x,
        [img-url]?fm=webp&amp;fit=crop&amp;w=600&amp;h=400&amp;s=[…] 2x
    ">
    <img src="[img-url]?w=300&amp;fit=crop&amp;s=[…]" loading="lazy">
</picture>

带大小的基于断点的图像

使用为每个提供的断点提供的源创建图像元素，每个源都有一个根据提供的尺寸调整大小/裁剪的图像。

例如：{{ picture:img default="300|1.5:1|100vw" md="1024|1.6:1|80vw" lg="1280|2:1|960px" }}

通过断点特定的属性接收宽度、比率和尺寸，值由管道分隔。结果为

<picture>
    <source type="image/webp" media="(min-width: 1024px)" srcset="
        [img-url]?fm=webp&amp;fit=crop&amp;w=1280&amp;h=640&amp;s=[…] 1280w,
        [img-url]?fm=webp&amp;fit=crop&amp;w=1920&amp;h=960&amp;s=[…] 1920w,
        [img-url]?fm=webp&amp;fit=crop&amp;w=2560&amp;h=1280&amp;s=[…] 2560w
    " sizes="960px">
    <source type="image/webp" media="(min-width: 768px)" srcset="
        [img-url]?fm=webp&amp;fit=crop&amp;w=1024&amp;h=640&amp;s=[…] 1024w,
        [img-url]?fm=webp&amp;fit=crop&amp;w=1536&amp;h=960&amp;s=[…] 1536w,
        [img-url]?fm=webp&amp;fit=crop&amp;w=2048&amp;h=1280&amp;s=[…] 2048w
    " sizes="80vw">
    <source type="image/webp" media="(min-width: 0px)" srcset="
        [img-url]?fm=webp&amp;fit=crop&amp;w=300&amp;h=200&amp;s=[…] 300w,
        [img-url]?fm=webp&amp;fit=crop&amp;w=450&amp;h=300&amp;s=[…] 450w,
        [img-url]?fm=webp&amp;fit=crop&amp;w=600&amp;h=400&amp;s=[…] 600w
    " sizes="100vw">
    <img src="[img-url]?w=300&amp;fit=crop&amp;s=[…]" loading="lazy">
</picture>

所有方式的附加信息

属性中的空格

如果您愿意，可以在属性中使用空格。这可能会使参数的数量更易于阅读，尤其是在多行使用时

{{ picture:img 
    default="300 | 1.5:1 | 100vw" 
    md="1024 | 1.6:1 | 80vw" 
    lg="1280 | 2:1 | 960px"
}}

图像源

图像源可以以不同的方式提供
{{ picture:img size="300|1.5:1" }}
或者
{{ picture :src="img" size="300|1.5:1" }}
其中img是您的资产字段的字段处理程序。

如果您使用第一种选项，请小心使用JSON模式（见下文）。

您还可以提供资产路径：{{ picture src="/assets/my-image.jpg" size="300|1.5:1" }}

裁剪、比率和尺寸

如果您想保持原始图像的比率（并且根本不裁剪），请使用auto而不是比率
{{ picture:img size="300 | auto | 100vw" […] }}

当不裁剪且不使用sizes属性时，您可以省略除图像宽度之外的所有内容
{{ picture:img size="300" }}

您还可以通过提供宽度和高度来代替使用比率裁剪图像
{{ picture:img size="300x100" md="600x400" }}

如果您想同时使用width x height和sizes属性，只需将auto作为第二个参数即可
{{ picture:img size="300x100 | auto | 100vw" md="600x400 | auto | 80vw" }}

该标签支持比率，如1.5:1或1.5/1，因此请使用您喜欢的任何一种方式。

格式/文件类型

您可以可选地添加一个或多个文件类型用于图像转换
{{ picture:img size="300x100" format="jpg, webp" }}

如果没有找到 format（或 filetype）参数，将使用默认设置（webp），这可以在配置中进行调整。请注意，只有支持的文件类型可用于转换，其他提供的格式将被忽略。

图片方向

默认情况下，Picturesque 假设您正在处理横幅图片。如果您有竖幅图片，可以通过添加 orientation（或简称 ori，供所有不耐烦的人使用）参数来改变这种行为
{{ picture:img size="300 | 2:1" orientation="portrait" }}

所有关于比例等的计算都将使用第一个数字作为高度，并从它计算宽度。如果您在使用竖幅方向时传递两个尺寸（300x100），则第一个尺寸被视为高度，第二个尺寸被视为宽度。

断点

媒体属性的断点可以配置（见下文），并使用默认的 tailwindcss 断点。

默认值（即本质上 0 断点）可以通过 size 或 default 参数进行定义。

JSON 模式

如果您不希望获取预编译的 HTML 字符串，而是希望所有数据都以 JSON 格式传递（例如，传递到 Vue 组件），可以告诉该标签这样做
{{ picture:json :src="img" size="300|1.5:1" }}
或者
{{ picture:img output="json" size="300|1.5:1" }}

结果

{
    "sources": {
        "default": {
            "type": "image\/webp",
            "srcset": "[img-url]?fm=webp&fit=crop&w=300&h=200&s=[…] 1x,[img-url]?fm=webp&fit=crop&w=600&h=400&s=[…] 2x"
        }
    },
    "img": {
        "alt": "Alt text provided by img asset.",
        "class": "",
        "src": "[img-url]?w=300&fit=crop&s=[…]",
        "loading": "lazy"
    }
}

额外的 img 元素属性

要将一些额外的数据传递到生成的 img 元素，以下属性是可用的

替代文本

标签默认会检查源资产中的替代文本。您可以通过这种方式覆盖替代文本
{{ picture:img size="300x200" alt="我希望每个人都关心替代文本。" }}

CSS 类

要将 CSS 类附加到 img 元素，使用此方法
{{ picture:img size="300x200" class="w-full object-cover" }}

如果您想将类附加到图片元素，请使用 wrapperClass 属性
{{ picture:img size="300x200" wrapperClass="foo bar" }}

懒加载

您可以像这样禁用懒加载（默认启用）：{{ picture:img size="300x200" lazy="false" }}

配置中的设置（见下文）允许您调整默认行为。

使用基本类

如果您想在 Antlers 模板之外使用标签的逻辑，可以简单地使用 Picturesque 基本类

use VV\Picturesque\Picturesque;

// ...

public function makePicture(string $imageUrl)
{   
    return (new Picturesque($imageUrl))
        ->default('300 | 1.5:1')
        ->breakpoint('md', '1024 | 1.6:1')
        ->breakpoint('lg', '1280 | 2:1 | 960px')
        ->format(['webp', 'jpg'])
        ->alt('I wish everyone would care about alt texts.')
        ->class('w-full object-cover')
        ->lazy(true)
        ->generate() // you always have to call this!
        ->html(); // or ->json()
}

请注意，当前图像必须是 Statamic 资产，并且必须可以通过资产外观找到（Statamic\Facades\Asset::find($url)）。

配置

该插件通过其 config/picturesque.php 文件提供几个配置选项。查看其中的描述。所有设置都有合理的默认选项，因此在最佳情况下您无需进行配置。

关于我们

• www.visuellverstehen.de

许可证

MIT 许可证（MIT）。有关更多信息，请参阅 许可证文件。