README

ResponsivePics 是一个 WordPress 插件，允许 WordPress 主题作者自动调整响应式布局中的图片大小^*。

• 节省带宽，让您的网站加载更快
• 无需再定义自定义图片大小
• 为您的主题图片添加视网膜支持
• 支持艺术指导的响应式图片
• 支持 image srcset & sizes 属性
• 支持基于焦点的裁剪
• 支持基于宽高比的裁剪
• 支持 WebP 图片（需要 WordPress 5.8 或更高版本）
• 支持 LQIP（低质量图片占位符）
• 支持懒加载
• 支持基于内比率的框
• 支持使用 WP Offload Media (Lite) 将媒体卸载到 S3 存储
• 支持 WP REST API
• 使用后台处理进行缩放和裁剪任务

_{^{*ResponsivePics 不处理 WordPress wysiwig 编辑器中的图片，仅适用于在主题中使用图片或照片的主题作者。它通过媒体查询自动处理视网膜或 hdpi 图片。}}

文档

有关完整文档和示例，请访问： responsive.pics

目录

1. 要求
2. 安装
3. 配置
4. 使用
5. 大小
6. 裁剪
7. 过程
8. 钩子
9. 特性

要求

安装

您可以通过命令行或 WordPress 管理面板安装此插件。

通过命令行

如果您使用 Composer 管理WordPress，请将 ResponsivePics 添加到项目的依赖项中。

composer require clarifynl/responsive-pics

然后通过 wp-cli 激活插件。

wp plugin activate responsive-pics

通过 WordPress 管理面板

1. 下载此存储库的最新 zip 文件。
2. 在您的 WordPress 管理面板中，导航到 插件->添加新插件
3. 点击 上传插件
4. 上传您下载的 zip 文件。
5. 安装后 激活 插件。

浏览器支持

目前，除了 Internet Explorer 11 之外，所有现代浏览器都支持 <picture> 元素以及 <img> 元素上的 srcset 和 sizes 属性。

为了在尚未支持图片元素的浏览器中启用对这些元素及其相关功能的支持，您可以使用polyfill。我们建议使用Picturefill。

要将Picturefill作为node模块安装到您的WordPress主题中，请在您的主题目录中运行以下命令：

npm

npm install --save picturefill

Yarn

yarn add picturefill

然后，在您的主题的全局JavaScript文件中导入此包：import 'picturefill';

配置

ResponsivePics使用以下默认变量：

默认情况下，ResponsivePics将使用Bootstrap 4 SCSS变量来定义：

网格列数： $grid-columns: 12;
网格间距宽度（像素）： $grid-gutter-width: 30px;
网格断点（像素）

$grid-breakpoints: (
  xs: 0,
  sm: 576px,
  md: 768px,
  lg: 992px,
  xl: 1200px,
  xxl: 1400px
);

和容器的最大宽度（像素）

$container-max-widths: (
  sm: 540px,
  md: 720px,
  lg: 960px,
  xl: 1140px,
  xxl: 1320px
);

注意：ResponsivePics将为您添加xs容器最大宽度（= 576），基于默认的sm网格断点（= 576px）。

如果您已自定义Bootstrap默认设置或正在使用不同的网格系统（如Foundation、Materialize等），或者即使您想添加额外的断点和容器宽度，也可以将您的网格变量传递给ResponsivePics库。

将这些行添加到您的主题的functions.php文件中，并确保检查ResponsivePics类是否存在

/*
 * Set ResponsivePics variables
 */
if (class_exists('ResponsivePics')) {
  ResponsivePics::setColumns(12);
  ResponsivePics::setGutter(30);
  ResponsivePics::setBreakPoints([
    'xs'    => 0,
    'sm'    => 576,
    'md'    => 768,
    'lg'    => 992,
    'xl'    => 1200,
    'xxl'   => 1400,
    'xxxl'  => 1600,
    'xxxxl' => 1920
  ]);
  ResponsivePics::setGridWidths([
    'xs'    => 576,
    'sm'    => 768,
    'md'    => 992,
    'lg'    => 1200,
    'xl'    => 1400,
    'xxl'   => 1600,
    'xxxl'  => 1920
  ]);
  ResponsivePics::setMaxWidthFactor(4);
  ResponsivePics::setLazyLoadClass('lozad');
  ResponsivePics::setLqipWidth(200);
  ResponsivePics::setLqipClass('blurred');
  ResponsivePics::setImageQuality(85);
  ResponsivePics::setRestApiCache(true);
  ResponsivePics::setRestApiCacheDuration(86400);
}

辅助函数

您可以通过运行以下辅助函数之一检索ResponsivePics中使用的任何变量：

ResponsivePics::getColumns();              // Will return $columns
ResponsivePics::getGutter();               // Will return $gutter
ResponsivePics::getBreakpoints();          // Will return $breakpoints
ResponsivePics::getGridWidths();           // Will return $grid_widths
ResponsivePics::getMaxWidthFactor();       // Will return $max_width_factor
ResponsivePics::getLqipWidth();            // Will return $max_width_factor
ResponsivePics::getLazyLoadClass();        // Will return $lazyload_class
ResponsivePics::getLqipWidth();            // Will return $lqip_width
ResponsivePics::getLqipClass();            // Will return $lqip_class
ResponsivePics::getImageQuality();         // Will return $image_quality
ResponsivePics::getRestApiCache();         // Will return $wp_rest_cache
ResponsivePics::getRestApiCacheDuration(); // Will return $wp_rest_cache_duration

用法

图像元素

要在模板中插入响应式的<img>元素，请使用get_image函数或带有可用参数的responsive-pics/v1/image API端点。

PHP

ResponsivePics::get_image(id, sizes, crop, classes, lazyload, lqip);

REST API

GET /wp-json/responsive-pics/v1/image/<id>?sizes=<sizes>&crop=<crop>&classes=<classes>&lazyload=<lazyload>&lqip=<lqip>

图像参数

图像数据

要获取主题中的响应式<img>数据，您可以使用get_image_data函数或使用带有可用参数id、sizes、crop、classes、lazyload和lqip的responsive-pics/v1/image-data API端点。

PHP

ResponsivePics::get_image_data(id, sizes, crop, classes, lazyload, lqip);

REST API

GET /wp-json/responsive-pics/v1/image-data/<id>?sizes=<sizes>&crop=<crop>&classes=<classes>&lazyload=<lazyload>&lqip=<lqip>

这将返回一个数组，包含每个断点上的可用图像源、alt文本、MIME类型、alpha通道和懒加载的布尔值、LQIP图像的URL以及CSS类数组。

[
  'sources'  => (array)  $sources,
  'alt'      => (string) $alt,
  'mimetype' => (string) $mime_type,
  'alpha'    => (bool)   $alpha,
  'lazyload' => (bool)   $lazyload,
  'lqip'     => (string) $lqip,
  'classes'  => (array)  $classes
];

图片元素

要在模板中插入响应式<picture>元素，请使用get_picture函数或带有可用参数的responsive-pics/v1/picture API端点。

PHP

ResponsivePics::get_picture(id, sizes, classes, lazyload, intrinsic);

REST API

GET /wp-json/responsive-pics/v1/picture/<id>?sizes=<sizes>&classes=<classes>&lazyload=<lazyload>&intrinsic=<intrinsic>

图片参数

图片数据

要获取主题中的响应式<picture>数据，您可以使用get_picture_data函数或使用带有可用参数id、sizes、classes、lazyload和intrinsic的responsive-pics/v1/picture-data API端点。

PHP

ResponsivePics::get_picture_data(id, sizes, classes, lazyload, intrinsic);

REST API

GET /wp-json/responsive-pics/v1/picture-data/<id>?sizes=<sizes>&classes=<classes>&lazyload=<lazyload>&intrinsic=<intrinsic>

这将返回一个数组，包含每个断点上的可用图片源、alt文本、MIME类型、alpha通道和内在的布尔值、图片CSS类数组以及img CSS类数组。

[
  'sources'         => (array)  $sources,
  'alt'             => (string) $alt,
  'mimetype'        => (string) $mime_type,
  'alpha'           => (bool)   $alpha,
  'lazyload'        => (bool)   $lazyload,
  'intrinsic'       => (bool)   $intrinsic,
  'picture_classes' => (array)  $picture_classes,
  'image_classes'   => (array)  $image_classes
];

背景图像

要在模板中插入响应式背景图像，请使用get_background函数或使用带有可用参数的responsive-pics/v1/background API端点。

PHP

ResponsivePics::get_background(id, sizes, classes);

REST API

GET /wp-json/responsive-pics/v1/background/<id>?sizes=<sizes>&classes=<classes>

背景参数

背景数据

要获取主题中的响应式背景图像数据，您可以使用get_background_data函数或使用带有可用参数id、sizes和classes的responsive-pics/v1/background-data API端点。

PHP

ResponsivePics::get_background_data(id, sizes, classes);

REST API

GET /wp-json/responsive-pics/v1/background-data/<id>?sizes=<sizes>&classes=<classes>

这将返回一个数组，包含每个断点上的可用背景图像源、alt文本、MIME类型、图像是否有alpha通道的布尔值、背景的ID以及背景CSS类数组。

[
  'sources'  => (array)  $sources,
  'alt'      => (string) $alt,
  'mimetype' => (string) $mime_type,
  'alpha'    => (bool)   $alpha,
  'id'       => (string) $id,
  'classes'  => (array)  $classes
];

支持的图像格式

以下图像文件格式受支持

其他任何图像格式都不会调整大小或裁剪。

尺寸

图像尺寸

在sizes参数中，每个图像尺寸都可用以下语法表示

breakpoint:width

图片 & 背景尺寸

由于<picture>元素和背景图像支持艺术指导图像，因此在sizes参数中为每个图像尺寸提供了以下完整语法

breakpoint:width [/factor|height]|crop_x crop_y

在尺寸语法中，以下参数可用

裁剪

以下选项可作为有效的裁剪位置

裁剪位置缩写

您可以在水平方向（x）中使用以下裁剪位置缩写

• l：左
• c：居中
• r：右
• f：焦点点（有关更多信息，请参阅焦点点部分）

并且垂直方向（y）

• t：顶部
• c：居中
• b：底部

如果未设置垂直方向，则水平方向x将被视为快捷方式

• c：居中居中
• t：顶部居中
• r：右侧居中
• b：居中底部
• l：左侧居中
• f：焦点点（有关更多信息，请参阅焦点点部分）

裁剪位置百分比

您还可以使用百分比作为有效的裁剪位置语法

• 75 10：从左边75%，从顶部10%
• 25 80：从左边25%，从顶部80%
• 50 100：从左边50%，从顶部100%（等于center bottom）

在这种情况下，需要传递坐标x和y。

焦点点

当您想要裁剪图像但保留图像的特定区域可见时，可以使用f(ocal)简写功能。为了设置图像的这个焦点区域，我们在WordPress媒体框架的几个视图中添加了一个焦点选择器界面。

附件详细信息

当从WordPress媒体库网格视图单击缩略图时，您将看到附件详细信息模态窗口。这将是最精确的选择焦点的方法：

特色图像

当在页面或文章中设置或替换特色图像时，您将看到特色图像模态窗口。在这个视图中，您可以在右侧边栏顶部的缩略图中选择您的焦点：

编辑图像

当在所见即所得编辑器中上传或编辑图像，或在页面或文章的元字段中时，您将看到编辑图像模态窗口。在这个视图中，您可以在左上角的缩略图中选择您的焦点：

您可以使用界面中的3种方法来设置图像的焦点

• 通过直接在图像中点击所需的焦点。
• 通过在图像上拖放焦点圆圈元素。
• 通过直接在附件输入字段中输入焦点X轴和Y轴的百分比值。

通过使用这些选项之一，将名为responsive_pics_focal_point的帖子元键添加或更新到附件中，其中包含包含x轴和y轴坐标的数组值。

[
  'x' => '86',
  'y' => '39'
]

要在主题的其它地方使用此值，可以通过调用

$focal_point = get_post_meta($attachment_id, 'responsive_pics_focal_point', true);

处理

1. 当访问前端页面并调用ResponsivePics函数时，此库将使用Action Scheduler将调整大小和/或裁剪图像任务作为作业添加到后台进程队列中。
2. 在每次页面加载或下一个cron间隔时，Action Scheduler将在后台进程队列中运行下一批作业。有关更多信息，请参阅Cron部分。
3. 当队列中的下一个作业准备好处理时，它将执行调整大小和/或裁剪任务，并在成功时将图像保存到与原始图像相同的位置，并从队列中删除该作业。
4. 一旦创建图像变体，它将跳过在下次页面加载中对该变体的处理。
5. 当您更改图像大小参数之一时，它将自动尝试在下次页面加载时创建新的图像变体。
6. 当原始图像不符合请求图像大小的尺寸要求时，它将跳过该图像大小变体，并继续到下一个图像大小。
7. 如果媒体库中的原始图像有一个替代文本，则将在图片img元素上自动添加替代文本。
8. 当从库中删除附件时，它也将删除由此插件创建的所有调整大小的图像。

背景处理

背景处理库 Action Scheduler 内置管理界面，用于监控、调试和手动触发计划中的图片缩放作业。管理界面可以通过以下方式访问

Tools > Scheduled Actions

每个缩放作业都将根据其WordPress图片ID进行分组

Cron

当您使用内置的 WP-Cron 时，后台进程队列只会在每次页面加载时处理任何任务。
如果您已禁用设置中的 WP-Cron 并在服务器上使用自己的cron作业，Action Scheduler 将使用该cron作业中设置的间隔来处理下一批作业。

define('DISABLE_WP_CRON', true);

如果您像我们一样使用 Trellis ❤️，默认cron间隔设置为每 15分钟。
您可以通过设置 cron_interval（或针对多站点设置 cron_interval_multisite）变量来覆盖此设置，每个WordPress站点设置为 */1

例如在 trellis/group_vars/development/wordpress_sites.yml

wordpress_sites:
  example.com:
    site_hosts:
      - canonical: example.test
        redirects:
          - www.example.test
    local_path: ../site # path targeting local Bedrock site directory (relative to Ansible root)
    admin_email: admin@example.test
    multisite:
      enabled: false
    ssl:
      enabled: false
      provider: self-signed
    cache:
      enabled: false
    cron_interval: '*/1'

别忘了更改此值后重新供应服务器。

错误处理

如果在缩放过程中发生错误或存在无效语法，ResponsivePics 将显示或返回错误。

PHP

ResponsivePics errors
- breakpoint xxs is neither defined nor a number

REST API

{
  "code": "responsive_pics_invalid",
  "message": "breakpoint xxs is neither defined nor a number",
  "data": {
    "xs": 0,
    "sm": 576,
    "md": 768,
    "lg": 992,
    "xl": 1200,
    "xxl": 1400
  }
}

钩子

以下操作允许您挂钩到图片缩放流程的时间线。您可以将它们放在主题的 functions.php 文件中。

responsive_pics_request_scheduled

当ResponsivePics向ActionScheduler队列计划新的图片缩放请求时，此操作将触发。

do_action('responsive_pics_request_scheduled', (int) $post_id, (array) $resize_request);

参数

• $post_id
  (整数) 附件ID

• $resize_request
  (数组) 缩放请求参数

[
  'id'         => (int) The attachment ID,
  'quality'    => (int) The requested image quality,
  'width'      => (int) The requested image width,
  'height'     => (int) The requested image height,
  'crop'       => (array) The requested image crop positions,
  'ratio'      => (float) The requested image ratio,
  'path'       => (string) The requested image file path,
  'rest_route' => (string) The requested rest api route
]

responsive_pics_request_processed

当ActionScheduler处理队列中的图片缩放请求时，此操作将触发。

do_action('responsive_pics_request_processed', (int) $post_id, (int) $quality, (int) $width, (int) $height, (array) $crop, (float) $ratio, (string) $resize_path, (string) $rest_route);

参数

• $post_id
  (整数) 附件ID

• $quality
  (整数) 请求的图片质量

• $width
  (整数) 请求的图片宽度

• $height
  (整数) 请求的图片高度

• $crop
  (数组) 请求的图片裁剪位置（百分比表示）

  [
    'x' => (int) The horizontal crop position as percentage,
    'y' => (int) The vertical crop position as percentage
  ]

• $ratio
  (浮点数) 请求的图片比例

• $resize_path
  (字符串) 请求的图片文件路径

responsive_pics_file_saved_local

当ResponsivePics成功将缩放后的图片文件保存在本地时，此操作将触发。

do_action('responsive_pics_file_saved_local', (int) $post_id, (array) $file);

参数

• $post_id
  (整数) 附件ID

• $file
  (数组) 包含以下内容的保存文件

  [
    'path'      => (string) The saved image filepath,
    'file'      => (string) The saved image filename,
    'width'     => (int) The saved image file width,
    'height'    => (int) The saved image file height,
    'mime-type' => (string) The saved image file mime-type,
    'filesize'  => (int) The saved image filesize
  ]

responsive_pics_file_s3_uploaded

当WP Offload Media将缩放后的图片文件上传到您的S3存储时，此操作将触发。

do_action('responsive_pics_file_s3_uploaded', (int) $post_id, (array) $file);

参数

• $post_id
  (整数) 附件ID

• $file
  (数组) 包含以下内容的S3上传文件

  [
    'path'      => (string) The uploaded image filepath,
    'file'      => (string) The uploaded image filename,
    'width'     => (int) The uploaded image file width,
    'height'    => (int) The uploaded image file height,
    'mime-type' => (string) The uploaded image file mime-type,
    'filesize'  => (int) The uploaded image filesize
  ]

responsive_pics_file_deleted_local

当ResponsivePics成功删除本地缩放后的图片文件时，此操作将触发。

do_action('responsive_pics_file_deleted_local', (int) $post_id, (string) $file);

参数

• $post_id
  (整数) 附件ID

• $file
  (字符串) 被删除的图片文件路径

responsive_pics_file_s3_deleted

当WP Offload Media在您的S3存储中删除缩放后的图片文件时，此操作将触发。

do_action('responsive_pics_file_s3_deleted', (int) $post_id, (array) $file_paths);

参数

• $post_id
  (整数) 附件ID

• $file_paths
  (数组) 您S3存储中被删除的缩放文件路径

功能

S3 Offload

当您安装并激活了 WP Offload Media (Lite) 插件时，此库将自动

• 将此插件生成的任何缩放/裁剪图像卸载到您配置的S3存储提供商。
• 删除配置的S3存储服务提供商中由本插件生成的任何调整大小/裁剪的图片。

注意

当在《Offload Media Lite》设置中激活《从服务器删除文件》选项时，此插件不会删除由本插件生成的任何调整大小/裁剪的图片！

延迟加载

当在《get_picture》或《get_image》函数或API端点中启用带有布尔值《true》的《lazyload》选项时，此库会自动

• 为《img》元素添加《lazyload》类。
• 将《srcset》与《data-srcset》属性在《source》或《img》元素上交换。

这将使您能够使用Lazysizes等延迟加载插件。

您也可以通过将类传递给主题的《functions.php》中的《ResponsivePics》库来自定义您的延迟加载类

if (class_exists('ResponsivePics')) {
  ResponsivePics::setLazyLoadClass('lazy');
}

要将《Lazysizes》作为节点模块安装到您的WordPress主题中，请从您的主题目录中运行以下命令

npm

npm install --save lazysizes

Yarn

yarn add lazysizes

并将包导入主题的全局javascript文件中

import 'lazysizes';

当使用字符串值《native》启用《lazyload》时，此库会自动

• 为《img》元素添加原生的《loading="lazy"`》属性。

LQIP（低质量图像占位符）

当在《get_image》函数或《/responsive-pics/v1/image》API端点中启用《lqip》选项时，此库会自动

• 为《img》元素添加《blur-up》类。
• 在《img`元素上添加回退的《src`属性，包含默认宽度为100px的低质量占位符图像。

这将使您在高质量图像加载之前对占位符图像进行样式设置。

您也可以通过将类传递给主题的《functions.php`中的《ResponsivePics`库来自定义您的《lqip`类

if (class_exists('ResponsivePics')) {
  ResponsivePics::setLqipClass('blurred');
}

固有宽高比

当在《get_picture`函数或《/responsive-pics/v1/picture`》API端点中启用《intrinsic`》选项时，此库会自动

• 向《picture`元素添加固有类，向图片《img`元素添加《intrinsic__item`》类。
• 在图片《source`》和《img`元素上添加具有计算出的源图像比例的《data-aspectratio`》属性。

这将使您能够使用固有插件（如lazysizes aspectratio扩展）通过计算高度从图像宽度或宽度从高度来预占图像所需的空间。

要在您的WordPress主题中使用《Lazysizes aspectratio扩展`，首先按照《Lazyloading部分`中所述安装《lazysizes`作为节点模块，并将扩展导入主题的全局javascript文件

import 'lazysizes/plugins/aspectratio/ls.aspectratio.js';

问题

请将您在使用《ResponsivePics`库时遇到的问题提交到Github。

待办事项

• 将应用程序密码身份验证添加到REST API端点。
• 添加Gutenberg块支持。
• 添加WPML（媒体）对焦点点的支持。
• 添加《多个背景图像`》语法支持。
• 添加《批量删除图像`》功能。

维护者

《ResponsivePics`是由以下开发者开发和维护的

@monokai（创建者）
@twansparant（创建者）

版权

代码和文档版权所有 2017-2023，由 Clarify 拥有。
代码在 MIT 许可证 下发布。
文档在创意共享许可下发布。