clarifynl/responsive-pics

Responsive Pics 是一个用于动态调整图片大小的 WordPress 工具。

维护者

详细信息

github.com/clarifynl/responsive-pics

主页

源代码

问题

文档

安装量: 11,232

依赖关系: 0

建议者: 0

安全: 0

星标: 75

关注者: 7

分支: 5

开放问题: 2

类型:wordpress-plugin

1.8.3 2024-02-27 13:23 UTC

Requires

Requires (Dev)

GPL-3.0 57df38f43607f201e756ebc2ac9c915f00dec301

phpimagewordpressresizingpicture

This package is auto-updated.

Last update: 2024-09-16 23:49:58 UTC

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> 元素以及 srcset 和 sizes 属性。

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

要将 Picturefill 安装到您的 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 通道和 lazyload 的布尔值、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 通道和 intrinsic 的布尔值、图片 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%（等于居中底部）

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

焦点

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

附件详细信息

当单击WordPress媒体库网格视图中的缩略图时，您将看到附件详细信息模态框。这将是最准确选择焦点的方法：[图片链接](https://github.com/clarifynl/responsive-pics/blob/HEAD//assets/images/attachment-details-focal-point-picker.jpg)

特色图像

当在页面或帖子中设置或替换特色图像时，您将看到特色图像模态框。在此视图中，您可以在右侧侧栏顶部的缩略图中选择焦点：[图片链接](https://github.com/clarifynl/responsive-pics/blob/HEAD//assets/images/featured-image-focal-point-picker.jpg)

编辑图像

当在所见即所得编辑器或页面或帖子中的元字段上传或编辑图像时，您将看到编辑图像模态框。在此视图中，您可以在左上角的缩略图中选择焦点：[图片链接](https://github.com/clarifynl/responsive-pics/blob/HEAD//assets/images/edit-image-focal-point-picker.jpg)

您可以通过以下三种方式使用界面设置图像的焦点

  • 直接在图像中点击所需的焦点。
  • 通过将焦点圆圈元素拖放到图像上。
  • 直接在附件输入字段中输入焦点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. 如果媒体库中的原始图像有一个，Alt 文本将自动添加到图片 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 分钟。
你可以将其覆盖为例如 1 分钟，通过为每个 WordPress 网站设置 cron_interval（对于多站点为 cron_interval_multisite）变量为 */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
    (integer) 附件 ID

  • $resize_request
    (array) 调整大小请求参数

[
  '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
    (int) 附件 ID

  • $quality
    (int) 请求的图像质量

  • $width
    (int) 请求的图像宽度

  • $height
    (int) 请求的图像高度

  • $crop
    (array) 请求的图像裁剪位置（百分比）

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

  • $ratio
    (float) 请求的图像比例

  • $resize_path
    (string) 请求的图像文件路径

responsive_pics_file_saved_local

当 ResponsivePics 成功地将调整大小的图像文件保存在本地时，此动作将触发。

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

参数

  • $post_id
    (int) 附件 ID

  • $file
    (array) 包含的已保存文件

  [
    '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
    (int) 附件 ID

  • $file
    (数组) 包含

  [
    '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
    (int) 附件 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
    (int) 附件 ID

  • $file_paths
    (数组) 在您的 S3 存储中被删除的调整大小后的文件路径。

特性

S3 Offload

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

  • 将此插件生成的任何调整大小/裁剪后的图片卸载到您配置的 S3 存储提供商。
  • 当删除附件时，会删除您配置的 S3 存储提供商中由此插件生成的任何调整大小/裁剪后的图片。

注意

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

懒加载

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

  • 向 <img> 元素添加一个 lazyload 类。
  • 将 srcset 与图片 <source> 或 <img> 元素的 data-srcset 属性交换。

这将使您能够使用类似 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扩展，首先按照懒加载部分的说明安装作为Node模块的lazysizes，并将扩展导入到主题的全局JavaScript文件中。

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

问题

有关ResponsivePics库遇到的问题，请提交到Github。

待办事项

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

维护者

ResponsivePics由以下人员开发和维护：

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

版权

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