Skip to main content
Version: 3.8.0

📦 plugin-ideal-image

Docusaurus 插件可生成几乎理想的图片（响应式、延迟加载和低质量占位符）。

¥Docusaurus Plugin to generate an almost ideal image (responsive, lazy-loading, and low quality placeholder).

信息

默认情况下，该插件在开发过程中处于非活动状态，因此你始终可以查看全尺寸图片。如果要调试理想的图片行为，可以将 disableInDev 选项设置为 false。

¥By default, the plugin is inactive in development so you could always view full-scale images. If you want to debug the ideal image behavior, you could set the disableInDev option to false.

安装​

¥Installation

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

用法​

¥Usage

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

¥This plugin supports the PNG and JPG formats only.

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

// your React code
<Image img={thumbnail} />

// or
<Image img={require('./path/to/img.png')} />
警告

该插件注册了一个 Webpack 加载器 来更改导入/需要图片的类型：

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

  • 前：string

    ¥Before: string

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

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

对于 pnpm 用户

从 pnpm 10 开始，运行 pnpm install 默认不会运行依赖安装脚本。为了正确安装我们的 sharp 图片调整大小依赖，你需要额外的 pnpm 配置 (issue)，例如：

¥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"]
  }
}

配置​

¥Configuration

接受的字段：

¥Accepted fields:

选项类型默认描述
namestringideal-img/[name].[hash:hex:7].[width].[ext]输出文件的文件名模板。
sizesnumber[]原始尺寸指定你要使用的所有宽度。如果指定的尺寸超过原始图片的宽度，则将使用后者（即图片不会放大）。
sizenumber原始尺寸指定你要使用的一种宽度；如果指定的尺寸超过原始图片的宽度，则将使用后者（即图片不会放大）
minnumber作为手动指定 sizes 的替代方法，你可以指定 min、max 和 steps，系统将为你生成尺寸。
maxnumber参见上面的 min
stepsnumber4配置 min 到 max（含）之间生成的图片数量
qualitynumber85JPEG 压缩质量
disableInDevbooleantrue你可以通过将其设置为 false 在开发模式下测试理想的图片行为。提示：在浏览器中使用 网络节流 来模拟慢速网络。

配置示例​

¥Example configuration

这是一个配置示例：

¥Here's an example configuration:

docusaurus.config.js
export default {
  plugins: [
    [
      '@docusaurus/plugin-ideal-image',
      {
        quality: 70,
        max: 1030, // max resized image's size.
        min: 640, // min resized image's size. if original is lower, use that size.
        steps: 2, // the max number of images generated between min and max (inclusive)
        disableInDev: false,
      },
    ],
  ],
};