README

介绍 ResponsiveImageCraft，这是一个强大的 Laravel 包，让您可以通过简单的命令行界面轻松生成各种所需静态格式的响应式图片。此包提供了一种灵活的组件，轻松在您的网页上显示这些响应式图片。此外，您还将发现一系列 SCSS 混合，轻松生成使用图片作为背景图片时所需的代码，确保无缝集成到您的项目中。

使用 ResponsiveImageCraft，您现在可以高效地管理和提供响应式图片，增强您的网站在多种设备上的性能和用户体验。拥抱 ResponsiveImageCraft 的便捷性和灵活性，它将为您承担繁重的工作，轻松实现令人惊叹的视觉效果。所以，还在等什么？今天就用 ResponsiveImageCraft 提升您的图片处理能力吧。

安装

您可以通过 composer 安装此包

composer require infernalmedia/responsive-image-craft

您可以使用以下命令发布配置文件

php artisan vendor:publish --tag="responsive-image-craft-config"

这是发布配置文件的内容

return [
    'use_responsive_images' => env('USE_RESPONSIVE_IMAGES', true),
    'source_disk' => env('RESPONSIVE_IMAGES_SOURCE_DISK', 'public'),
    'target_disk' => env('RESPONSIVE_IMAGES_TARGET_DISK', 's3'),
    'source_directory' => env('RESPONSIVE_IMAGES_SOURCE_DIRECTORY', 'images'),
    'target_directory' => env('RESPONSIVE_IMAGES_TARGET_DIRECTORY', 'images'),
    'sizes' => explode(',', env('RESPONSIVE_IMAGES_SIZES', "320,640,880,1024,1200,1760,2100")),
    'extensions' => [
        Manipulations::FORMAT_JPG,
        Manipulations::FORMAT_PNG,
        Manipulations::FORMAT_AVIF,
        Manipulations::FORMAT_WEBP,
    ],
    'extensions_filters_rules' => [
        Manipulations::FORMAT_JPG => [Manipulations::FORMAT_PNG],
        Manipulations::FORMAT_PNG => [Manipulations::FORMAT_JPG],
        Manipulations::FORMAT_WEBP => [],
        Manipulations::FORMAT_AVIF => [],
    ],
    'extensions_to_ignore' => [
        'svg'
    ],
    'filename_to_ignore' => [
        'favicon'
    ],
    'supported_file_extensions' => [
        Manipulations::FORMAT_JPG,
        Manipulations::FORMAT_WEBP,
        Manipulations::FORMAT_PNG,
        Manipulations::FORMAT_AVIF,
        Manipulations::FORMAT_GIF,
        Manipulations::FORMAT_TIFF,
        Manipulations::FORMAT_PJPG
    ],
    'filename_spacer' => '@',
    'container_css_class_name' => 'img-container'
    'scss_path' => resource_path('/scss/utilities'),
];

可选，您还可以发布 SCSS 辅助工具。SCSS 需要 sass:^1.57 才能正确运行。

php artisan vendor:publish --tag="responsive-image-craft-scss"

用法

图片生成

配置完成后，设置源和目标，然后运行

php artisan responsive-image-craft:generate

可选，您可以定义源

php artisan responsive-image-craft:generate --source-disk=public --relative-source-path=images

响应式图片组件

以下是一个基本的工作配置

<x-infernal-responsive-img src="full/path/to/generated/image.original-extension"
                            alt="the alternate text"
                            height=1570 {{-- original height --}}
                            width=1216 {{-- original width --}} />

将生成以下 HTML

<div class="img-container the-css-class-to-add-to-the-wrapping-container">
    <picture>
        <!-- load avif images if supported -->
        <source type="image/avif" srcset="url-to-img@320.avif 320w, ....{until 1216w}">
        [...]
        <!-- the img format fallback -->       
        <img src="url-to-img.jpg" srcset="url-to-img@320.jpg 320w,...{until 1216w}" alt="the alternate text" decoding="async" loading="lazy" width="1216" height="1570">
    </picture>
</div>

以下属性可用于自定义

$alt
图片的替代文本。了解更多
$skipPictureTag
一个标志，用于跳过 picture 标签，只渲染 img 标签。
$src
图片的相对路径。
$height
原始图片的高度。了解更多
$width
原始图片的宽度了解更多。宽度值将定义最大可用图片宽度，遵循生成的值。
$asyncDecoding
启用图片的异步解码。这可以通过在后台解码图片来提高页面加载性能。了解更多
$lazy
启用图片的懒加载。当设置为 true 时，图片仅在视口中可见时才会加载。了解更多
$containerClass
添加到包装顶部 <div> 的 CSS 类。您可以使用此类应用自定义样式。
$imgAttributes
要添加到 img 标签的额外 HTML 属性。例如："class=img-class data-attribute=attribute"

以下是一个完整示例

<x-infernal-responsive-img src="full/path/to/generated/image.original-extension"
                            alt="the alternate text"
                            container-class="the-css-class-to-add-to-the-wrapping-container" {{-- optional --}}
                            height=1570 {{-- original height --}}
                            width=1216 {{-- original width --}}
                            :async-decoding="true" 
                            :lazy="true" 
                            :skip-picture-tag="false" 
                            img-attributes="attributes to add to img tag" />

将生成以下 HTML

<div class="img-container the-css-class-to-add-to-the-wrapping-container">
    <picture>
        <!-- load avif images if supported -->
        <source type="image/avif" srcset="url-to-img@320.avif 320w, ....{until 1216w}">
        [...]
        <!-- the img format fallback -->       
        <img attributes to add to img tag src="url-to-img.jpg" srcset="url-to-img@320.jpg 320w,...{until 1216w}" alt="the alternate text" decoding="async" loading="lazy" width="1216" height="1570">
    </picture>
</div>

使用 Sass（和 ViteJs）使用响应式图片

配置

将 vite.config.js 配置为向 SCSS 提供环境变量

import { defineConfig, loadEnv } from 'vite'
import laravel from 'laravel-vite-plugin'
import { AssetsScssFile } from './resources/js/AssetsScssFile'

export default defineConfig(async ({ command, mode }) => {
    const env = loadEnv(mode, process.cwd())
    const useResponsiveImages = Boolean(
        JSON.parse(env.VITE_USE_RESPONSIVE_IMAGES.toLowerCase())
    )
    const assetsUrl = useResponsiveImages ? env.VITE_ASSETS_URL : null
    const variables = new Map([
        ['$assetsUrl', assetsUrl],
        ['$filenameSpacer', env.VITE_RESPONSIVE_IMAGES_FILENAME_SPACER],
    ])

    const scss = new AssetsScssFile()
    scss.createSCSSFile(variables)

    return {
        plugins: [
            laravel({
                ...
            }),
        ],
        css: {
            preprocessorOptions: {
                scss: {
                    additionalData: "@use 'assets' as *;",
                },
            },
        },
    }
})

响应式图片 SCSS 混合和样式

响应式图片 SCSS 模块提供了创建响应式背景图片和管理媒体查询的有用混合和样式。

混合使用

使用 responsive-background-image-from-existing-css-var 混合，从由 Laravel 门面 ResponsiveImageCraft::getCssVariables() 生成的现有 CSS 变量生成响应式背景图片

.example-class {
    @include responsive-background-image-from-existing-css-var(
        $sizes: (480px, 768px, 1024px),
        $extensions: ('webp', 'jpg'),
        $full: 'full'
    );
}

或者使用 responsive-background-image 混合生成响应式背景图片

.example-class {
    @include responsive-background-image(
        $base-relative-path: "images/example.jpg",
        $extensions: ('webp', 'jpg'),
        $breakpoints: (480px, 768px, 1024px),
        $file-name-spacer: '@'
    );
}

请注意，扩展列表的顺序将定义浏览器的偏好。

其他有用的函数可以在 /scss/_assets-url-helper.scss 中找到

测试

composer test

变更日志

有关最近更改的更多信息，请参阅变更日志

贡献

有关详细信息，请参阅贡献指南

安全漏洞

有关如何报告安全漏洞，请参阅我们的安全策略

致谢

许可

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

infernalmedia / responsive-image-craft

维护者

详细信息