片段

在操作之间共享字段

AGraphQL 片段是可以在多个查询和mutations之间共享的逻辑片段。

这是一个可以与任何NameParts fragment使用的声明示例：Person 对象：

1
fragment NameParts on Person {
2
  firstName
3
  lastName
4
}

每一个片段都包含属于其关联类型的子集字段。在上面的示例中，Person类型必须声明firstName和lastName字段，以便NameParts片段有效。

现在，我们可以将NameParts片段包含在任何数量的查询和突变中中，这些操作都涉及Person对象，如下所示：

1
query GetPerson {
2
  people(id: "7") {
3
    ...NameParts
4
    avatar(size: LARGE)
5
  }
6
}

你可以使用三个点（...）前置一个包含的片段，就像JavaScript的展开语法。

根据我们的NameParts定义，上述查询等同于：

1
query GetPerson {
2
  people(id: "7") {
3
    firstName
4
    lastName
5
    avatar(size: LARGE)
6
  }
7
}

如果我们以后更改包含在NameParts片段中的字段，我们将自动更改使用该片段的操作包含的字段。这减少了在一系列操作中保持字段一致所需的努力。

示例使用

假设我们有一个博客应用程序，它执行多个与评论相关的GraphQL操作（提交评论、获取文章评论等）。这些操作可能都包含Comment类型的某些字段。

为了指定这个核心字段集，我们可以在Comment类型上定义一个片段，例如：

fragments.js

1
import { gql } from '@apollo/client';
2

3
export const CORE_COMMENT_FIELDS = gql`
4
  fragment CoreCommentFields on Comment {
5
    id
6
    postedBy {
7
      username
8
      displayName
9
    }
10
    createdAt
11
    content
12
  }
13
`;

您可以在应用程序的任何文件中声明片段。上面的示例export将片段从fragments.js文件导出。

然后我们可以将CoreCommentFields 片段在以下操作中使用：

PostDetails.jsx

1
import { gql } from '@apollo/client';
2
import { CORE_COMMENT_FIELDS } from './fragments';
3

4
export const GET_POST_DETAILS = gql`
5
  ${CORE_COMMENT_FIELDS}
6
  query CommentsForPost($postId: ID!) {
7
    post(postId: $postId) {
8
      title
9
      body
10
      author
11
      comments {
12
        ...CoreCommentFields
13
      }
14
    }
15
  }
16
`;
17

18
// ...PostDetails component definition...

我们首先import CORE_COMMENT_FIELDS 因为它们是在另一个文件中声明的。
我们将我们的片段定义添加到GET_POST_DETAILS 的gql模板字面量中，通过占位符（${CORE_COMMENT_FIELDS}）
我们在我们的查询中使用标准的...符号来包含CoreCommentFields片段。

使用 `createFragmentRegistry` 注册命名的片段

从 Apollo Client 3.7 开始，片段可以与您的InMemoryCache注册，这样它们可以在查询或任何InMemoryCache操作（如cache.readFragment、cache.readQuery和cache.watch）中通过名称引用，而无需在声明中插值。

让我们看看React中的示例。

index.js

1
import { ApolloClient, gql, InMemoryCache } from "@apollo/client";
2
import { createFragmentRegistry } from "@apollo/client/cache";
3

4
const client = new ApolloClient({
5
  uri: "https://127.0.0.1:4000/graphql",
6
  cache: new InMemoryCache({
7
    fragments: createFragmentRegistry(gql`
8
      fragment ItemFragment on Item {
9
        id
10
        text
11
      }
12
    `)
13
  })
14
});

由于ItemFragment已经在InMemoryCache中注册，所以它可以用名称引用，如下面片段在GetItemList查询中展开所示。

ItemList.jsx

1
const listQuery = gql`
2
  query GetItemList {
3
    list {
4
      ...ItemFragment
5
    }
6
  }
7
`;
8
function ToDoList() {
9
  const { data } = useQuery(listQuery);
10
  return (
11
    <ol>
12
      {data?.list.map(item => (
13
        <Item key={item.id} text={item.text} />
14
      ))}
15
    </ol>
16
  );
17
}

使用本地版本覆盖已注册的片段

查询可以声明它们自己的本地版本命名的片段，这将优先级高于通过createFragmentRegistry注册的片段，即使本地片段只是由其他已注册片段间接引用。以下是一个例子：

index.js

1
import { ApolloClient, gql, InMemoryCache } from "@apollo/client";
2
import { createFragmentRegistry } from "@apollo/client/cache";
3

4
const client = new ApolloClient({
5
  uri: "https://127.0.0.1:4000/graphql",
6
  cache: new InMemoryCache({
7
    fragments: createFragmentRegistry(gql`
8
      fragment ItemFragment on Item {
9
        id
10
        text
11
        ...ExtraFields
12
      }
13

14
      fragment ExtraFields on Item {
15
        isCompleted
16
      }
17
    `)
18
  })
19
});

在ItemList.jsx中声明的ExtraFields片段的本地版本优先于最初与InMemoryCache一起注册的ExtraFields。因此，当在注册的ItemFragment中解析扩展的ExtraFields片段时，只会使用其定义（仅在执行GetItemList查询时），因为显式定义优先于已注册片段。

ItemList.jsx

1
const listQuery = gql`
2
  query GetItemList {
3
    list {
4
      ...ItemFragment
5
    }
6
  }
7

8
  fragment ExtraFields on Item {
9
    createdBy
10
  }
11
`;
12
function ToDoList() {
13
  const { data } = useQuery(listQuery);
14
  return (
15
    <ol>
16
      {data?.list.map((item) => (
17
        {/* `createdBy` exists on the returned items, `isCompleted` does not */}
18
        <Item key={item.id} text={item.text} author={item.createdBy} />
19
      ))}
20
    </ol>
21
  );
22
}

并列放置片段

GraphQL响应的树形结构类似于前端渲染组件的层次结构。由于这种相似性，您可以使用片段片段将查询逻辑拆分在组件之间，以便每个组件正好请求它使用的字段。这有助于您使组件逻辑更加简洁。

考虑以下应用程序的可视层次结构

1
FeedPage
2
└── Feed
3
    └── FeedEntry
4
        ├── EntryInfo
5
        └── VoteButtons

在这个应用程序中，FeedPage组件执行一个查询来获取FeedEntry对象的列表。子组件EntryInfo和VoteButtons需要从包围的FeedEntry对象中获取特定的字段。

创建联动物件片段

携手合作片段就像任何其他片段一样，只是它附加到使用片段字段的特定组件。例如，VoteButtons是FeedPage的子组件可能会使用来自FeedEntry对象的score和vote { choice }字段：

VoteButtons.jsx

1
VoteButtons.fragments = {
2
  entry: gql`
3
    fragment VoteButtonsFragment on FeedEntry {
4
      score
5
      vote {
6
        choice
7
      }
8
    }
9
  `,
10
};

在子组件中定义片段之后，父组件可以在其自己的联同伴分中引用它，如下所示：

FeedEntry.jsx

1
FeedEntry.fragments = {
2
  entry: gql`
3
    fragment FeedEntryFragment on FeedEntry {
4
      commentCount
5
      repository {
6
        full_name
7
        html_url
8
        owner {
9
          avatar_url
10
        }
11
      }
12
      ...VoteButtonsFragment
13
      ...EntryInfoFragment
14
    }
15
    ${VoteButtons.fragments.entry}
16
    ${EntryInfo.fragments.entry}
17
  `,
18
};

关于VoteButtons.fragments.entry或EntryInfo.fragments.entry的命名没有什么特别之处。任何命名约定都行，只要您能根据组件检索到组件的片段。

使用Webpack时导入片段

当使用graphql-tag/loader加载.graphql文件时，我们可以使用import语句来包含片段。例如：

1
#import "./someFragment.graphql"

这使当前文件可用someFragment.graphql的内容。有关详细信息，请参阅Webpack Fragments部分。

使用联合和接口上的片段

您可以在联合和接口上定义片段。

以下是一个包含三个内联片段的查询示例：

1
query AllCharacters {
2
  all_characters {
3

4
    ... on Character {
5
      name
6
    }
7

8
    ... on Jedi {
9
      side
10
    }
11

12
    ... on Droid {
13
      model
14
    }
15
  }
16
}

上面的 all_characters 查询返回一个 Character 对象列表。 Character 类型是一个接口，Jedi 和 Droid 类型都实现了该接口。列表中的每个项如果是一个 Jedi 类型的对象，则包含一个 side 字段；如果是一个 Droid 类型的对象，则包含一个 model 字段。

但是，要使此查询能够工作，您的客户端需要理解 Character 接口及其实现类型之间的多态关系。为了通知客户端这些关系，您可以在初始化您的 InMemoryCache 时传递一个 possibleTypes 选项。

手动定义 `possibleTypes`

该 possibleTypes 选项在 Apollo Client 3.0 及更高版本中可用。

您可以将 possibleTypes 选项传递给 InMemoryCache 构造函数以指定架构中的超类与子类之间的关系。此对象将一个接口或联合类型的名称（超类）映射到实现或属于它的类型（子类）。

以下是一个 possibleTypes 声明的示例：

1
const cache = new InMemoryCache({
2
  possibleTypes: {
3
    Character: ["Jedi", "Droid"],
4
    Test: ["PassingTest", "FailingTest", "SkippedTest"],
5
    Snake: ["Viper", "Python"],
6
  },
7
});

该示例列出了三个接口（Character，Test 和 Snake）以及实现它们的对象类型。

如果您的架构只包含少数几个联合和接口，您可能可以手动指定 possibleTypes 而无问题。但是，当您的架构在规模和复杂性方面增长时，您应考虑自动从架构生成 possibleTypes。

自动生成 `possibleTypes`

以下示例脚本将GraphQL introspection 查询转换为一个 possibleTypes 配置对象：

1
const fetch = require('cross-fetch');
2
const fs = require('fs');
3

4
fetch(`${YOUR_API_HOST}/graphql`, {
5
  method: 'POST',
6
  headers: { 'Content-Type': 'application/json' },
7
  body: JSON.stringify({
8
    variables: {},
9
    query: `
10
      {
11
        __schema {
12
          types {
13
            kind
14
            name
15
            possibleTypes {
16
              name
17
            }
18
          }
19
        }
20
      }
21
    `,
22
  }),
23
}).then(result => result.json())
24
  .then(result => {
25
    const possibleTypes = {};
26

27
    result.data.__schema.types.forEach(supertype => {
28
      if (supertype.possibleTypes) {
29
        possibleTypes[supertype.name] =
30
          supertype.possibleTypes.map(subtype => subtype.name);
31
      }
32
    });
33

34
    fs.writeFile('./possibleTypes.json', JSON.stringify(possibleTypes), err => {
35
      if (err) {
36
        console.error('Error writing possibleTypes.json', err);
37
      } else {
38
        console.log('Fragment types successfully extracted!');
39
      }
40
    });
41
  });

然后您可以将生成的possibleTypes JSON模块导入到创建您的InMemoryCache的地方：

1
import possibleTypes from './path/to/possibleTypes.json';
2

3
const cache = new InMemoryCache({
4
  possibleTypes,
5
});

`useFragment`

The useFragment hook将轻量级的实时绑定到 Apollo 客户端的缓存。它允许 Apollo 客户端向单个组件广播特定的fragment结果。此 hook 返回缓存当前为给定fragment包含的任何数据的始终最新的视图。useFragment永远不会触发它自己的网络请求。

useQuery hook 仍然负责在缓存中查询和填充数据的主要 hook（查看 API 参考）。因此，通过 fragment数据通过useFragment读取的组件仍然订阅query数据中的所有变更，但只有在特定 fragment的数据变更时才会收到更新。

注意：此 hook 在3.7.0作为实验性功能引入，但在3.8.0中稳定下来。在3.7.x和3.8.0-alpha.x版本中，此 hook 以useFragment_experimental的形式导出。从3.8.0-beta.0及更高版本开始，其命名导出中不再包含_experimental后缀。

示例

考虑到以下fragment定义：

1
const ItemFragment = gql`
2
  fragment ItemFragment on Item {
3
    text
4
  }
5
`;

我们可以首先使用useQuery hook 获取具有id的项以及在任何命名的ItemFragment fragment 上选择的任何字段。通过在ListQuery中的list内部散播ItemFragment done，可以完成此操作。

1
const listQuery = gql`
2
  query GetItemList {
3
    list {
4
      id
5
      ...ItemFragment
6
    }
7
  }
8
  ${ItemFragment}
9
`;
10

11
function List() {
12
  const { loading, data } = useQuery(listQuery);
13

14
  return (
15
    <ol>
16
      {data?.list.map(item => (
17
        <Item key={item.id} id={item.id}/>
18
      ))}
19
    </ol>
20
  );
21
}

注意：我们可以在每次query中内插fragments的界面，我们还可以使用 Apollo 客户端的createFragmentRegistry方法预先将命名的fragments注册到我们的InMemoryCache中。这允许 Apollo 客户端在网络请求之前将注册的fragment的定义包括在要发送的文档中。有关更多信息，请参阅使用createFragmentRegistry注册命名的fragments。

然后，我们可以在<Item>组件内部使用useFragment，通过提供fragment document、fragmentName及通过 from的对象引用，为每个项创建实时绑定。

1
function Item(props: { id: number }) {
2
  const { complete, data } = useFragment({
3
    fragment: ItemFragment,
4
    fragmentName: "ItemFragment",
5
    from: {
6
      __typename: "Item",
7
      id: props.id,
8
    },
9
  });
10

11
  return <li>{complete ? data.text : "incomplete"}</li>;
12
}

useFragment 可以与 @nonreactive 指令结合使用，在需要列表项对单个缓存更新进行响应而不重新渲染整个列表的情况下。有关更多信息，请参阅 @nonreactive 文档。

请参阅API参考获取更多详细信息。

指令