GraphQL 查询选项

简介

本页面将引导您完成一系列 GraphQL 查询，每个查询都旨在演示 GraphQL 的特定功能。这些示例将在 graphql-reference 示例 中使用的*真实* schema 上运行。您可以本地运行此示例来尝试和探索站点的内部结构！要访问 GraphiQL 编辑器，请转到 localhost:8000/___graphql（注意是三个下划线）。您也可以打开示例站点的 CodeSandbox 版本。

有关更多背景信息，请阅读关于 Gatsby 为什么使用 GraphQL 以及 如何在任何 Gatsby 站点中使用 GraphiQL。

基本查询

示例：站点元数据

从基础开始，从 gatsby-config.js 的 siteMetadata 中提取站点的 title。

在 GraphiQL 编辑器中，尝试编辑查询以包含 siteMetadata 中的 description。在查询编辑器中键入时，您可以使用 Ctrl + Space 查看自动完成选项，并使用 Ctrl + Enter 运行当前查询。

示例：多个数据节点

Gatsby 将其内容构建为 nodes 的集合，这些节点通过 edges 连接。在此查询中，您要求获取此 Gatsby 站点的插件总数，以及每个插件的特定信息。

在 GraphiQL 编辑器中，尝试使用编辑器的自动完成功能（Ctrl + Space）来获取 packageJson 节点中的扩展详细信息。

如果您使用的是 Gatsby 版本 2.2.0 或更高版本，您可以从查询中删除 edges 和 node，并用 nodes 替换。查询仍将正常工作，并且返回的对象将反映 nodes 结构。

字段参数

本节介绍您可以传递给 GraphQL 字段的各种参数。

限制（Limit）

有几种方法可以减少查询结果的数量。这里 totalCount 告诉您有 8 个结果，但 limit 用于仅显示前三个。

跳过（Skip）

跳过一定数量的结果。在此查询中，skip 用于省略前 3 个结果。

过滤（Filter）

在此查询中，使用 filter 参数和 ne（不等于）操作符来仅显示具有标题的结果。您可以在 LevelUpTuts Gatsby Tutorial #9: Filters & Sorting with GraphQL 中找到关于此内容的优秀视频教程。

所有可能的操作符列表

Gatsby 依赖 Sift 来启用类似 MongoDB 的对象过滤查询语法。这使得 Gatsby 支持 eq、ne、in、regex 等操作符，并通过 ___ 连接符查询嵌套字段。

在列表下方的代码块中，有一个示例查询，其中描述了每个操作符查询的作用。

• eq：等于的缩写，必须与给定数据完全匹配
• ne：不等于的缩写，必须与给定数据不同
• regex：正则表达式的缩写，必须匹配给定的模式
• glob：全局的缩写，允许使用通配符 *，它充当任何非空字符串的占位符
• in：在数组中的缩写，必须是数组中的一个元素
• nin：不在数组中的缩写，不能是数组中的一个元素
• gt：大于的缩写，必须大于给定值
• gte：大于或等于的缩写，必须大于或等于给定值
• lt：小于的缩写，必须小于给定值
• lte：小于或等于的缩写，必须小于或等于给定值
• elemMatch：元素匹配的缩写，这表示您正在过滤的字段将返回一个元素数组，您可以在该数组上使用前面的操作符应用过滤器

如果您想更深入地了解这些过滤器的工作原理，查看代码库中相应的 测试 会非常有帮助。

对多个字段进行过滤

通过用逗号分隔各个过滤器（这相当于 AND 操作），也可以对多个字段进行过滤。

在此查询中，categories 和 title 字段被过滤，以查找属于 magical creatures 类别 *并且* 标题中包含 Fantastic 的书籍。

组合操作符

您也可以组合提到的操作符。此查询使用 regex 操作符按 /History/ 进行过滤，这将返回 Hogwarts: A History 和 History of Magic。然后 ne 操作符会过滤掉 History of Magic，因此最终结果只包含 Hogwarts: A History。

排序（Sort）

结果的顺序可以通过 sort 指定。这里的结果按 frontmatter 的 date 字段升序排序。

对多个字段进行排序

您也可以按多个字段排序。以下查询的结果按 date 和 title 字段的升序排序。

Children's Anthology of Monsters 和 Break with Banshee 的日期相同（1992-01-02），但在第一个查询（只有一个排序字段）中，后者排在前者之后。对 title 的额外排序将 Break with Banshee 放在了正确的顺序。

排序顺序

您可以通过提供 ASC（升序）或 DESC（降序）值来指定排序 order。例如，要按 frontmatter.date 升序排序，并另外按 frontmatter.title 降序排序，您将使用 sort: [{ frontmatter: { date: ASC }}, { frontmatter: { title: DESC }}]。

格式化

日期

日期可以使用 formatString 函数进行格式化。

Gatsby 依赖 Moment.js 来格式化日期。这允许您在字符串中使用任何令牌。有关更多令牌，请参阅 Moment.js 文档。

您还可以传入 locale 以根据您的语言调整输出。上面的查询为您提供了英文的星期几输出，此示例则以德语输出。

示例：anotherDate(formatString: "dddd, MMMM Do YYYY, h:mm:ss a") # Sunday, August 5th 2018, 10:56:14 am

日期还接受 fromNow 和 difference 函数。前者返回一个使用 Moment.js 的 fromNow 函数生成的字符串，后者返回日期与当前时间之间的差值（使用 Moment.js 的 difference 函数）。

摘要（Excerpt）

摘要接受三个选项：pruneLength、truncate 和 format。format 可以是 PLAIN 或 HTML。

示例：组合使用排序、过滤、限制和格式化

此查询将排序、过滤、限制和格式化组合在一起。

查询变量

除了直接将查询参数添加到查询字段之外，GraphQL 还允许您传入“查询变量”。这些可以是简单的标量值，也可以是对象。

下面的查询与上一个示例中的查询相同，但将输入参数作为“查询变量”传入。

要将变量添加到页面组件查询中，请在 创建页面时将其传递给 context 对象。

分组（Group）

您还可以基于某个字段（如标题、日期或类别）对值进行分组，并获取字段值、出现次数总数以及边（edges）。

下面的查询获取应用于书籍的所有类别（fieldValue）以及某个类别应用的图书数量（totalCount）。此外，您还可以获取给定类别中图书的 title。例如，此查询的响应包含 magical creatures 类别中的 3 本书。

片段（Fragments）

片段是保存常用查询以供重用的方法。

要创建片段，请在查询中定义它，并将其作为命名导出从 Gatsby 可识别的任何文件中导出。片段可在项目的任何其他 GraphQL 查询中使用，无论其位置如何。

片段在 Gatsby 项目中是全局定义的，因此名称必须是唯一的。

下面的查询定义了一个获取站点标题的片段，然后使用该片段来访问此信息。

别名（Aliasing）

想在同一个数据源上运行两个查询？您可以通过为查询设置别名来实现。请参见下面的查询示例

当您使用数据时，您将能够使用别名而不是根查询名称来引用它。在此示例中，它将是 data.someEntries 或 data.someMoreEntries（而不是 data.allMarkdownRemark）。

在查询内部的字段上同样适用。看这个例子

您将获得 header 而不是 title。当您想以不同的方式显示相同的字段时，这尤其有用，例如 date 所展示的那样。您从同一个源获取 date 和 relativeDate。

条件语句

GraphQL 允许您根据变量跳过查询的一部分。当您需要有条件地渲染页面的某个部分时，这非常方便。

在 GraphiQL 编辑器中，尝试更改下面的示例查询中的变量 withDate。

使用指令 @include(if: $variable) 有条件地包含查询的一部分，或使用 @skip(if: $variable) 来排除它。

您可以在查询的任何级别甚至片段上使用这些指令。看一个高级示例