自3.8.0

Suspense

使用 Apollo Client 与 React 18 Suspense 功能

"Suspense"通常指用React 18中引入的新并发渲染引擎构建React应用的方式并发渲染引擎在React 18中引入。它也是一个特定的React API，<Suspense />，一个允许你显示回退内容的组件，直到其子组件加载完成。

本指南探讨了Apollo Client's data fetching hooks introduced in 3.8, which leverage React's powerful Suspense features.

要跟随下面的示例，请打开我们的Suspense 演示在 CodeSandbox 上。

使用 Suspense 获取数据

`useSuspenseQuery` 钩子触发一个网络请求，并在请求期间使调用该组件挂起。您可以将它视为 `useQuery` 的 Suspense 版本，允许您在渲染过程中获取数据时利用 React 的 Suspense 功能。

让我们看一下一个例子

1
import { Suspense } from 'react';
2
import {
3
  gql,
4
  TypedDocumentNode,
5
  useSuspenseQuery
6
} from '@apollo/client';
7

8
interface Data {
9
  dog: {
10
    id: string;
11
    name: string;
12
  };
13
}
14

15
interface Variables {
16
  id: string;
17
}
18

19
interface DogProps {
20
  id: string
21
}
22

23
const GET_DOG_QUERY: TypedDocumentNode<Data, Variables> = gql`
24
  query GetDog($id: String) {
25
    dog(id: $id) {
26
      # By default, an object's cache key is a combination of
27
      # its __typename and id fields, so we should always make
28
      # sure the id is in the response so our data can be
29
      # properly cached.
30
      id
31
      name
32
      breed
33
    }
34
  }
35
`;
36

37
function App() {
38
  return (
39
    <Suspense fallback={<div>Loading...</div>}>
40
      <Dog id="3" />
41
    </Suspense>
42
  );
43
}
44

45
function Dog({ id }: DogProps) {
46
  const { data } = useSuspenseQuery(GET_DOG_QUERY, {
47
    variables: { id },
48
  });
49

50
  return <>Name: {data.dog.name}</>;
51
}

ⓘ 注意

这个示例手动为 Data 和 Variables 以及 GET_DOG_QUERY 的类型定义使用 TypedDocumentNode。 GraphQL 代码生成器是一个流行的工具，可以为您自动创建这些类型定义。有关将 TypeScript 代码生成器与 Apollo Client 集成的更多信息，请参阅。

在本示例中，我们的 App 组件渲染了一个 Dog 组件，该组件通过 useSuspenseQuery 获取单个狗狗的记录。当 React 首次尝试渲染 Dog 时，缓存无法满足对 GetDog 查询的请求，因此 useSuspenseQuery 便启动了一个网络请求。Dog 组件在网络请求挂起期间暂停渲染，并触发 Suspense 边界，该边界位于 App 组件中暂停组件之上，渲染我们的 "正在加载..." 默认内容。一旦网络请求完成，Dog 将使用新缓存的 name 渲染名叫 Cookie 的斗牛犬。

你可能已经注意到，useSuspenseQuery 并不返回一个 loading 布尔值。这是因为调用 useSuspenseQuery 的组件在获取数据时总是挂起。一个推论是，当它确实渲染时，data 总是定义的！在 Suspense 架构中，存在 在挂起组件之外 的回退内容，可以替换之前由组件自己渲染的加载状态。

ⓘ 注意

对于 TypeScript 用户：由于 GET_DOG_QUERY 是一个 TypedDocumentNode，我们在其中通过 Data 泛型参数指定了结果类型，所以 useSuspenseQuery 返回的 data 的 TypeScript 类型反映了这一点！这意味着当 Dog 组件渲染时，data 总是定义的，并且 data.dog 的形状为 { id: string; name: string; breed: string; }。

更改变量

在上一个示例中，我们通过传递到一个预先编码的 id 变量来通过 useSuspenseQuery 获取单个狗狗的记录。现在，假设我们想要通过动态值获取其他狗狗的记录。我们将获取我们列表中狗狗的 name 和 id，一旦用户选择了一个单独的狗狗，我们会获取更多的细节，包括它们的 breed。

更新我们的示例

1
export const GET_DOG_QUERY: TypedDocumentNode<
2
  DogData,
3
  Variables
4
> = gql`
5
  query GetDog($id: String) {
6
    dog(id: $id) {
7
      id
8
      name
9
      breed
10
    }
11
  }
12
`;
13

14
export const GET_DOGS_QUERY: TypedDocumentNode<
15
  DogsData,
16
  Variables
17
> = gql`
18
  query GetDogs {
19
    dogs {
20
      id
21
      name
22
    }
23
  }
24
`;
25

26
function App() {
27
  const { data } = useSuspenseQuery(GET_DOGS_QUERY);
28
  const [selectedDog, setSelectedDog] = useState(
29
    data.dogs[0].id
30
  );
31

32
  return (
33
    <>
34
      <select
35
        onChange={(e) => setSelectedDog(e.target.value)}
36
      >
37
        {data.dogs.map(({ id, name }) => (
38
          <option key={id} value={id}>{name}</option>
39
        ))}
40
      </select>
41
      <Suspense fallback={<div>Loading...</div>}>
42
        <Dog id={selectedDog} />
43
      </Suspense>
44
    </>
45
  );
46
}
47

48
function Dog({ id }: DogProps) {
49
  const { data } = useSuspenseQuery(GET_DOG_QUERY, {
50
    variables: { id },
51
  });
52

53
  return (
54
    <>
55
      <div>Name: {data.dog.name}</div>
56
      <div>Breed: {data.dog.breed}</div>
57
    </>
58
  );
59
}

通过 select 更改狗狗会导致组件在每次选择尚未存在于缓存中的狗狗记录时暂停。一旦我们在缓存中加载了某个狗狗的记录，再次从下拉列表中选定该狗狗不会导致组件重新暂停，因为根据我们的 cache-first 缓存优先获取策略，Apollo Client 在缓存命中后不会发起网络请求。

无挂起状态更新状态

有时我们可能想要在处理挂起的网络请求时避免显示加载中的UI，而是选择继续显示之前的渲染。要做到这一点，我们可以使用一个过渡来标记我们的更新为非紧急。这告诉React在新的数据完成加载之前保持现有UI的状态。

要将状态更新标记为过渡，我们使用React的startTransition函数。

让我们修改我们的示例，以便在过渡期间，先前显示的狗保留在屏幕上，同时下一个狗被获取

1
import { useState, Suspense, startTransition } from "react";
2

3
function App() {
4
  const { data } = useSuspenseQuery(GET_DOGS_QUERY);
5
  const [selectedDog, setSelectedDog] = useState(
6
    data.dogs[0].id
7
  );
8

9
  return (
10
    <>
11
      <select
12
        onChange={(e) => {
13
          startTransition(() => {
14
            setSelectedDog(e.target.value);
15
          });
16
        }}
17
      >
18
        {data.dogs.map(({ id, name }) => (
19
          <option key={id} value={id}>{name}</option>
20
        ))}
21
      </select>
22
      <Suspense fallback={<div>Loading...</div>}>
23
        <Dog id={selectedDog} />
24
      </Suspense>
25
    </>
26
  );
27
}

通过将我们的setSelectedDog状态更新包装在React的startTransition函数中，我们就不会再在选择新狗时看到Suspense后备！相反，之前的狗会一直保留在屏幕上，直到下一个狗的记录加载完成。

过渡期间的挂起UI显示

在先前的示例中，在选择新狗时，没有视觉效果表明正在进行获取操作。为了提供良好的视觉反馈，让我们更新我们的示例以使用React的useTransition钩子，它为您提供一个isPending布尔值，以确定何时发生过渡。

让我们在过渡发生时变暗选择下拉菜单

1
import { useState, Suspense, useTransition } from "react";
2

3
function App() {
4
  const [isPending, startTransition] = useTransition();
5
  const { data } = useSuspenseQuery(GET_DOGS_QUERY);
6
  const [selectedDog, setSelectedDog] = useState(
7
    data.dogs[0].id
8
  );
9

10
  return (
11
    <>
12
      <select
13
        style={{ opacity: isPending ? 0.5 : 1 }}
14
        onChange={(e) => {
15
          startTransition(() => {
16
            setSelectedDog(e.target.value);
17
          });
18
        }}
19
      >
20
        {data.dogs.map(({ id, name }) => (
21
          <option key={id} value={id}>{name}</option>
22
        ))}
23
      </select>
24
      <Suspense fallback={<div>Loading...</div>}>
25
        <Dog id={selectedDog} />
26
      </Suspense>
27
    </>
28
  );
29
}

部分数据的渲染

当缓存中包含部分数据时，您可能希望立即渲染这些数据而不是挂起。要做到这一点，请使用returnPartialData选项。

ⓘ 注意

此选项仅当与cache-first（默认）或cache-and-network获取策略结合使用时才有效。cache-only目前不支持useSuspenseQuery。有关这些获取策略的详细信息，请参阅设置获取策略。

让我们更新我们的示例以使用部分缓存数据和立即渲染

1
interface PartialData {
2
  dog: {
3
    id: string;
4
    name: string;
5
  };
6
}
7

8
const PARTIAL_GET_DOG_QUERY: TypedDocumentNode<
9
  PartialData,
10
  Variables
11
> = gql`
12
  query GetDog($id: String) {
13
    dog(id: $id) {
14
      id
15
      name
16
    }
17
  }
18
`;
19

20
// Write partial data for Buck to the cache
21
// so it is available when Dog renders
22
client.writeQuery({
23
  query: PARTIAL_GET_DOG_QUERY,
24
  variables: { id: "1" },
25
  data: { dog: { id: "1", name: "Buck" } },
26
});
27

28
function App() {
29
  const client = useApolloClient();
30

31
  return (
32
    <Suspense fallback={<div>Loading...</div>}>
33
      <Dog id="1" />
34
    </Suspense>
35
  );
36
}
37

38
function Dog({ id }: DogProps) {
39
  const { data } = useSuspenseQuery(GET_DOG_QUERY, {
40
    variables: { id },
41
    returnPartialData: true,
42
  });
43

44
  return (
45
    <>
46
      <div>Name: {data?.dog?.name}</div>
47
      <div>Breed: {data?.dog?.breed}</div>
48
    </>
49
  );
50
}

在本示例中，我们将部分数据写入Buck的缓存，以显示当查询无法完全从缓存中得到满足时的行为。useSuspenseQuery，我们通过将returnPartialData选项设置为true告诉useSuspenseQuery我们不介意渲染部分数据。Apollo Client则在后台从网络中获取缺少的查询数据。

在第一次渲染时，Buck 的名字显示在 Name 标签后面，接着是带有空值的 Breed 标签。一旦缺失的字段加载完成，useSuspenseQuery 将触发重新渲染并显示 Buck 的品种。

ⓘ 注意

针对 TypeScript 用户：将 returnPartialData 设置为 true 时，data 属性的返回类型会将查询类型中的所有 fields 标记为可选。当返回部分数据时，Apollo Client 无法准确地确定缓存中存在的字段。

错误处理

默认情况下，useSuspenseQuery 会抛出网络错误和 GraphQL 错误。这些错误会被最近的错误边界捕获并显示。

ⓘ 注意

错误边界是一个实现了 static getDerivedStateFromError 的 类组件。有关更多信息，请参阅 React 文档中关于使用错误边界捕获渲染错误的部分。

让我们创建一个基本的错误边界，当查询抛出错误时，它将渲染一个错误 UI：

1
class ErrorBoundary extends React.Component {
2
  constructor(props) {
3
    super(props);
4
    this.state = { hasError: false };
5
  }
6

7
  static getDerivedStateFromError(error) {
8
    return { hasError: true };
9
  }
10

11
  render() {
12
    if (this.state.hasError) {
13
      return this.props.fallback;
14
    }
15

16
    return this.props.children;
17
  }
18
}

ⓘ 注意

在实际应用中，您的错误边界可能需要更健壮的实现。考虑在使用高度灵活和可重用的库时使用如 react-error-boundary 时。

当 GET_DOG_QUERY 在 Dog 组件中返回 GraphQL 错误或网络错误时，useSuspenseQuery 会抛出错误，最近的错误边界会渲染其备选组件。

我们的示例还没有错误边界，让我们添加一个！

1
function App() {
2
  const { data } = useSuspenseQuery(GET_DOGS_QUERY);
3
  const [selectedDog, setSelectedDog] = useState(
4
    data.dogs[0].id
5
  );
6

7
  return (
8
    <>
9
      <select
10
        onChange={(e) => setSelectedDog(e.target.value)}
11
      >
12
        {data.dogs.map(({ id, name }) => (
13
          <option key={id} value={id}>
14
            {name}
15
          </option>
16
        ))}
17
      </select>
18
      <ErrorBoundary
19
        fallback={<div>Something went wrong</div>}
20
      >
21
        <Suspense fallback={<div>Loading...</div>}>
22
          <Dog id={selectedDog} />
23
        </Suspense>
24
      </ErrorBoundary>
25
    </>
26
  );
27
}

在这里，我们使用了我们的 ErrorBoundary 组件并将其放置在我们的 Dog 组件外部。现在，当 Dog 组件中的 useSuspenseQuery 钩子抛出错误时，ErrorBoundary 会捕获错误并显示我们提供的 fallback 元素。

ⓘ 注意

在许多 React 框架中，当出现错误并且带有错误边界时，您可能在开发模式下看到错误对话框蒙版。这旨在防止开发者错过错误。

在错误旁边渲染部分数据

在某些情况下，您可能希望在错误旁边渲染部分数据。为此，将 errorPolicy 选项设置为 all。通过设置此选项，useSuspenseQuery 避免抛出错误，而是设置钩子返回的 error 属性。要完全忽略错误，将 errorPolicy 设置为 ignore。有关更多信息，请参阅 errorPolicy 文档。

避免请求瀑布效应

由于 useSuspenseQuery 在加载数据时挂起，所有使用 useSuspenseQuery 的组件的树可以引起 "瀑布"，每个对 useSuspenseQuery 的调用都依赖于上一个调用完成，然后才能开始加载数据。这可以通过使用 useBackgroundQuery 和使用 useReadQuery 读取数据来避免。

useBackgroundQuery 在父组件中启动数据请求并返回一个 queryRef，该引用被传递给 useReadQuery 以在子组件中读取数据。当子组件在数据加载完成之前渲染时，子组件将挂起。

让我们更新我们的示例以利用 useBackgroundQuery:

1
import {
2
  useBackgroundQuery,
3
  useReadQuery,
4
  useSuspenseQuery,
5
} from '@apollo/client';
6

7
function App() {
8
  // We can start the request here, even though `Dog`
9
  // suspends and the data is read by a grandchild component.
10
  const [queryRef] = useBackgroundQuery(GET_BREEDS_QUERY);
11

12
  return (
13
    <Suspense fallback={<div>Loading...</div>}>
14
      <Dog id="3" queryRef={queryRef} />
15
    </Suspense>
16
  );
17
}
18

19
function Dog({ id, queryRef }: DogProps) {
20
  const { data } = useSuspenseQuery(GET_DOG_QUERY, {
21
    variables: { id },
22
  });
23

24
  return (
25
    <>
26
      Name: {data.dog.name}
27
      <Suspense fallback={<div>Loading breeds...</div>}>
28
        <Breeds queryRef={queryRef} />
29
      </Suspense>
30
    </>
31
  );
32
}
33

34
interface BreedsProps {
35
  queryRef: QueryRef<BreedData>;
36
}
37

38
function Breeds({ queryRef }: BreedsProps) {
39
  const { data } = useReadQuery(queryRef);
40

41
  return data.breeds.map(({ characteristics }) =>
42
    characteristics.map((characteristic) => (
43
      <div key={characteristic}>{characteristic}</div>
44
    ))
45
  );
46
}

我们开始在 App 组件渲染时获取我们的 GET_BREEDS_QUERY。网络请求在 React 渲染我们的其他组件树时在后台进行。当 Dog 组件渲染时，它获取我们的 GET_DOG_QUERY 并挂起。

当网络请求GET_DOG_QUERY完成时，Dog组件恢复挂起并继续渲染，达到Breeds组件。由于我们的GET_BREEDS_QUERY请求是使用useBackgroundQuery在组件树上更高处启动的，因此GET_BREEDS_QUERY的网络请求已完成！当Breeds组件从useBackgroundQuery提供的queryRef读取数据时，它避免了挂起并立即使用获取的数据进行渲染。

ⓘ 注意

当GET_BREEDS_QUERY的获取时间比GET_DOG_QUERY更长时，useReadQuery挂起，并且在Dog组件中渲染了回退。

关于性能的说明

父组件中使用的useBackgroundQuery钩子负责启动获取，但不处理读取或渲染数据。这被委托给子组件中使用的useReadQuery钩子。这种关注点的分离提供了一种良好的性能优势，因为缓存更新可以由useReadQuery观察到，并且只重新渲染子组件。您可能会发现这是一个有用的工具，可以优化组件结构，以避免在缓存数据更改时无必要地重新渲染父组件。

响应用户交互进行获取
自3.9.0

使用钩子的useSuspenseQuery和useBackgroundQuery允许我们在组件挂载时立即加载数据。但是，用户交互时如何加载查询呢？例如，我们可能希望在用户将鼠标悬停在链接上时开始加载数据。

自Apollo Client3.9.0起提供，useLoadableQuery钩子可以在用户交互时启动网络请求。

useLoadableQuery返回一个执行函数和一个queryRef。执行函数在用提供的变量调用时启动网络请求。与useBackgroundQuery类似，将queryRef传递给子组件中的useReadQuery会在查询加载完成之前挂起子组件。

ⓘ 注意

在执行函数首次被调用之前，queryRef是null。因此，任何尝试使用queryRef读取数据的孩子组件应该进行有条件的渲染。

让我们更新我们的示例，以在从下拉列表中选择时开始加载狗的细节。

1
import {
2
  // ...
3
  useLoadableQuery
4
} from '@apollo/client';
5

6
function App() {
7
  const { data } = useSuspenseQuery(GET_DOGS_QUERY);
8
  const [loadDog, queryRef] = useLoadableQuery(GET_DOG_QUERY);
9

10
  return (
11
    <>
12
      <select
13
        onChange={(e) => loadDog({ id: e.target.value })}
14
      >
15
        {data.dogs.map(({ id, name }) => (
16
          <option key={id} value={id}>
17
            {name}
18
          </option>
19
        ))}
20
      </select>
21
      <Suspense fallback={<div>Loading...</div>}>
22
        {queryRef && <Dog queryRef={queryRef} />}
23
      </Suspense>
24
    </>
25
  );
26
}
27

28
function Dog({ queryRef }: DogProps) {
29
  const { data } = useReadQuery(queryRef)
30

31
  return (
32
    <>
33
      <div>Name: {data.dog.name}</div>
34
      <div>Breed: {data.dog.breed}</div>
35
    </>
36
  );
37
}

通过在 onChange 处理函数中调用 loadDog 函数，我们开始检索我们的 GET_DOG_QUERY。一旦网络请求开始，queryRef 就不再为 null，这将渲染 Dog 组件。

useReadQuery 在网络请求完成时挂起 Dog 组件，然后返回数据到组件。因此，我们也消除了在组件状态中跟踪所选狗狗 id 的需要。

在 React 之外启动查询
自3.9.0

从 Apollo Client 的 3.9.0 版本开始，查询可以在 React 之外启动。这允许你的应用程序在 React 渲染你的组件之前开始加载数据，并提供性能优势。

要预加载数据查询，你首先需要使用 createQueryPreloader 创建一个预加载数据函数。函数 createQueryPreloader 接收一个 ApolloClient 实例作为参数，并返回一个函数，当调用该函数时，将启动一个网络请求。

💡 提示

考虑将你的预加载数据函数和你的 ApolloClient 实例一起导出。这样，你可以直接导入该函数，而不需要在每次预加载数据时传递你的 ApolloClient 实例。

预加载数据函数返回一个 queryRef，该 queryRef 传递到 useReadQuery 以读取查询数据并在加载时挂起组件。 useReadQuery 确保你的组件在预加载数据的缓存更新时保持更新。

让我们更新我们的例子，在应用绘制之前开始加载 GET_DOGS_QUERY。

1
import {
2
  // ...
3
  createQueryPreloader
4
} from '@apollo/client';
5

6
// This `preloadQuery` function does not have to be created each time you
7
// need to preload a new query. You may prefer to export this function
8
// alongside your client instead.
9
const preloadQuery = createQueryPreloader(client);
10
const preloadedQueryRef = preloadQuery(GET_DOGS_QUERY);
11

12
function App() {
13
  const { data } = useReadQuery(preloadedQueryRef);
14
  const [queryRef, loadDog] = useLoadableQuery(GET_DOG_QUERY)
15

16
  return (
17
    <>
18
      <select
19
        onChange={(e) => loadDog({ id: e.target.value })}
20
      >
21
        {data.dogs.map(({ id, name }) => (
22
          <option key={id} value={id}>{name}</option>
23
        ))}
24
      </select>
25
      <Suspense fallback={<div>Loading...</div>}>
26
        <Dog queryRef={queryRef} />
27
      </Suspense>
28
    </>
29
  );
30
}
31

32
const root = createRoot(document.getElementById('app'));
33

34
root.render(
35
  <ApolloProvider client={client}>
36
    <Suspense fallback={<div>Loading...</div>}>
37
      <App />
38
    </Suspense>
39
  </ApolloProvider>
40
);

我们开始加载数据，而不是等 React 渲染我们的 <App /> 组件。因为 preloadedQueryRef 传递到我们在 App 组件中的 useReadQuery，因此我们仍然享有挂起功能和相关缓存更新的好处。

ⓘ 注意

卸载包含预加载数据查询的组件是安全且释放 queryRef 的。当组件重新挂起时，useReadQuery 会自动重新订阅到 queryRef，并在任何时候发生的任何缓存更新都将立即读取，就像预先加载数据从未卸载过一样。

与数据加载路由结合使用

流行的路由器，如React Router和TanStack Router，提供了在路径组件渲染前加载数据的API。一个例子是来自ReactRouter的loader函数

在渲染路径组件之前加载数据，对于嵌套路由特别有用，可以实现数据加载的并行化。这可以防止父路径组件挂起并创建子路径组件的请求级联。

preloadQuery与这些routerAPI配合良好，因为它让您能够利用这些优化而不牺牲在路径组件中重新渲染缓存更新的能力。

让我们用React Router的loader函数更新我们的示例，在进入我们的路径时开始加载数据。

1
import { useLoaderData } from 'react-router-dom';
2

3
export function loader() {
4
  return preloadQuery(GET_DOGS_QUERY);
5
}
6

7
export function RouteComponent() {
8
  const queryRef = useLoaderData();
9
  const { data } = useReadQuery(queryRef);
10

11
  return (
12
    // ...
13
  );
14
}

该loader函数在React Router版本6.4及以上版本中可用。

React Router调用loader函数，我们通过调用preloadQuery函数来开始加载GET_DOG_QUERY查询。由preloadQuery创建的queryRef从loader函数返回，这使得在路径组件中可访问。

当路径组件渲染时，我们从useLoaderData钩子中访问queryRef，然后将其传递给useReadQuery。我们获得了在路由生命周期早期加载数据的好处，并且路径组件维持了使用缓存更新重新渲染的能力。

ⓘ 注意

该preloadQuery函数仅与客户端路由一起使用。preloadQuery返回的queryRef无法在网络中进行序列化，因此无法与在服务器上获取数据的routers一起使用，例如Remix

在查询加载完成之前防止路径转换

默认情况下，preloadQuery的工作方式类似于一个延迟加载器: 路由立即过渡，并且试图通过useReadQuery读取数据的即将到来的页面会暂停，直到网络请求完成。

但如果我们想防止路由在数据完全加载前过渡怎么办？queryRef's toPromise方法提供了一个在网络请求完成时解决的承诺。这个承诺以queryRef自身解决，使得它易于与useLoaderData等钩子一起使用。

以下是一个示例

1
export async function loader() {
2
  const queryRef = await preloadQuery(GET_DOGS_QUERY).toPromise();
3

4
  return queryRef;
5
}
6

7
// You may also return the promise directly from loader.
8
// This is equivalent to the above.
9
export async function loader() {
10
  return preloadQuery(GET_DOGS_QUERY).toPromise();
11
}
12

13
export function RouteComponent() {
14
  const queryRef = useLoaderData();
15
  const { data } = useReadQuery(queryRef);
16

17
  // ...
18
}

这指示React Router在查询加载完成后才开始路由过渡。在承诺解决后进行路由过渡时，数据会立即渲染，无需在路由组件中显示加载回退。

为什么在`toPromise`中阻止访问`data`？

您可能想知道为什么我们不使用查询从查询加载数据来解析toPromise，而是解析queryRef自身。我们希望大家利用useReadQuery以避免错过查询的缓存更新。如果data可用，那么在loader函数中消费它并暴露给路由组件会很诱惑。这样做意味着您将错过缓存更新。

如果您需要在loader函数中访问原始查询数据，直接使用client.query()。

重新查询和分页

Apollo的 suspense 数据获取钩子返回用于通过refetch函数重新查询query数据和通过fetchMore函数获取数据额外页面的函数。

让我们更新我们的示例，增加重新查询品种的能力。我们从useBackgroundQuery返回的元组的第二个项目解构出refetch函数。我们将确保使用React的useTransition钩子显示一个挂起状态，让用户知道数据正在重新查询：

1
import { Suspense, useTransition } from "react";
2
import {
3
  useSuspenseQuery,
4
  useBackgroundQuery,
5
  useReadQuery,
6
  gql,
7
  TypedDocumentNode,
8
  QueryRef,
9
} from "@apollo/client";
10

11
function App() {
12
  const [isPending, startTransition] = useTransition();
13
  const [queryRef, { refetch }] = useBackgroundQuery(
14
    GET_BREEDS_QUERY
15
  );
16

17
  function handleRefetch() {
18
    startTransition(() => {
19
      refetch();
20
    });
21
  };
22

23
  return (
24
    <Suspense fallback={<div>Loading...</div>}>
25
      <Dog
26
        id="3"
27
        queryRef={queryRef}
28
        isPending={isPending}
29
        onRefetch={handleRefetch}
30
      />
31
    </Suspense>
32
  );
33
}
34

35
function Dog({
36
  id,
37
  queryRef,
38
  isPending,
39
  onRefetch,
40
}: DogProps) {
41
  const { data } = useSuspenseQuery(GET_DOG_QUERY, {
42
    variables: { id },
43
  });
44

45
  return (
46
    <>
47
      Name: {data.dog.name}
48
      <Suspense fallback={<div>Loading breeds...</div>}>
49
        <Breeds isPending={isPending} queryRef={queryRef} />
50
      </Suspense>
51
      <button onClick={onRefetch}>Refetch!</button>
52
    </>
53
  );
54
}
55

56
function Breeds({ queryRef, isPending }: BreedsProps) {
57
  const { data } = useReadQuery(queryRef);
58

59
  return data.breeds.map(({ characteristics }) =>
60
    characteristics.map((characteristic) => (
61
      <div
62
        style={{ opacity: isPending ? 0.5 : 1 }}
63
        key={characteristic}
64
      >
65
        {characteristic}
66
      </div>
67
    ))
68
  );
69
}

1
// ...
2
import {
3
  // ...
4
  useQueryRefHandlers,
5
} from "@apollo/client";
6

7
const queryRef = preloadQuery(GET_BREEDS_QUERY);
8

9
function App() {
10
  const [isPending, startTransition] = useTransition();
11
  const { refetch } = useQueryRefHandlers(queryRef);
12

13
  function handleRefetch() {
14
    startTransition(() => {
15
      refetch();
16
    });
17
  };
18

19
  return (
20
    <Suspense fallback={<div>Loading...</div>}>
21
      <Dog
22
        id="3"
23
        isPending={isPending}
24
        onRefetch={handleRefetch}
25
      />
26
    </Suspense>
27
  );
28
}
29

30
// ...

1
function App() {
2
  const [queryRef] = useBackgroundQuery(GET_BREEDS_QUERY);
3

4
  return (
5
    <Suspense fallback={<div>Loading...</div>}>
6
      <Dog id="3" queryRef={queryRef} />
7
    </Suspense>
8
  );
9
}
10

11
function Dog({ id, queryRef }: DogProps) {
12
  const { data } = useSuspenseQuery(GET_DOG_QUERY, {
13
    variables: { id },
14
  });
15
  const [isPending, startTransition] = useTransition();
16
  const { refetch } = useQueryRefHandlers(queryRef);
17

18
  function handleRefetch() {
19
    startTransition(() => {
20
      refetch();
21
    });
22
  };
23

24
  return (
25
    <>
26
      Name: {data.dog.name}
27
      <Suspense fallback={<div>Loading breeds...</div>}>
28
        <Breeds queryRef={queryRef} isPending={isPending} />
29
      </Suspense>
30
      <button onClick={handleRefetch}>Refetch!</button>
31
    </>
32
  );
33
}
34

35
// ...

ⓘ 注意

使用从 useQueryRefHandlers 返回的处理程序不会阻止您使用 query 代理钩子生成处理程序

使用 `queryKey` 区分查询

Apollo 客户端使用 query 和 variables 的组合来唯一标识在使用 Apollo 的 Suspense 数据获取钩子时每个查询。

如果您的应用程序渲染多个使用相同 query 和 variables 的组件，这可能会引起问题：多个钩子执行的查询共享相同的身份，导致它们 同时挂起，无论哪个组件启动或重新启动网络请求。

您可以使用 queryKey 选项来确保每个钩子都有一个唯一的身份。当提供 queryKey 时，Apollo 客户端将其用作钩子身份的一部分，加上其 query 和 variables。

更多信息，请参阅 useSuspenseQuery 或 useBackgroundQuery API 文档。

跳过悬停钩子

虽然 useSuspenseQuery 和 useBackgroundQuery 都有 skip 选项，但该选项仅用于易于将 useQuery 迁移，尽可能少地修改代码。它不应长期使用。

相反，您应使用 skipToken:

与 useSuspenseQuery 一起推荐的 skipToken 的使用方法

1
import { skipToken, useSuspenseQuery } from '@apollo/client';
2
const { data } = useSuspenseQuery(
3
  query,
4
  id ? { variables: { id } } : skipToken
5
);

与 useBackgroundQuery 一起推荐的 skipToken 的使用方法

1
import { skipToken, useBackgroundQuery } from '@apollo/client';
2
const [queryRef] = useBackgroundQuery(
3
  query,
4
  id ? { variables: { id } } : skipToken
5
);

突变

Suspense

使用 Apollo Client 与 React 18 Suspense 功能

使用 Suspense 获取数据

更改变量

无挂起状态更新状态

过渡期间的挂起UI显示

部分数据的渲染

错误处理

在错误旁边渲染部分数据

避免请求瀑布效应

关于性能的说明

响应用户交互进行获取
自3.9.0

在 React 之外启动查询
自3.9.0

与数据加载路由结合使用

在查询加载完成之前防止路径转换

为什么在`toPromise`中阻止访问`data`？

使用 `queryKey` 区分查询

跳过悬停钩子

React 服务器组件 (RSC)

与 Next.js 13 应用路由一起使用

在流式 SSR 过程中使用 `useBackgroundQuery` 进行获取数据时

错误处理

后续阅读

useSuspenseQuery API

useBackgroundQuery API

useLoadableQuery API

useQueryRefHandlers API

useReadQuery API

Suspense

使用 Apollo Client 与 React 18 Suspense 功能

在 React 之外启动查询自3.9.0

在 React 之外启动查询
自3.9.0