📦 plugin-ideal-image

道格龙（Docusaurus）插件，用于生成近乎理想的图片（响应式、懒加载、低质量占位图）。

信息

默认情况下，插件在开发环境下不启用，这样你总能看到原始尺寸图片。如果你想调试理想图片的行为，可以将 disableInDev 选项设置为 false。

安装

npm
Yarn
pnpm
Bun

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

yarn add @docusaurus/plugin-ideal-image

pnpm add @docusaurus/plugin-ideal-image

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')} />

注意

本插件注册了一个 Webpack loader，会改变 import/require 图片的类型：

变更前：string
变更后：{preSrc: string, src: import("@theme/IdealImage").SrcImage}

针对 pnpm 用户

从 pnpm 10 开始，运行 pnpm install 默认不会执行依赖安装脚本。你需要额外配置 pnpm（相关 issue），以确保我们的 sharp 图片缩放依赖能正确安装，例如：

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, // 最大缩放后图片尺寸。
        min: 640, // 最小缩放后图片尺寸。如果原图更小，则使用原图尺寸。
        steps: 2, // 在 min 和 max 之间生成的最大图片数量（含）
        disableInDev: false,
      },
    ],
  ],
};

安装​

用法​

配置​

示例配置​

安装

用法

配置

示例配置