README

Neos 的响应式图片 - 考虑到 Atomic.Fusion 和 Monocle

此包实现了 Neos 的响应式图片，可通过 Fusion 使用。

imageSource = Sitegeist.Kaleidoscope:DummyImageSource

renderer = afx`
    <Sitegeist.Kaleidoscope:Image
        imageSource={props.imageSource}
        srcset="320w, 400w, 600w, 800w, 1000w, 1200w, 1600w"
        sizes="(min-width: 800px) 1000px, (min-width: 480px) 800px, (min-width: 320px) 440px, 100vw"
        width="400"
        height="400"
    />
`

通过将图片定义、尺寸限制和渲染方面分离，我们可以将这些方面分别集成到不同的 fusion 组件中。

我们希望帮助在 atomic-fusion 的背景下实现响应式图片，并允许在 Sitegeist.Monocle 生活方式指南中预览 fusion 组件及其完整的响应式行为。

Sitegeist.Kaleidoscope 包含四个 Fusion-ImageSources

• Sitegeist.Kaleidoscope:AssetImageSource：编辑上传的图片
• Sitegeist.Kaleidoscope:DummyImageSource：由本地服务创建的占位图片
• Sitegeist.Kaleidoscope:ResourceImageSource：来自包的静态资源
• Sitegeist.Kaleidoscope:UriImageSource：任何 URL

作者与赞助商

• Martin Ficzel - ficzel@sitegeist.de
• Wilhelm Behncke - behncke@sitegeist.de

此包的开发和公共发布得到了我们的雇主 http://www.sitegeist.de 的慷慨赞助。

安装

Sitegeist.Kaleidoscope 可通过 packagist 运行 composer require sitegeist/kaleidoscope。我们使用语义版本控制，因此每次重大变更都会增加主版本号。

配置

一些图像库在与 WebP 图像格式一起使用时存在问题。为了避免问题，可以配置回退图像格式，当请求的格式失败时将使用该格式。默认值是 png。

Sitegeist:
  Kaleidoscope:
    dummyImage:
      fallbackFormat: 'png'

此外，由于一些图像库（如 Vips）在生成占位图片时也存在问题，因此可以覆盖驱动程序。默认情况下，此值是 false，并使用在 Neos.Imagine 中配置的默认驱动程序。可能的值是 Gd、Imagick、Gmagick 或 Vips。

Sitegeist:
  Kaleidoscope:
    dummyImage:
      overrideImagineDriver: 'Imagick'

用法

Image/Picture FusionObjects

Kaleidoscope 包集成了两个主要的 fusion-objects，可以将给定的 ImageSource 渲染为 img 或 picture 标签。

Sitegeist.Kaleidoscope:Image

根据 sizes 或 resolutions 渲染带有可选 srcset 的 img 标签。

Props

• imageSource：要渲染的 imageSource
• srcset：默认图像的媒体描述符，如 '1.5x' 或 '600w'（字符串或数组）
• sizes：默认图像的 sizes 属性（字符串或数组）
• loading：（可选，默认 "lazy"）img 标签的加载属性
• format：（可选）图像格式，如 webp 或 png，将应用于 imageSource
• quality：（可选）从 0 到 100 的图像质量，将应用于 imageSource
• width：（可选）基础宽度，将应用于 imageSource
• height：（可选）基础高度，将应用于 imageSource
• alt：img 标签的 alt 属性（默认 ""）
• title：img 标签的 title 属性
• class：img 标签的 class 属性（已弃用，改为 attributes.class）
• attributes：标签属性，将覆盖任何自动渲染的属性
• renderDimensionAttributes：当从 imageSource 获取数据时渲染尺寸属性（宽度/高度）。默认启用

具有多分辨率srcset的图片

imageSource = Sitegeist.Kaleidoscope:DummyImageSource

renderer = afx`
    <Sitegeist.Kaleidoscope:Image
        imageSource={props.imageSource}
        srcset="1x, 2x, 3x"
        />
`

具有多尺寸srcset的图片

imageSource = Sitegeist.Kaleidoscope:DummyImageSource

renderer = afx`
    <Sitegeist.Kaleidoscope:Image
        imageSource={props.imageSource}
        srcset="320w, 400w, 600w, 800w, 1000w, 1200w, 1600w"
        sizes="(min-width: 800px) 1000px, (min-width: 480px) 800px, (min-width: 320px) 440px, 100vw"
        />
`

Sitegeist.Kaleidoscope:图片

渲染带有各种来源的-标签。

Props

• imageSource：要渲染的 imageSource
• sources：支持以下键的源定义数组
  • imageSource：用于艺术方向的备用图像源
  • srcset：(可选) 媒体描述符，如'1.5x'或'600w'（字符串或数组）
  • sizes：(可选) 尺寸属性（字符串或数组）
  • media：(可选) 此源的媒体属性
  • type：(可选) 此源的类型属性
  • format：(可选) 源的图像格式，如webp或png，应用于imageSource和type
  • quality：（可选）从 0 到 100 的图像质量，将应用于 imageSource
  • width：（可选）基础宽度，将应用于 imageSource
  • height：（可选）基础高度，将应用于 imageSource
• srcset：默认图像的媒体描述符，如 '1.5x' 或 '600w'（字符串或数组）
• sizes：默认图像的 sizes 属性（字符串或数组）
• formats：(可选) 将作为单独类型源渲染的图像格式（字符串或数组）
• quality：（可选）从 0 到 100 的图像质量，将应用于 imageSource
• width：（可选）基础宽度，将应用于 imageSource
• height：（可选）基础高度，将应用于 imageSource
• loading：（可选，默认 "lazy"）img 标签的加载属性
• alt：img标签的alt属性
• title：img 标签的 title 属性
• attributes：picture标签属性，将覆盖任何自动渲染的属性
• imgAttributes：img标签属性，将覆盖任何自动渲染的属性
• class：picture标签的class属性（已弃用，建议使用attributes.class）
• renderDimensionAttributes：当从imageSource提供数据时，为img标签渲染维度属性（宽度/高度），如果未指定，则自动为仅使用formats选项的图片启用renderDimensionAttributes。

多格式图片

以下代码将渲染一个带有img标签的图片，以及两个额外的格式为webp和png的源标签，除默认img外。

imageSource = Sitegeist.Kaleidoscope:DummyImageSource

renderer = afx`
    <Sitegeist.Kaleidoscope:Picture
        imageSource={props.imageSource}
        srcset="320w, 600w, 800w, 1200w, 1600w"
        sizes="(min-width: 320px) 440px, 100vw"
        formats="webp, png'
        />
`

多源图片

imageSource、srcset和sizes属性将在未定义其他情况下自动从图片传递到源。

imageSource = Sitegeist.Kaleidoscope:DummyImageSource

renderer = afx`
    <Sitegeist.Kaleidoscope:Picture imageSource={props.imageSource} >
        <Sitegeist.Kaleidoscope:Source
            format="webp"
            srcset='320w, 480w, 800w'
            sizes='(max-width: 320px) 280px, (max-width: 480px) 440px, 100vw'
            />
        <Sitegeist.Kaleidoscope:Source
            srcset="1x, 1.5x, 2x"
            media="screen and (min-width: 1600px)"
            />
        <Sitegeist.Kaleidoscope:Source
            srcset="320w, 480w, 800w"
            sizes="(max-width: 320px) 280px, (max-width: 480px) 440px, 100vw"
            media="screen and (max-width: 1599px)"
            />
        <Sitegeist.Kaleidoscope:Source
            imageSource={props.alternatePintImage}
            media="print"
            />
    </Sitegeist.Kaleidoscope:Picture>
`

Sitegeist.Kaleidoscope:Source

渲染带有srcset、sizes、type和media属性的src-标签。

Props

• imageSource：要渲染的imageSource（从图片继承）
• srcset：(可选) 默认图像的媒体描述符，如'1.5x'或'600w'（字符串或数组，从图片继承）
• sizes：(可选) 尺寸属性（字符串或数组，从图片继承）
• format：(可选) 图像格式，如webp或png，将应用于imageSource和type
• quality：（可选）从 0 到 100 的图像质量，将应用于 imageSource
• width：（可选）基础宽度，将应用于 imageSource
• height：（可选）基础高度，将应用于 imageSource
• type：(可选) 源的类型属性，如image/png或image/webp，实际格式通过imageSource.withFormat()强制执行
• media：(可选) 给定源的媒体查询
• renderDimensionAttributes：当从imageSource提供数据时，为源标签渲染维度属性（宽度/高度），如果未指定，则自动启用。

使用AtomicFusion-Components和Sitegeist.Monocle的响应式图片

prototype (Vendor.Site:Component.ResponsiveKevisualImage) < prototype(Neos.Fusion:Component) {

    #
    # Use the DummyImageSource inside the styleguide
    #
    @styleguide {
        props {
            imageSource = Sitegeist.Kaleidoscope:DummyImageSource
        }
    }

    #
    # Enforce the dimensions of the passed images by cropping to 1600 x 800
    #
    imageSource = null
    imageSource.@process.enforeDimensions = ${value ? value.withWidth(1600).withHeight(900) : null}

    renderer = afx`
        <Sitegeist.Kaleidoscope:Image imageSource={props.imageSource} srcset="1x, 1.5x, 2x" />
    `
}

请注意，强制执行的维度应用于呈现组件。维度强制执行也应用于DummySource以及将由集成定义的AssetSource。

上述组件作为内容元素集成的工作方式如下

prototype (Vendor.Site:Content.ResponsiveKevisual) < prototype(Neos.Neos:ContentComponent) {
    renderer = Vendor.Site:Component.ResponsiveKevisualImage {
        imageSource = Sitegeist.Kaleidoscope:AssetImageSource {
            asset = ${q(node).property('image')}
            title = ${q(node).property('title')}
            alt = ${q(node).property('alternativeText')}
        }
    }
}

这表明集成代码不需要知道所需的图像尺寸或需要哪些变体。这种前端知识现在封装在呈现组件中。

动态启用/禁用延迟渲染

为了优化初始加载时间，延迟加载应禁用于第一个内容，但对于其他内容应启用。这可以通过在ContentCase原型中启用lazy来实现，具体取决于当前节点是否是主集合中的第一个内容。

renderer = Neos.Neos:ContentCollection {
    nodePath = 'main'

    // configure seperate iterator for main content
    content.iterationName = 'mainContentIterator'

    // enable lazynes for first items
    prototype(Sitegeist.Kaleidoscope:Image) {
        loading = ${mainContentIterator.isFirst ? 'eager' : 'lazy'}
    }
    prototype(Sitegeist.Kaleidoscope:Picture) {
        loading = ${mainContentIterator.isFirst ? 'eager' : 'lazy'}
    }
}

ImageSource FusionObjects

该软件包包含封装了渲染图像意图的ImageSource-FusionObjects。ImageSource-Objects返回Eel-Helpers，允许在渲染过程中稍后强制执行渲染的维度。

注意：可以通过融合设置 width、height、thumbnailPreset 和 variantPreset，但也可以应用于返回的对象，这将覆盖融合设置。

Sitegeist.Kaleidoscope:AssetImageSource

参数

• asset：要渲染的图像资产（默认为上下文值 asset）
• async：将图像渲染延迟到浏览器实际请求图像时（默认为 true）
• thumbnailPreset：width 和 height 如上所述支持
• variantPreset：如上所述
• format：设置图像输出格式，例如 webp（默认 null）
• quality：设置图像质量，从 0 到 100（默认 null）
• alt：如果不指定其他内容，则为 alt 属性（默认 null）
• title：如果不指定其他内容，则为 title 属性（默认 null）

Sitegeist.Kaleidoscope:DummyImageSource

参数

• baseWidth：缩放前的图像默认宽度（默认 = 600）
• baseHeight：缩放前的图像默认高度（默认 = 400）
• backgroundColor：占位图像的背景颜色（默认 = '999'）
• foregroundColor：占位图像的前景颜色（默认 = 'fff'）
• text：在图像上渲染的文本（默认 = null，显示大小）
• thumbnailPreset：width 和 height 如上所述支持
• variantPreset：如上所述
• alt：如果不指定其他内容，则为 alt 属性（默认 null）
• title：如果不指定其他内容，则为 title 属性（默认 null）

Sitegeist.Kaleidoscope:UriImageSource

参数

• uri：要渲染的 uri
• alt：如果不指定其他内容，则为 alt 属性（默认 null）
• title：如果不指定其他内容，则为 title 属性（默认 null）

Sitegeist.Kaleidoscope:ResourceImageSource

参数

• package：包密钥（例如 'My.Package'）（默认 = false）
• path：资源路径，可以是相对于 Public 和 package 的路径，或者 resource:// URI（默认 = null）
• !!! thumbnailPreset：width 和 height 对此 ImageSource 无效
• !!! variantPreset 对此 ImageSource 无效

ImageSource Eel-Helpers

上述融合对象创建 ImageSource-helpers 并传递给渲染组件。这些助手允许设置或覆盖目标尺寸，并渲染 src 和 srcset-属性。

可通过 Eel 访问的 ImageSource-Helpers 方法

• withWidth( integer $width, bool $preserveAspect = false )：设置目标宽度，如果需要，修改高度

• withHeight( integer $height, bool $preserveAspect = false )：设置目标高度

• withDimensions( integer, integer)：设置目标宽度和高度

• withThumbnailPreset( string )：通过命名缩略图预设设置宽度和/或高度，从设置 Neos.Media.thumbnailPresets

• withVariantPreset( string, string )：通过命名的变体预设选择图像变体（参数是从设置 Neos.Media.variantPresets 中的 "preset identifier" 键和 "preset variant name" 键）

• withFormat( string )：将图像格式设置为生成，如 webp、png 或 jpeg

• withQuality( integer )：将图像质量设置为 0 到 100

• withAlt( ?string )：设置图像标签的 alt 属性

• withTitle( ?string )：设置图像标签的 title 属性

• src()：为给定的 ImageSource-object 渲染 src 属性

• srcset( array of descriptors )：为具有给定媒体描述符的 ImageSource 渲染 srcset 属性，如 2.x 或 800w

• width()：如果可用，则为 ImageSource 的当前宽度

• height()：如果可用，则为 ImageSource 的当前高度

• alt()：如果可用，则为 ImageSource 的 alt 值

• title()：如果可用，则为 ImageSource 的 title 值

已弃用方法

• applyThumbnailPreset( string )：通过设置 Neos.Media.thumbnailPresets 中的命名缩略图预设来设置宽度和/或高度
• useVariantPreset( string, string )：通过命名的变体预设选择图像变体（参数是从设置 Neos.Media.variantPresets 中的 "preset identifier" 键和 "preset variant name" 键）
• setWidth( 整数 $width, 布尔 $preserveAspect = false )：设置目标宽度，如果 $preserveAspect 为 true，则调整高度
• setHeight( 整数 $height, 布尔 $preserveAspect = false )：设置目标高度
• setDimensions( 整数, 整数)：设置目标宽度和高度
• setFormat( 字符串 )：设置生成的图像格式，如 webp、png 或 jpeg
• setQuality( 整数 )：设置图像质量，范围从 0 到 100

注意：不能直接创建 Eel 辅助函数。它们必须通过使用融合对象 Sitegeist.Kaleidoscope:AssetImageSource 或 Sitegeist.Kaleidoscope:DummyImageSource 来创建。

示例

渲染带有 src 和多个分辨率的 srcset 的 img 标签

    imageSource = Sitegeist.Kaleidoscope:DummyImageSource
    renderer = afx`
        <img
            src={props.imageSource.src()}
            srcset={props.imageSource.srcset('1x, 1.5x, 2x')}
        />
    `

渲染带有 src、srcset 和 sizes 的 img 标签

    imageSource = Sitegeist.Kaleidoscope:DummyImageSource
    renderer = afx`
        <img
            src={props.imageSource.src()}
            srcset={props.imageSource.srcset('400w, 600w, 800w')}
            sizes="(max-width: 320px) 280px, (max-width: 480px) 440px, 800px"
        />
    `

渲染带有多个 source 子元素和 img 退回的 picture 标签

    imageSource = Sitegeist.Kaleidoscope:DummyImageSource
    renderer = afx`
        <picture>
            <source srcset={props.imageSource.withDimensions(400, 400).srcset('200w, 400w')} media="(max-width: 799px)" />
            <source srcset={props.imageSource.srcset('400w, 600w, 800w')} media="(min-width: 800px)" />
            <img src={props.imageSource.src()} />
        </picture>
    `

在此示例中，小于 800px 的设备将显示正方形图像，而更大的设备将渲染原始图像尺寸的多分辨率源

贡献

我们乐意接受贡献。请发送拉取请求。