📦 plugin-ideal-image

生成近乎理想的图像的 Docusaurus 插件（响应式、懒加载及低像素占位图）。

信息

默认情况下，插件在开发模式下不工作，从而允许你始终看到全尺寸的图像。 如果你想调试插件的行为，你可以把 disableInDev 选项设置为 false。

安装流程

npm

npm install --save @docusaurus/plugin-ideal-image

Yarn

yarn add @docusaurus/plugin-ideal-image

pnpm

pnpm add @docusaurus/plugin-ideal-image

Bun

bun add @docusaurus/plugin-ideal-image

用法

此插件仅支持 PNG 和 JPG 格式。

import Image from '@theme/IdealImage';
import thumbnail from './path/to/img.png';

// 你的 React 代码
<Image img={thumbnail} />

// 或者
<Image img={require('./path/to/img.png')} />

警告

This plugin registers a Webpack loader that changes the type of imported/require images:

• Before: string
• After: {preSrc: string, src: import("@theme/IdealImage").SrcImage}

For pnpm users

Starting with pnpm 10, running pnpm install won't run dependency install scripts by default. You'll need additional pnpm configuration (issue) for our sharp image resizing dependency to install correctly, such as:

package.json

{
  "pnpm": {
    "onlyBuiltDependencies": ["fsevents"]
  }
}

配置

接受的字段：

选项	类型	默认值	描述
name	string	ideal-img/[name].[hash:hex:7].[width].[ext]	输出文件的文件名模板。
sizes	number[]	原始尺寸	指定你想使用的所有宽度。 如果指定尺寸超过了原始图像宽度，则使用后者（即图像不会被放大）。
size	number	原始尺寸	指定你想使用的唯一宽度。如果指定尺寸超过了原始图像宽度，则使用后者（即图像不会被放大）。
min	number		除了手动指定 sizes 外，你还可以指定 min、max 及 steps，然后自动生成相应尺寸。
max	number		参见上方的 min。
steps	number	4	配置在 min 与 max 之间生成的图像数量（包括上下限）。
quality	number	85	JPEG 压缩质量。
disableInDev	boolean	true	设置为 false 后，你可以在开发模式下测试插件行为。 提示：可以在浏览器中用网络节流来模拟慢速网络。

示例配置

这是一个示例配置：

docusaurus.config.js

export default {
  plugins: [
    [
      '@docusaurus/plugin-ideal-image',
      {
        quality: 70,
        max: 1030, // max resized image's size.
        min: 640, // 最小缩放图片尺寸。 如果原始值比这还低，会使用原图尺寸。
        steps: 2, // 在 min 和 max 之间最多生成的图片数量（包含两端点）
        disableInDev: false,
      },
    ],
  ],
};