从 gatsby-image 迁移到 gatsby-plugin-image

本文档旨在帮助 gatsby-image 的用户迁移到使用 gatsby-plugin-image。

请注意，您可以同时使用这两个包。在您使用与 gatsby-image 兼容的 CMS 作为数据源，而该 CMS 插件尚未更新到与新 API 兼容的版本时，您可能需要这样做。

如果您正在寻找有关新插件的其他文档，请参阅

• 操作指南：使用 beta Gatsby Image 插件
• 参考指南：Gatsby Image 插件

有什么变化？

新的语法

新插件需要进行重大的语法更改。我们提供了一个代码转换工具 (codemod) 来帮助您迁移，但本节将解释这些更改。

导入变更

以前，GatsbyImage 是从 gatsby-image 导出的默认项。使用 gatsby-plugin-image 后，该组件现在是命名导出。

GraphQL 变更

这是较大的变更之一。不再有需要使用的 fragments。取而代之的是，诸如 layout 和 format 之类的东西作为参数传递给 resolver。

这是之前的语法。

新的语法如下所示。 fragments 已被移除，取而代之的是 gatsbyImageData，它用于所有图像。之前的配置选项 - 例如 fixed 与 fluid、WebP 生成和占位符类型 - 作为参数传递给 resolver。

可用参数结构的更多更改位于“API 变更”部分。

组件变更

最后一个更改是 JSX 组件。导入名称可能不同，查询结果也不同。

API 变更

除了使用 gatsby-plugin-image 的语法更改外，API 本身也发生了变化，这会影响 resolver 参数（以及新的 StaticImage 组件）。

fluid

fluid 图像类型已被弃用，取而代之的是两种替代方案。

第一种是称为 fullWidth 的图像类型。此图像旨在用于跨越屏幕全宽的英雄图像等内容，并相应地生成图像尺寸。它不接受 maxWidth 之类的参数，而是接受一个名为 breakpoints 的数组，该数组将生成适合这些屏幕尺寸的图像。在大多数情况下，您无需提供这些，因为存在适用于大多数站点的默认值。请注意，与旧的 fluid 布局一样，fullWidth 图像将扩展以适应其容器的宽度，即使该宽度大于源图像。

第二种是称为 constrained 的响应式图像类型，它会与其容器一起缩小并生成较小的图像，但不会比原始图像源尺寸更大。此外，您可以传递 width 和/或 height 来将显示的图像限制为该尺寸。在这种情况下，可能会为高密度屏幕生成较大的图像。

maxWidth

对于所有图像类型，maxWidth 和 maxHeight 都已弃用。对于 constrained 和 fixed 图像，请使用 width 和 height。对于 fullWidth 图像，请查看 breakpoints 选项。

aspectRatio

aspectRatio 是一个新参数，接受一个数字（或分数）。如果仅在不传递 width 或 height 的情况下传递它，它将默认使用源图像宽度，然后将高度调整为正确的纵横比。或者，您可以传递自己的 width 或 height，它将设置另一个维度。同时传递 height 和 width 将导致 aspectRatio 被忽略，而使用推断的纵横比。

formats

以前，图像默认会生成自己的类型，例如 JPG、PNG 等。您也可以在使用适当的 fragments 时生成 WebP 图像。现在使用 formats 参数进行控制。此字段接受一个数组，默认为 [AUTO, WEBP]，其中 AUTO 表示与源图像相同的格式。AVIF 现在也是一个有效的格式。

嵌套在对象中的选项

以前，诸如 grayscale 之类的转换和诸如 pngQuality 之类的质量选项是顶层查询参数。这已经改变了。

grayscale 现在位于 transformOptions 参数内，而 pngQuality 在 pngOptions 中的 quality。有关详细信息，请参阅 gatsby-plugin-image 参考指南。

破坏性变更

由于 gatsby-plugin-image 的更改，某些功能不再受支持。

1. GatsbyImage 不再是类组件，因此无法对其进行扩展。您可以使用组合来代替。

2. fluid 图像已不再存在，而 fullWidth 的替代方案不接受 maxWidth 或 maxHeight。

3. 艺术指导 API 已更改，请参阅 gatsby-plugin-image 参考指南 以了解详细信息。

4. 该组件不再接受解构的对象，以下代码无效。您应该避免访问或更改 gatsbyImageData 对象的内容，因为它不被视为公共 API，因此可以随时更改。

如何迁移

1. 安装并更新依赖项。

2. 配置插件。

3. 运行代码转换工具。

   请注意，如果您需要进行部分迁移（例如，因为您正在使用一个尚不支持新插件与本地图像文件一起使用的 CMS），您应该利用 optional-path 来针对单个文件运行。

   如果没有 optional-path，代码转换工具将针对当前目录中的所有文件运行，因此建议在根目录运行。它会自动忽略 node_modules、.cache 和 public。它还将尊重项目中的任何本地 Babel 配置。代码转换工具设计用于处理扩展名为 .ts、.js、.tsx 和 .jsx 的文件。如果这不适用于您的项目，或者您需要其他自定义设置，请参阅有关使用 jscodeshift 的部分。

   由于 API 的更改，代码转换工具不是纯粹的 1:1 映射。引入了一些更改。

   • Fluid 图像将映射到 fullWidth 或 constrained 图像。此决定是根据 maxWidth 的存在及其值做出的。如果 maxWidth 不存在，它将是 fullWidth 图像。如果存在，并且 maxWidth 小于 1000，它将是 constrained 图像，否则是 fullWidth 图像。fullWidth 图像不保留其 maxWidth 或 maxHeight 字段；constrained 图像保留，作为 width 和 height。

   • 所有图像将生成 WebP。

   代码转换工具将在多种不同情况下输出警告，并指向相关文件，以便您可以手动检查更改。

4. 考虑手动更改。

• 对于使用静态查询的图像，您应该改用 StaticImage 组件。此组件接受 src，它可以是远程图像 URL 或图像的相对路径。如果您将使用此组件，请确保已安装 gatsby-source-filesystem。

• 您还可以考虑重构代码以利用 getImage 辅助函数。

• 最后，如果您之前使用了 src（例如，用于 SEO 组件），您将需要使用 getSrc 辅助函数，因为返回对象的内部结构已更改。

jscodeshift

本节适用于需要使用 jscodeshift 暴露的额外标志来运行代码转换工具的人员，例如，转换扩展名不是 .js、.ts、.tsx 或 .jsx 的文件类型。

1. 安装 jscodeshift。

2. 在项目中安装代码转换工具包。

3. 使用 jscodeshift 运行代码转换工具。

有关所有可用标志，请参阅 jscodeshift 文档。