Skip to main content
官方插件
View plugin on GitHub
See starters using this

gatsby-plugin-sharp

公开了一些基于Sharp图像处理库的图像处理功能. 这是其他Gatsby插件通常使用的低级帮助程序插件. 通常,您不应该直接使用它,但是如果进行非常自定义的图像处理,可能会发现它很有用.

它旨在为处理常见的Web图像格式提供出色的现成设置.

对于JPEG,它将生成默认质量等级为50的逐行图像.

对于PNG,它使用pngquant压缩图像. 默认情况下,它使用[50-75]的质量设置. pngCompressionSpeed值是从1(强力)到10(最快)的速度/质量折衷. 速度10的质量降低了5%,但比默认速度(4)快8倍. 在大多数情况下,您应该坚持默认设置,但是如果您有大量的PNG,则可以大大减少构建时间.

Install

npm install --save gatsby-plugin-sharp

How to use

// In your gatsby-config.js
plugins: [
  {
    resolve: `gatsby-plugin-sharp`,
    options: {
      useMozJpeg: false,
      stripMetadata: true,
      defaultQuality: 75,
    },
  },
]

Methods

resize

Parameters

  • width (整数,默认值:400)
  • height (int)
  • quality (整数,默认值:50)
  • jpegQuality (int)
  • pngQuality (int)
  • webpQuality (int)
  • jpegProgressive (布尔型,默认值:true)
  • pngCompressionLevel (整数,默认值:9)
  • base64 (布尔型,默认值:false)

Returns

  • src (string)
  • width (int)
  • height (int)
  • aspectRatio (float)

fixed

自动创建不同分辨率的尺寸-我们做1倍,1.5倍和2倍.

Parameters

  • width (整数,默认值:400)
  • height (int)
  • quality (整数,默认值:50)
  • jpegQuality (int)
  • pngQuality (int)
  • webpQuality (int)

Returns

  • base64 (string)
  • aspectRatio (float)
  • width (float)
  • height (float)
  • src (string)
  • srcSet (string)

fluid

为图像创建流体尺寸(宽度). 如果用于渲染的降价文件的容器的最大宽度为800px,则尺寸为:200px,400px,800px,1200px,1600px –足以为每种设备尺寸/屏幕分辨率提供接近最佳图像尺寸的图像.

如果要进一步控制输出的大小,可以使用srcSetBreakpoints参数. 例如,如果要使用srcSetBreakpoints: [ 200, 340, 520, 890 ]和890宽的图像,则可以添加srcSetBreakpoints: [ 200, 340, 520, 890 ]作为参数. 您还将获得maxWidth作为断点(默认情况下为800),因此您实际上将获得[ 200, 340, 520, 800, 890 ]作为断点.

最重要的是, fluid返回了其他所有内容(即AspectRatio和用作占位符的base64图像),您需要实施Medium和Facebook普及的"模糊处理"技术(也可以作为Gatsby插件使用,用于Markdown内容作为gatsby -remark-images).

同时提供maxWidthmaxHeight ,默认情况下Sharp会使用COVER作为契合策略来调整图像的大小 . 您可以选择COVERCONTAINFILLINSIDEOUTSIDE作为适合策略. 有关更多详细信息,请参见下面fit参数 .

Parameters

  • maxWidth (整数,默认值:800)
  • maxHeight (int)
  • quality (整数,默认值:50)
  • jpegQuality (int)
  • pngQuality (int)
  • webpQuality (int)
  • srcSetBreakpoints (整数数组,默认值:[])
  • background (字串,预设值:'rgba(0,0,0,1)')
  • [不建议使用] sizeByPixelDensity (布尔型,默认值:false)

    • 像素密度仅用于矢量图像,Gatsby的Sharp实施不支持. 该选项目前是禁止操作,将在下一个主要版本的盖茨比中删除.

Returns

  • base64 (string)
  • aspectRatio (float)
  • src (string)
  • srcSet (string)
  • srcSetType (string)
  • sizes (string)
  • originalImg (string)

Shared Options

除了它们各自的参数外,上述所有方法还共享以下内容:

  • grayscale (布尔型,默认值:false)
  • duotone (bool|obj, default: false)
  • toFormat (字符串,默认值:"")
  • cropFocus (字串,预设值:'ATTENTION')
  • fit (字符串,默认值:" COVER")
  • pngCompressionSpeed (整数,默认值:4)
  • rotate (整数,默认值:0)

toFormat

将源图像转换为以下可用选项之一: NO_CHANGEJPGPNGWEBP .

cropFocus

更改裁剪重点. 可用选项: CENTERNORTHNORTHEASTEASTSOUTHEASTSOUTHSOUTHWESTWESTNORTHWESTENTROPYATTENTION . 请参阅Sharp的调整大小 .

fit

选择适合的策略,以便在调整图像大小时使用锐利的图像. 可用的选项包括: COVERCONTAINFILLINSIDEOUTSIDE . 请参阅Sharp的调整大小 .

注:合适的战略CONTAINFILL将无法正常工作时, cropFocus设置为ENTROPYATTENTION .

下图显示了每个拟合选项的效果. 您可以看到INSIDE选项导致一维尺寸小于请求的尺寸,而OUTSIDE选项导致一维尺寸大于要求的尺寸. 尖锐的变换拟合选项

pngCompressionSpeed

Change the speed/quality tradeoff for PNG compression from 1 (brute-force) to 10 (fastest). See pngquant’s options.

rotate

旋转图像(裁剪后). 参见Sharp的旋转 .

grayscale

使用Sharp的灰度将源图像转换为256级灰度的8位灰度,例如

allImageSharp {
  edges {
    node {
      ... on ImageSharp {
        resize(width: 150, height: 150, grayscale: true) {
          src
        }
      }
    }
  }
}

duotone

如果给定了两个十六进制颜色shadow和高highlight定义了双色调渐变的开始和结束颜色,则对源图像应用"双色调"效果(请参阅IIIIII ).

fixed(
  width: 800,
  duotone: {
    highlight: "#f00e2e",
    shadow: "#192550"
  }
) {
  src
  srcSet
  base64
}

源图像颜色将被转换为匹配根据每个像素的相对亮度选择的渐变颜色.
逻辑是从react-duotone中借用的.

您可以传递第三个可选参数opacity

fluid(
  width: 800,
  duotone: {
    highlight: "#f00e2e",
    shadow: "#192550",
    opacity: 50
  }
) {
  src
  srcSet
  base64
}

如果设置了该选项,则将在原始图像上合成双色调图像的半透明版本,从而使原始图像及其颜色部分"通过". 抬头 :如果原始图像包含Alpha通道,则在创建合成图像之前将其展 .

这是通过在双色调的图像上添加Alpha通道来实现的,然后让Sharp通过overlayWith ; 引用Sharp文档:

如果叠加图像包含Alpha通道,则将发生带预乘的合成.

tracedSVG

生成图像的跟踪SVG(请参阅原始GitHub问题 ),并将SVG返回为" 优化的URL编码 " data: URI. 它用于gatsby-image中,以提供默认内联base64占位符图像的替代方案.

后台使用node-potraceSVGO . node-potrace的默认设置:

  {
    color: `lightgray`,
    optTolerance: 0.4,
    turdSize: 100,
    turnPolicy: TURNPOLICY_MAJORITY,
  }

公开了所有节点电位Potrace参数 ,可以通过traceSVG参数进行设置:

fixed(
  traceSVG: {
    color: "#f00e2e"
    turnPolicy: TURNPOLICY_MINORITY
    blackOnWhite: false
  }
) {
  src
  srcSet
  tracedSVG
}

Setting a default quality

您可以通过设置defaultQuality选项使默认图像质量sharp .

Using MozJPEG

您可以选择使用MozJPEG进行jpeg编码. 与gatsby-plugin-sharp使用的默认编码器相比,MozJPEG提供了更好的图像压缩. 但是,使用MozJPEG时,Gatsby项目的构建时间将大大增加.

要启用MozJPEG,可以在gatsby-config.js中将useMozJpeg插件选项设置为true .

出于向后兼容的原因,如果未在插件选项中定义useMozJpeg ,则环境变量 GATSBY_JPEG_ENCODER如果设置为MOZJPEG则充当后备:

GATSBY_JPEG_ENCODER=MOZJPEG

EXIF and ICC metadata

默认情况下, gatsby-plugin-sharp剥离源文件中存在的所有EXIF,ICC和其他元数据. 建议使用默认值,因为它可以减小文件大小.

但是,在您希望保留EXIF元数据或ICC配置文件的情况下(例如:您正在构建摄影作品集,并希望保留从Adobe Lightroom或Phase One的Capture One中导出的照片的颜色配置文件或版权信息) ,您可以在gatsby-config.js中将stripMetadata插件选项设置为false .

重要的是要注意,如果stripMetadata设置为false ,则将从源图像中保留所有元数据信息,包括但不限于照片拍摄地(如果存在)的纬度/经度信息. 如果希望从源文件中剥离此信息,则可以将stripMetadata为默认值true ,或者使用ExifTool之类的工具手动预处理图像.

Troubleshooting

Incompatible library version: sharp.node requires version X or later, but Z provides version Y

这意味着在node_modules安装了sharp软件包的多个不兼容版本. 完整的错误通常如下所示:

Something went wrong installing the "sharp" module

dlopen(/Users/misiek/dev/gatsby-starter-blog/node_modules/sharp/build/Release/sharp.node, 1): Library not loaded: @rpath/libglib-2.0.dylib
  Referenced from: /Users/misiek/dev/gatsby-starter-blog/node_modules/sharp/build/Release/sharp.node
  Reason: Incompatible library version: sharp.node requires version 6001.0.0 or later, but libglib-2.0.dylib provides version 5801.0.0

要解决此问题,您需要更新当前项目中依赖于sharp软件包的所有Gatsby插件. 这是官方插件的列表,如果您的项目使用它们,可能需要更新:

  • gatsby-plugin-sharp
  • gatsby-plugin-manifest
  • gatsby-remark-images-contentful
  • gatsby-source-contentful
  • gatsby-transformer-sharp
  • gatsby-transformer-sqip

要更新这些软件包,请运行:

npm install gatsby-plugin-sharp gatsby-plugin-manifest gatsby-remark-images-contentful gatsby-source-contentful gatsby-transformer-sharp gatsby-transformer-sqip

如果更新这些内容不能解决问题,则您的项目可能使用了社区中依赖其他版本sharp其他插件. 尝试运行npm list sharpyarn why sharp以查看当前项目中所有使用sharp软件包并尝试对其进行更新.

Docs
Tutorials
Plugins
Blog
Showcase

by  ICOPY.SITE