GraphQL API

Gatsby 的一个主要优势是其内置的数据层，它整合了您配置的所有数据源。数据在 构建时 收集，并自动组装成一个 模式，该模式定义了如何在整个站点中查询数据。

本文档作为 Gatsby 内置 GraphQL 功能的参考，包括查询和源数据的方法，以及根据您站点的需求定制 GraphQL。

GraphQL 入门

GraphQL 在 Gatsby 中无需特殊安装即可使用：当您运行 gatsby develop 或 gatsby build 时，会自动推断并创建模式。在站点编译时，数据层可以在以下地址进行 探索：https://:8000/___graphql

数据源

数据需要被 源化 — 或添加到 GraphQL 模式 — 才能通过 GraphQL 查询并拉取到页面中。Gatsby 使用 源插件 来拉取数据。

请注意：GraphQL 不是必需的，您仍然可以 在没有 GraphQL 的情况下使用 Gatsby。

要使用现有插件源化数据，您需要安装所有必需的包。此外，您必须将插件添加到 gatsby-config 的插件数组中，并附带任何可选配置。如果您想从文件系统源化数据以供 GraphQL 使用，例如 Markdown 文件、图片等，请参阅 文件系统数据源文档。

有关从 npm 安装插件的说明，请参阅有关 使用插件 的文档中的说明。

您也可以 创建自定义插件 来适应您自己的用例，并以您想要的任何方式拉取数据。

查询组件和 Hooks

可以使用以下选项之一在页面、组件或 gatsby-node.js 文件中查询数据

• pageQuery 组件
• useStaticQuery Hook

注意：由于 Gatsby 处理 GraphQL 查询的方式，您不能在同一个文件中混合使用页面查询和静态查询。您也不能在一个文件中拥有多个页面查询或静态查询。

有关页面组件和非页面组件与查询的关系的信息，请查看有关 使用组件构建 的文档指南。

pageQuery

pageQuery 是一个内置组件，用于从 Gatsby 页面的数据层检索信息。每个页面只能有一个页面查询。它可以接受 GraphQL 参数来设置查询中的变量。

Gatsby 中的 页面 是通过 src/pages 文件夹中的任何 React 组件创建的，或者通过调用 createPage 操作并使用 createPage 选项中的组件来创建——这意味着 pageQuery 不能在任何组件中使用，只能在满足此条件的组件中使用。

另外，请参阅关于 使用 page query 在页面中查询数据 的指南。

参数

页面查询不是一个方法，而是一个导出的变量，它被赋值为一个 graphql 字符串和一个有效的查询块作为其值。

注意：在 const 中导出的查询不一定需要命名为 pageQuery。更重要的是，Gatsby 会查找从文件中导出的 graphql 字符串。

返回值

当包含在页面组件文件中时，页面查询会返回一个数据对象，该对象会自动作为 prop 传递给组件。

useStaticQuery

useStaticQuery Hook 可以在任何组件或页面中使用。

因为这是一个 React Hook，所以 Hooks 规则 适用。由于 Gatsby 目前处理查询的方式，每个文件只支持一个 useStaticQuery 实例。

另外，请参阅关于 使用 useStaticQuery 在组件中查询数据 的指南。

参数

useStaticQuery Hook 接受一个参数

• query：一个 graphql 查询字符串

返回值

useStaticQuery Hook 返回一个对象形式的数据

查询结构

查询的编写方式与您希望返回数据的形状相同。您如何源化数据将决定您可以查询的字段名称，这取决于它们向 GraphQL 模式添加的节点。

要理解查询的各个部分，请参考 概念指南。

GraphQL 查询参数

GraphQL 查询可以接受参数来改变数据返回的方式。这些参数的逻辑由 Gatsby 内部处理。参数可以传递到查询任何级别的字段。

不同的节点可以根据节点的性质接受不同的参数。

您可以传递给集合（如数组或长列表数据 - 例如 allFile 或 allMdx）的参数是

• filter
• limit
• sort
• skip

您可以传递给 date 字段的参数是

• formatString
• locale

您可以传递给 excerpt 字段的参数是

• pruneLength
• truncate

GraphQL 查询操作

其他内置配置可以在查询中使用

• Alias
• Group

有关示例，请参阅 GraphQL 查询选项参考指南。

查询片段

片段允许您重用 GraphQL 查询的部分。它们还允许您将复杂的查询拆分成更小、更易于理解的组件。

有关更多信息，请查看有关 在 Gatsby 中使用片段 的文档指南。

Gatsby 片段

一些片段包含在 Gatsby 插件中，例如用于通过 gatsby-image 和 gatsby-transformer-sharp 返回各种格式的优化图像数据的片段，或者通过 gatsby-source-contentful 的数据片段。有关哪些插件包含片段的更多信息，请参阅 gatsby-image README。

高级定制

您可以在 GraphQL 层中定制源数据，并使用 Gatsby Node API 在节点之间创建关系。

GraphQL 模式可以为更高级的用例进行定制：在 模式定制 API 文档 中阅读更多相关信息。