Gatsby Image 插件
本指南将介绍如何配置您的图片，包括选择布局、占位符和图片处理选项。虽然其中大多数选项都适用于您从任何来源获取图片，但如果您使用 CMS 中的图片，请务必参考您的源插件的文档，因为具体选项可能会有所不同。
组件
Gatsby Image 插件包含两个组件，用于在您的网站上显示响应式图片。一个用于静态图片，另一个用于动态图片。
StaticImage： 如果图片在组件使用时始终相同，则使用此组件。示例：网站 logo，首页主图GatsbyImage： 如果图片作为 prop 传入组件，或者会发生变化，则使用此组件。示例：博客文章主图，作者头像
如果您想了解如何设置图片插件并在您的网站上使用这些组件，请参阅操作指南。
这些是可传递给组件的属性
共享属性
GatsbyImage 和 StaticImage 都可以接收以下属性。您还可以使用任何有效的<img> 标签属性，这些属性将被转发到底层的 <img> 元素。
| 属性 | 类型 | 默认 | 描述 |
|---|---|---|---|
alt (必需) | string | 替代文本，传递给 <img> 标签。对于可访问性是必需的。 | |
as | ElementType | "div" | 用于外部包装器的 HTML 元素。 |
loading | "eager" | "lazy" | "lazy" | 图片的加载行为。对于视口内的图片，应将其设置为 "eager"，以确保它们在 React hydration 之前开始加载。 |
className | string | 应用于外部包装器的 CSS 类。 | |
imgClassName | string | 应用于 <img> 元素的 CSS 类。 | |
style | CSSProperties | 应用于外部包装器的内联样式。 | |
imgStyle | CSSProperties | 应用于 <img> 元素的内联样式。 | |
backgroundColor | string | transparent | 应用于包装器的背景颜色。 |
objectFit | 查看 MDN 文档 | cover | 图片在其容器内的缩放行为。 |
objectPosition | 查看 MDN 文档 | 50% 50% | 图片在其容器内的位置。 |
StaticImage
StaticImage 组件可以接受所有图片选项作为 props，以及所有共享属性。此外，它还接受此属性
| 属性 | 类型 | 描述 |
|---|---|---|
src (必需) | string | 源图片，在构建时处理。可以是相对于源文件的路径，或绝对 URL。 |
使用 StaticImage 的限制
图片在构建时加载和处理，因此在传递属性给组件方面存在限制。值需要能在构建时静态分析，这意味着您不能从组件外部将它们作为 props 传递，也不能使用函数调用的结果，例如。您可以使用静态值，或组件本地范围内的变量。请参见以下示例
这不起作用
这样也不行
如果这些变量和表达式在文件范围内，您就可以使用它们，例如
如果您发现自己希望能够为图片 src 使用 prop，那么您很可能应该使用动态图片。
将 StaticImage 与 CSS-in-JS 库一起使用
StaticImage 组件不支持高阶组件，这包括 Emotion 和 styled-components 等库中的 styled 函数。解析器依赖于能够识别源中的 StaticImage 组件，而将它们传递给函数意味着这不可能。
如果您使用 Emotion，则可以使用提供的 css prop 代替
不幸的是，styled-components 的 css prop 会将代码在底层转换为 styled 函数，如上所述，StaticImage 不支持该语法。
您也可以使用普通的 style 或 className prop。请注意，在所有这些情况下，样式都应用于包装器，而不是图像本身。如果您需要为 <img> 标签设置样式，可以使用 imgStyle 或 imgClassName。如果您使用的样式库计算出的是计算后的类名字符串而不是计算后的样式（例如，如果您使用linaria 等库），则 className 或 imgClassName prop 会很有用。
GatsbyImage
此组件接受所有共享属性以及下面的属性。这些属性直接传递给组件，不应与图片选项混淆，后者在使用动态图片时传递给 GraphQL 解析器。
| 属性 | 类型 | 描述 |
|---|---|---|
image (必需) | GatsbyImageData | 图片数据对象，从 gatsbyImageData 解析器返回。 |
图片选项
对于 StaticImage 和 GatsbyImage，指定选项的方式有几种不同。
如何传递选项：使用
StaticImage时，选项作为 props 传递给组件；而对于GatsbyImage组件，选项则传递给gatsbyImageDataGraphQL 解析器。选项值：在
StaticImage组件中，layout和placeholder等属性接受一个字符串，而解析器接受一个 GraphQL 枚举，该枚举通常为大写，并且不像字符串那样加引号。参考下方将显示两种语法。
重要提示：对于动态图片，这些选项用于sharp 节点上的 gatsbyImageData 解析器。如果您使用来自其他插件（如 CMS 或图片托管）的 gatsbyImageData，则应参考该插件的文档以获取选项，因为它们将与此处的选项不同。静态图片底层使用 sharp，因此在使用 StaticImage 组件时，这些选项也适用。
在编写 gatsbyImageData 查询时，强烈建议使用 GraphiQL IDE。它包含所有选项的自动完成和内联文档，并允许您直接在浏览器中查看生成的图片数据。
静态图片和动态图片都有以下可用选项
| 选项 | 默认字符串/枚举值 | 描述 |
|---|---|---|
layout | "constrained" / CONSTRAINED | 确定图片的大小及其缩放行为。 |
aspectRatio | 源图片宽高比 | 强制图片宽度和高度之间保持特定比例。 |
width/height | 源图片尺寸 | 更改图片尺寸。 |
placeholder | "dominantColor"/DOMINANT_COLOR | 选择加载完整图片时显示的临时图片的样式。 |
formats | ["auto","webp"]/[AUTO,WEBP] | 生成的图片文件格式。 |
transformOptions | {fit: "cover", cropFocus: "attention"}/{fit: COVER, cropFocus: ATTENTION} | 传递给 sharp 以控制裁剪和其他图片操作的选项。 |
查看所有选项。
layout
图片组件支持三种布局类型，它们决定了生成的图片尺寸以及图片在浏览器中的缩放行为。
| 布局 | 组件 prop 值 | 解析器 prop 值 | 描述 |
|---|---|---|---|
| Constrained (受限) | "constrained" | CONSTRAINED | 这是默认布局。它以源图片的大小显示图片，或者您可以设置一个最大尺寸（通过传入 width 或 height）。如果屏幕或容器尺寸小于图片宽度，它会按比例缩小以适应，保持其宽高比。它会生成较小的图片版本，以便移动浏览器不必加载完整尺寸的图片。 |
| Fixed (固定) | "fixed" | FIXED | 这是一个固定尺寸的图片。它将始终以相同尺寸显示，并且不会缩小以适应其容器。这要么是源图片的大小，要么是由 width 和 height props 设置的大小。只有当您确定容器的宽度永远不会小于图片宽度时，才使用此选项。 |
| Full width (全屏) | "fullWidth" | FULL_WIDTH | 将其用于始终以屏幕全屏宽度显示的图片，例如横幅或主图。与 constrained 布局一样，它会缩放以适应容器。但是，它不受最大尺寸的限制，因此无论容器有多大，它都会增长以填满容器，并保持其宽高比。它会为不同的屏幕断点生成几个较小的图片尺寸，以便浏览器只需要加载一个足够大的尺寸来适应屏幕。如果您想指定使用的尺寸，可以传递 breakpoints prop，但在大多数情况下，您可以允许它使用默认值。 |
您可以在下面的视频中比较这些布局
要设置布局，请将类型传递给 layout prop。例如
对于动态图片，将其传递给解析器
width/height
布局：fixed 和 constrained
尺寸属性在 GatsbyImage 和 StaticImage 中是可选的。由于图片是在构建时处理的，插件知道源图片的大小，并可以为 <img> 标签添加正确的宽度和高度，使其在没有布局跳动的情况下正确显示。但是，如果您想更改显示尺寸，可以使用尺寸选项来实现。
对于 fixed 布局，这些属性定义了屏幕上显示的图片尺寸。对于 constrained 图片，这些属性定义了最大尺寸，因为图片会缩小以适应较小的容器（如果需要）。
如果您只设置其中一个，源图片将按该宽度或高度缩放，同时保持宽高比。如果您同时包含两者，它还会根据需要进行裁剪，以确保其尺寸完全相同。
aspectRatio
布局：fixed、constrained 和 fullWidth
aspectRatio prop 可强制图片按指定的宽高比显示，必要时进行裁剪。该值是一个数字，但用作分数可以更清晰，例如 aspectRatio={16/9}
对于 fixed 和 constrained 图片，您还可以选择性地传递 width 或 height，它将使用该值来计算另一个维度。例如，如果您传递 width={800} aspectRatio={4/3}，那么 height 将设置为宽度除以宽高比：即 600。传递 1 作为 aspectRatio 将把图片裁剪成正方形。如果您不传递宽度或高度，它将使用源图片的宽度。
对于 fullWidth 图片，您不指定宽度或高度，因为它会缩放以适应屏幕宽度。传递 aspectRatio 将根据需要裁剪图片，高度将根据屏幕宽度进行缩放。例如，如果您将 aspectRatio 设置为 16/9，那么当图片以全屏宽度显示在 1280px 宽的屏幕上时，图片将为 720 像素高。
注意：有几个高级选项可以用来控制裁剪和缩放行为。有关更多详细信息，请参阅transformOptions参考。
placeholder
Gatsby 图片组件默认是懒加载的，这意味着如果它们不在视口内，浏览器直到它们进入视口才会加载它们。为了确保布局不会混乱，在图片加载之前会显示一个占位符。您可以选择三种占位符类型之一（或者不使用占位符）
| 占位符 | 组件 prop 值 | 解析器 prop 值 | 描述 |
|---|---|---|---|
| 主色调 | "dominantColor" | DOMINANT_COLOR | 默认占位符。它计算源图片的主色调并将其用作纯色背景。 |
| 模糊 | "blurred" | BLURRED | 这会生成源图片的非常低分辨率的版本，并将其显示为模糊背景。 |
| 无 | "none" | NONE | 无占位符。如果您愿意，可以使用背景颜色选项设置一个静态背景。 |
formats
默认组件 prop 值：["auto", "webp"]。默认解析器 prop 值：[AUTO, WEBP]
Gatsby Image 插件支持四种输出格式：JPEG、PNG、WebP 和 AVIF。默认情况下，该插件会生成与源图片格式相同的图片，以及 WebP 格式的图片。例如，如果您的源图片是 PNG，它将生成 PNG 和 WebP 图片。在大多数情况下，您不应更改此设置。但是，在某些情况下，您可能需要手动设置格式。这样做的原因之一是如果您想启用对 AVIF 图片的支持。AVIF 是一种新型图片格式，其文件大小比其他格式显著减小。它目前浏览器支持有限，但这很可能会增加。只要您也为其他浏览器生成了回退，就可以安全地包含它，而图片插件默认会自动执行此操作。
transformOptions
这些值作为对象传递给 transformOptions，可以作为 StaticImage 的 prop，也可以传递给动态图片的解析器。它们是高级设置，大多数人不需要更改。任何提供的对象都会与下面的默认值合并。
| 选项名称 | 默认 | 描述 |
|---|---|---|
grayscale | false | 将图片转换为灰度 |
duotone | false | 添加双色调效果。传递 false，或包含 {highlight: string, shadow: string, opacity: number} 的选项对象 |
rotate | auto | 旋转图片。值的单位为度。 |
trim | 10 | 裁剪“无聊”像素。值是阈值。请参阅 sharp 文档。 |
cropFocus | "attention"/ATTENTION | 控制裁剪行为。有关策略、位置和方向，请参阅 sharp 文档。 |
fit | "cover"/COVER | 调整图片大小并提供宽度和高度时的行为。请参阅 sharp 文档。 |
所有选项
Gatsby Image 插件使用sharp进行图片处理，并支持传递许多高级选项，例如影响裁剪行为或图片效果（包括灰度或双色调）的选项，以及每个格式特有的选项。
| 选项 | 默认 | 描述 |
|---|---|---|
layout | "constrained" / CONSTRAINED | 确定图片的大小及其缩放行为。 |
width/height | 源图片尺寸 | 更改图片尺寸。 |
aspectRatio | 源图片宽高比 | 强制图片宽度和高度之间保持特定比例。 |
placeholder | "dominantColor"/DOMINANT_COLOR | 选择加载完整图片时显示的临时图片的样式。 |
formats | ["auto","webp"]/[AUTO,WEBP] | 生成的图片文件格式。 |
transformOptions | {fit: "cover", cropFocus: "attention"} | 传递给 sharp 以控制裁剪和其他图片操作的选项。 |
sizes | 自动生成 | img 标签的 <img> sizes 属性。这描述了图片的显示尺寸，不影响生成的图片。只有当您使用不跨越屏幕全宽的全屏图片时，您才可能需要更改它。 |
quality | 50 | 生成的默认图片质量。任何特定于格式的选项都会覆盖此设置。 |
outputPixelDensities | 对于 fixed 图片：[1, 2]对于 constrained 图片： [0.25, 0.5, 1, 2] | 要生成的图片像素密度列表。它永远不会生成大于源图片的图片，并且始终包含 1x 图片。该值乘以图片宽度，得到生成尺寸。例如，一个 400px 宽的 constrained 图片默认会生成 100px、200px、400px 和 800px 宽的图片。对于 full width 布局图片，此选项被忽略，它们使用 breakpoints 代替。 |
breakpoints | [750, 1080, 1366, 1920] | 为 full width 图片生成的输出宽度。默认情况下，会为常见的设备分辨率生成宽度。它永远不会生成大于源图片的图片。浏览器会自动选择最合适的。 |
blurredOptions | 无 | 低分辨率占位符图片的选项。除非placeholder设置为 blurred，否则忽略。 |
jpgOptions | 无 | 生成 JPG 图片时传递给 sharp 的选项。 |
pngOptions | 无 | 生成 PNG 图片时传递给 sharp 的选项。 |
webpOptions | 无 | 生成 WebP 图片时传递给 sharp 的选项。 |
avifOptions | 无 | 生成 AVIF 图片时传递给 sharp 的选项。 |
自定义默认选项
您可能会发现自己大部分 GatsbyImage 和 StaticImage 实例都使用了相同的选项（如 placeholder、formats 等）。您可以使用 gatsby-plugin-sharp 自定义默认选项。
以下配置描述了可以自定义的选项及其默认值
辅助函数
有许多实用函数可帮助您处理 gatsbyImageData 对象。我们强烈建议您不要直接访问这些对象的内部结构，因为格式可能会发生变化。
getImage
安全地获取 gatsbyImageData 对象。它接受几种不同类型的对象，并且是 null 安全的，如果传入的对象或任何中间子项为 undefined，则返回 undefined。
如果传入 File 对象，它将返回 file?.childImageSharp?.gatsbyImageData。如果传入包含 gatsbyImageData 字段的节点（例如 ContentfulAsset），它将返回 gatsbyImageData 对象。如果传入的是 gatsbyImageData 对象本身，它将返回相同的对象。
getSrc
获取默认图片 src 作为字符串。这将是回退，通常是 jpg 或 png。接受与 getImage 相同的类型。
getSrcSet
获取默认图像 srcset。这将是备用图像，通常是 jpg 或 png。
withArtDirection
默认情况下，插件会在不同屏幕尺寸下显示不同分辨率的图像，但它也支持艺术指导（art direction），即在不同尺寸下显示视觉上不同的图像。这可能包括在小屏幕上查看时显示一个简化的徽标或对个人资料图片进行更紧密的裁剪。要实现这一点，您可以使用 withArtDirection 函数。您需要从 GraphQL 中获取两种图像，并且应该能够为每个尺寸编写一个媒体查询。
第一个参数是默认图像。当没有媒体查询匹配时，将显示此图像，它还用于设置布局、大小、占位符以及大多数其他选项。然后，您可以传递一个“艺术指导图像”数组，这些图像是具有 media 和 image 值的对象。
当屏幕宽度小于 1024px 时，将显示 smallImage。否则，将显示 largeImage。
纵横比由默认图像设置，不会随不同源自动更改。处理此问题的方法是使用 CSS 媒体查询。例如，您可以使用此 CSS 来更改小图像中容器的大小
然后，您可以使用纯 CSS 或您选择的样式系统来应用此样式。例如：