10月8日至10日，与我们相聚纽约市，学习关于GraphQL联邦和API平台工程的最新技巧、趋势和新闻。加入我们，在纽约市的GraphQL峰会2024
文档
免费开始
自从3.0.0

Hooks

Apollo Client react hooks API 参考

是ApolloProvider 组件

The ApolloProvider 组件利用 React 的 Context API 来使配置好的 Apollo Client 实例在整个 React 组件树中可用。此组件可以从 @apollo/client 包中直接导入。

import { ApolloProvider } from '@apollo/client';

属性

选项类型描述
clientApolloClient<TCache>一个 ApolloClient 实例。

示例

const client = new ApolloClient({
  cache: new InMemoryCache(),
  uri: "http://localhost:4000/graphql"
});


ReactDOM.render(
  <ApolloProvider client={client}>
    <MyRootComponent />
  </ApolloProvider>,
  document.getElementById('root'),
);

The ApolloConsumer 组件

直接访问配置的 Apollo 客户端 实例的一种方法是创建一个 ApolloConsumer 组件，并将一个渲染函数作为其子元素提供。渲染函数将使用您的 ApolloClient 实例作为其唯一的 参数 被调用。您可以将 ApolloConsumer 组件视为类似于来自 React Context API 的Consumer 组件。

示例

import { ApolloConsumer } from '@apollo/client';


function WithApolloClient() {
  return (
    <ApolloConsumer>
      {client => 'We have access to the client!' /* do stuff here */}
    </ApolloConsumer>
  );
}

useQuery
自从3.0.0

在 Apollo 应用程序中执行查询的钩子。

要在 React 组件中运行查询，请调用 useQuery 并将其传递给一个 查询 document。

当组件渲染时， useQuery 将从一个包含 Apollo Client 的对象中返回一个对象，其中包含 loading、error 和 data 属性，您可以使用这些属性来渲染 UI。

有关 查询 的更深入了解，请参阅该部分。

示例

import { gql, useQuery } from '@apollo/client';


const GET_GREETING = gql`
  query GetGreeting($language: String!) {
    greeting(language: $language) {
      message
    }
  }
`;


function Hello() {
  const { loading, error, data } = useQuery(GET_GREETING, {
    variables: { language: 'english' },
  });
  if (loading) return <p>Loading ...</p>;
  return <h1>Hello {data.greeting.message}!</h1>;
}

签名

function useQuery<TData, TVariables>(
  query: DocumentNode | TypedDocumentNode<TData, TVariables>,
  options?: QueryHookOptions<NoInfer<TData>, NoInfer<TVariables>>
): QueryResult<TData, TVariables>

(src/react/hooks/useQuery.ts)

参数

名称 / 类型
描述

查询

DocumentNode | TypedDocumentNode(<TData, TVariables>)

一个由 GraphQL 查询 document 解析成 AST 的gql。

options (可选)

QueryHookOptions(<NoInfer<TData>, NoInfer<TVariables>>)

用于控制查询执行的选项。

显示/隐藏子属性
操作选项

client (可选)

ApolloClient<any>

用于执行查询的 ApolloClient 实例。

默认情况下，使用通过上下文传递的实例，但您也可以在此提供不同的实例。

errorPolicy（可选）

ErrorPolicy

指定查询如何处理返回GraphQL错误和部分结果的响应。

有关详细信息，请参阅GraphQL错误策略。

默认值是none，这意味着查询结果包含错误详情，但不包含部分结果。

onCompleted（可选）

(数据: NoInfer<TData>) => void

当您的查询成功完成后没有错误（或者如果errorPolicy是ignore且返回了部分数据）时，将被调用的回调函数。

此函数接受查询的data结果。

onError（可选）

(错误: ApolloError) => void

当查询遇到一个或多个错误时（除非errorPolicy是ignore）将被调用的回调函数。

此函数接受一个包含networkError对象或graphQLErrors数组对象的ApolloError对象，具体取决于发生的错误。

skip（可选）

boolean

如果为true，则不执行查询。

默认值是false。

variables（可选）

NoInfer<TVariables>

一个包含查询执行所需所有GraphQL的对象。

对象中的每个键对应一个名称，该键的值对应变量值。

网络选项

context（可选）

DefaultContext

如果您正在使用Apollo Link，此对象是传递到您的链中的context对象的初始值。

notifyOnNetworkStatusChange（可选）

boolean

如果true，则在网络状态更改或发生网络错误时，与正在进行的查询关联的组件将重新渲染。

默认值是false。

pollInterval（可选）

number

指定查询轮询更新结果的时间间隔（以毫秒为单位）。

默认值是 0（无轮询）。

skipPollAttempt（可选）

() => boolean

每当轮询期间发生重试尝试时都会被调用的回调函数。如果函数返回 true，则跳过重试，直到下一个轮询间隔才会再次尝试。

ssr（可选）

boolean

将 false 传递以跳过在 服务器端渲染 期间执行查询。

缓存选项

fetchPolicy（可选）

WatchQueryFetchPolicy

指定查询在执行期间如何与 Apollo Client 缓存交互（例如，在向服务器发送请求之前是否检查缓存中的结果）。

有关详情，请参阅 设置获取策略。

默认值是 cache-first。

initialFetchPolicy（可选）

WatchQueryFetchPolicy

默认为 options.fetchPolicy 的初始值，但可以显式配置以指定观看 FetchPolicy，以便在变量更改时时恢复（除非 nextFetchPolicy 干预）。

nextFetchPolicy（可选）

WatchQueryFetchPolicy | （this: WatchQueryOptions, NoInfer>，currentFetchPolicy: WatchQueryFetchPolicy，context: NextFetchPolicyContext, NoInfer>) => WatchQueryFetchPolicy

指定在此查询完成后要使用的 FetchPolicy。

refetchWritePolicy（可选）

RefetchWritePolicy

指定 NetworkStatus.refetch 操作是否应将传入的字段数据与现有数据合并，或覆盖现有数据。覆盖可能是更好的选择，但合并是当前默认行为，以支持 Apollo Client 3.x 的向后兼容性。

returnPartialData（可选）

boolean

如果 true，在缓存不包含所有查询 的结果时，查询可以从缓存返回部分结果。

默认值是false。

其他

canonizeResults（可选）

boolean

⚠️ 已弃用

使用 canonizeResults 可能会导致内存泄漏，因此我们通常不推荐再使用此选项。Apollo Client 的未来版本将包含一个类似的功能，但不会有内存泄漏的风险。

在返回结果前是否对缓存结果进行统一化。统一化会花费更多时间，但可以加快未来的深度比较。默认为 false。

partialRefetch (可选)

boolean

⚠️ 已弃用

Apollo Client 3 中设置此选项是不必要的，多亏了更一致的应用 fetch 策略。这可能在未来的版本中移除。

如果 true，当查询结果检测为不完整时将导致查询重新获取。

默认值是false。

结果

查询结果对象
QueryResult<TData, TVariables>
显示/隐藏子属性
操作数据

data

TData | undefined

包含您好 GraphQL 查询完成后的结果的 对象。

如果 a 查询 有一个或多个错误，此值可能是 undefined（具体取决于查询的 errorPolicy）。

error (可选)

ApolloError

如果查询产生了一个或多个错误，此对象包含一个 graphQLErrors 数组或一个单独的 networkError。如果不是，此值是 undefined。

有关更多信息，请参阅 处理操作错误。

previousData (可选)

TData

包含此 查询 最近一次执行的 previous 的结果的 对象。

如果这是 查询 的首次执行，此值是 undefined。

variables

TVariables | undefined

包含为 查询 提供的 变量的 对象。

网络信息

called

boolean

如果 true，已执行相关的懒查询。

该字段仅存在于由 useLazyQuery 返回的结果对象中。

client

ApolloClient<any>

执行 查询的 Apollo Client 实例。这可能用于手动执行后续查询或将数据写入缓存。

loading

boolean

如果 true，则查询仍在进行中且尚未返回结果。

networkStatus

NetworkStatus

表示查询's关联请求的当前网络状态的一个数字。查看可能的值。

与notifyOnNetworkStatusChange选项一起使用。

辅助函数

fetchMore

<TFetchData = TData, TFetchVars extends OperationVariables = TVariables>(fetchMoreOptions: FetchMoreQueryOptions<TFetchVars, TFetchData> & { updateQuery?: (previousQueryResult: TData, options: { fetchMoreResult: TFetchData; variables: TFetchVars; }) => TData; }) => Promise<ApolloQueryResult<TFetchData>>

一个辅助函数，帮助你获取分页列表字段的下一组结果。

refetch

(variables?: Partial<TVariables>) => Promise<ApolloQueryResult<TData>>

一个函数，允许你重新执行查询，可以选择传递新的variables。

为了保证refetch执行网络请求，其fetchPolicy设置为network-only（除非原始查询的fetchPolicy是no-cache或cache-and-network，这也会保证一个网络请求）。

另请参阅重新查询。

startPolling

(pollInterval: number) => void

一个函数，指示查询在指定的间隔（以毫秒为单位）开始重新执行。

stopPolling

() => void

一个函数，在执行startPolling之前的调用后，指示查询停止轮询。

subscribeToMore

<TSubscriptionData = TData, TSubscriptionVariables extends OperationVariables = TVariables>(options: SubscribeToMoreOptions<TData, TSubscriptionVariables, TSubscriptionData>) => () => void

一个函数，允许你执行一个订阅，通常用来订阅查询中包含的特定字段。

此函数返回一个函数，您可以调用该函数来终止。

updateQuery

<TVars extends OperationVariables = TVariables>(mapFn: (previousQueryResult: TData, options: Pick<WatchQueryOptions<TVars, TData>, "variables">) => TData) => void

一个函数，使您能够在不执行后续 GraphQL 操作的情况下更新查询的缓存的结果。

有关更多信息，请参阅使用 updateQuery 和 updateFragment。

其他

observable

ObservableQuery＜TData, TVariables＞

此钩子使用的内部ObservableQuery 的引用。

errors（可选）

ReadonlyArray＜GraphQLFormattedError＞

⚠️ 已弃用

此属性将在 Apollo Client 的未来版本中删除。请改用error.graphQLErrors。

useLazyQuery
自从3.0.0

用于在 Apollo 应用程序中以命令方式执行查询的钩子，例如响应用户交互。

请参阅查询 - 使用 useLazyQuery 手动执行部分以进一步了解useLazyQuery。

示例

import { gql, useLazyQuery } from "@apollo/client";


const GET_GREETING = gql`
  query GetGreeting($language: String!) {
    greeting(language: $language) {
      message
    }
  }
`;


function Hello() {
  const [loadGreeting, { called, loading, data }] = useLazyQuery(
    GET_GREETING,
    { variables: { language: "english" } }
  );
  if (called && loading) return <p>Loading ...</p>
  if (!called) {
    return <button onClick={() => loadGreeting()}>Load greeting</button>
  }
  return <h1>Hello {data.greeting.message}!</h1>;
}

签名

function useLazyQuery<TData, TVariables>(
  query: DocumentNode | TypedDocumentNode<TData, TVariables>,
  options?: LazyQueryHookOptions<NoInfer<TData>, NoInfer<TVariables>>
): LazyQueryResultTuple<TData, TVariables>

(src/react/hooks/useLazyQuery.ts)

参数

名称 / 类型
描述

query

DocumentNode | TypedDocumentNode＜TData, TVariables＞

一个由 GraphQL 查询 document 解析成 AST 的gql。

options（可选）

LazyQueryHookOptions＜NoInfer＜TData＞, NoInfer＜TVariables＞>

查询执行的默认选项。

显示/隐藏子属性
操作选项

client (可选)

ApolloClient<any>

用于执行查询的 ApolloClient 实例。

默认情况下，使用通过上下文传递的实例，但您也可以在此提供不同的实例。

errorPolicy（可选）

ErrorPolicy

指定查询如何处理返回GraphQL错误和部分结果的响应。

有关详细信息，请参阅GraphQL错误策略。

默认值是none，这意味着查询结果包含错误详情，但不包含部分结果。

onCompleted（可选）

(数据: NoInfer<TData>) => void

当您的查询成功完成后没有错误（或者如果errorPolicy是ignore且返回了部分数据）时，将被调用的回调函数。

此函数接受查询的data结果。

onError（可选）

(错误: ApolloError) => void

当查询遇到一个或多个错误时（除非errorPolicy是ignore）将被调用的回调函数。

此函数接受一个包含networkError对象或graphQLErrors数组对象的ApolloError对象，具体取决于发生的错误。

variables（可选）

NoInfer<TVariables>

包含您的查询执行所需的全部 GraphQL 变量的对象。

对象中的每个键对应一个变量名称，该键的值对应于变量值。

网络选项

context（可选）

DefaultContext

如果您正在使用Apollo Link，此对象是传递到您的链中的context对象的初始值。

notifyOnNetworkStatusChange（可选）

boolean

如果true，则在网络状态更改或发生网络错误时，与正在进行的查询关联的组件将重新渲染。

默认值是false。

pollInterval（可选）

number

指定查询轮询更新结果的时间间隔（以毫秒为单位）。

默认值是 0（无轮询）。

skipPollAttempt（可选）

() => boolean

每当轮询期间发生重试尝试时都会被调用的回调函数。如果函数返回 true，则跳过重试，直到下一个轮询间隔才会再次尝试。

ssr（可选）

boolean

将 false 传递以跳过在 服务器端渲染 期间执行查询。

缓存选项

fetchPolicy（可选）

WatchQueryFetchPolicy

指定查询在执行期间如何与 Apollo Client 缓存交互（例如，在向服务器发送请求之前是否检查缓存中的结果）。

有关详情，请参阅 设置获取策略。

默认值是 cache-first。

initialFetchPolicy（可选）

WatchQueryFetchPolicy

默认为 options.fetchPolicy 的初始值，但可以显式配置，以指定 WatchQueryFetchPolicy，以便在变量更改时恢复到之前的状态（除非有 nextFetchPolicy干预）。

nextFetchPolicy（可选）

WatchQueryFetchPolicy | （this: WatchQueryOptions, NoInfer>，currentFetchPolicy: WatchQueryFetchPolicy，context: NextFetchPolicyContext, NoInfer>) => WatchQueryFetchPolicy

指定在此查询完成后要使用的 FetchPolicy。

refetchWritePolicy（可选）

RefetchWritePolicy

指定是否将NetworkStatus.refetch操作与现有数据合并字段数据，还是覆盖现有数据。

returnPartialData（可选）

boolean

如果为true，当缓存中未包含所有查询字段的结果时，查询可以返回缓存的局部结果。

默认值是false。

其他

canonizeResults（可选）

boolean

⚠️ 已弃用

使用 canonizeResults 可能会导致内存泄漏，因此我们通常不推荐再使用此选项。Apollo Client 的未来版本将包含一个类似的功能，但不会有内存泄漏的风险。

在返回结果前是否对缓存结果进行统一化。统一化会花费更多时间，但可以加快未来的深度比较。默认为 false。

partialRefetch (可选)

boolean

⚠️ 已弃用

Apollo Client 3 中设置此选项是不必要的，多亏了更一致的应用 fetch 策略。这可能在未来的版本中移除。

如果 true，当查询结果检测为不完整时将导致查询重新获取。

默认值是false。

结果

[execute: LazyQueryExecFunction<TData, TVariables>, result: QueryResult<TData, TVariables>]

两个值的元组

名称类型描述
execute(options?: LazyQueryHookOptions＜TVariables＞) => Promise＜LazyQueryResult＜TData, TVariables＞>可以触发的函数，用于执行挂起的查询。调用后，`useLazyQuery` 的行为与 `useQuery` 相同。`useLazyQuery` 函数返回一个承诺，当查询成功或失败时，该承诺将被解决。
结果QueryResult查询结果。更多详情请参阅 `useQuery` 钩子。
显示/隐藏子属性
操作数据

data

TData | undefined

包含您好 GraphQL 查询完成后的结果的 对象。

如果 a 查询 有一个或多个错误，此值可能是 undefined（具体取决于查询的 errorPolicy）。

error (可选)

ApolloError

如果查询产生了一个或多个错误，此对象包含一个 graphQLErrors 数组或一个单独的 networkError。如果不是，此值是 undefined。

有关更多信息，请参阅 处理操作错误。

previousData (可选)

TData

包含此 查询 最近一次执行的 previous 的结果的 对象。

如果这是 查询 的首次执行，此值是 undefined。

variables

TVariables | undefined

包含为 查询 提供的 变量的 对象。

网络信息

called

boolean

如果 true，已执行相关的懒查询。

该字段仅存在于由 useLazyQuery 返回的结果对象中。

client

ApolloClient<any>

执行 查询的 Apollo Client 实例。这可能用于手动执行后续查询或将数据写入缓存。

loading

boolean

如果 true，则查询仍在进行中且尚未返回结果。

networkStatus

NetworkStatus

表示查询's关联请求的当前网络状态的一个数字。查看可能的值。

与notifyOnNetworkStatusChange选项一起使用。

辅助函数

fetchMore

<TFetchData = TData, TFetchVars extends OperationVariables = TVariables>(fetchMoreOptions: FetchMoreQueryOptions<TFetchVars, TFetchData> & { updateQuery?: (previousQueryResult: TData, options: { fetchMoreResult: TFetchData; variables: TFetchVars; }) => TData; }) => Promise<ApolloQueryResult<TFetchData>>

一个辅助函数，帮助你获取分页列表字段的下一组结果。

refetch

(variables?: Partial<TVariables>) => Promise<ApolloQueryResult<TData>>

一个函数，允许你重新执行查询，可以选择传递新的variables。

为了保证refetch执行网络请求，其fetchPolicy设置为network-only（除非原始查询的fetchPolicy是no-cache或cache-and-network，这也会保证一个网络请求）。

另请参阅重新查询。

startPolling

(pollInterval: number) => void

一个函数，指示查询在指定的间隔（以毫秒为单位）开始重新执行。

stopPolling

() => void

一个函数，在执行startPolling之前的调用后，指示查询停止轮询。

subscribeToMore

<TSubscriptionData = TData, TSubscriptionVariables extends OperationVariables = TVariables>(options: SubscribeToMoreOptions<TData, TSubscriptionVariables, TSubscriptionData>) => () => void

一个函数，允许你执行一个订阅，通常用来订阅查询中包含的特定字段。

此函数返回另一个函数，您可以调用该函数来终止订阅。

updateQuery

<TVars extends OperationVariables = TVariables>(mapFn: (previousQueryResult: TData, options: Pick<WatchQueryOptions<TVars, TData>, "variables">) => TData) => void

一个函数，使您能够在不执行后续 GraphQL 操作的情况下更新查询的缓存的结果。

有关更多信息，请参阅使用 updateQuery 和 updateFragment。

其他

observable

ObservableQuery＜TData, TVariables＞

此钩子使用的内部ObservableQuery 的引用。

errors（可选）

ReadonlyArray＜GraphQLFormattedError＞

⚠️ 已弃用

此属性将在 Apollo Client 的未来版本中删除。请改用error.graphQLErrors。

useMutation
自从3.0.0

请参考突变部分以获取更深入的useMutation概述。

示例

import { gql, useMutation } from '@apollo/client';


const ADD_TODO = gql`
  mutation AddTodo($type: String!) {
    addTodo(type: $type) {
      id
      type
    }
  }
`;


function AddTodo() {
  let input;
  const [addTodo, { data }] = useMutation(ADD_TODO);


  return (
    <div>
      <form
        onSubmit={e => {
          e.preventDefault();
          addTodo({ variables: { type: input.value } });
          input.value = '';
        }}
      >
        <input
          ref={node => {
            input = node;
          }}
        />
        <button type="submit">Add Todo</button>
      </form>
    </div>
  );
}

签名

function useMutation<TData, TVariables, TContext, TCache>(
  mutation: DocumentNode | TypedDocumentNode<TData, TVariables>,
  options?: MutationHookOptions<NoInfer<TData>, NoInfer<TVariables>, TContext, TCache>
): MutationTuple<TData, TVariables, TContext, TCache>

(src/react/hooks/useMutation.ts)

参数

名称 / 类型
描述

mutation

DocumentNode | TypedDocumentNode

由gql解析为 AST 的 GraphQL文档。

options（可选）

MutationHookOptions>NoInfer, NoInfer, TContext, TCache>

控制突变如何执行的选项。

显示/隐藏子属性
操作选项

awaitRefetchQueries（可选）

boolean

如果true，确保所有包含在refetchQueries中的查询都在突变被视为完成之前完成。

默认值是false（查询异步重新获取）。

errorPolicy（可选）

ErrorPolicy

指定突变如何处理既返回 GraphQL 错误又返回部分结果的响应。

有关详细信息，请参阅GraphQL错误策略。

默认值是none，这意味着突变结果包含错误细节，但不包含部分结果。

ignoreResults（可选）

boolean

如果true，则不会使用突变的data属性更新突变的data属性。

默认值是false。

onCompleted（可选）

(data: NoInfer, clientOptions?: BaseMutationOptions) => void

当您的突变在没有错误的情况下成功完成（或如果errorPolicy是ignore并且返回部分数据）时调用的回调函数。

该函数接受突变的结果data以及传递给突变的任何选项。

onError（可选）

(error: ApolloError, clientOptions?: BaseMutationOptions) => void

当突变遇到至少一个错误时调用的回调函数（除非errorPolicy是ignore）。

此函数接受一个 ApolloError 对象，该对象包含一个 networkError 对象或一个 graphQLErrors 数组，具体取决于发生错误的内容，以及传递给 mutation 的任何选项。

onQueryUpdated (可选)

OnQueryUpdated<any>

拦截由于 mutation 更新缓存数据而更新的查询的可选回调，以及传递给 client.mutate 的任何指定在 refetchQueries: [...] 列表中的

从 onQueryUpdated 返回一个 Promise 将导致最终的 mutation Promise 等待返回的 Promise。返回 false 将导致查询被忽略。

refetchQueries (可选)

((result: FetchResult<NoInfer<TData>>) => InternalRefetchQueriesInclude) | InternalRefetchQueriesInclude

一个数组（或返回数组的函数）指定在 mutation 发生后你想重新查询哪些查询。

每个数组值可以是

  • 一个包含要执行 query 以及任何 variables 的对象

  • 一个表示要重新查询的 的字符串

variables（可选）

NoInfer<TVariables>

一个包含所有 GraphQL 变量，你的 mutation 需要来执行的对象。

对象中的每个键对应一个变量名称，该键的值对应于变量值。

网络选项

client (可选)

ApolloClient<object>

用于执行 mutation 的 ApolloClient 实例。

默认情况下，使用通过上下文传递的实例，但您也可以在此提供不同的实例。

context（可选）

TContext

如果您正在使用Apollo Link，此对象是传递到您的链中的context对象的初始值。

notifyOnNetworkStatusChange（可选）

boolean

如果为 true，则正在进行的 mutation 关联的组件在网络状态改变或发生网络错误时重新渲染。

默认值是false。

缓存选项

fetchPolicy（可选）

MutationFetchPolicy

如果 mutation 的结果不应写入 Apollo Client 缓存，请提供 no-cache。

默认值是 network-only（表示结果写入缓存）。

与查询不同， 不支持 除了 network-only 和 no-cache 之外的其他 fetch policies。

optimisticResponse (可选)

NoInfer<TData> | ((vars: NoInfer<TVariables>, { IGNORE }: { IGNORE: IgnoreModifier; }) => NoInfer<TData> | IgnoreModifier)

通过提供一个对象或回调函数，当在发生变化后调用，允许您返回乐观数据，并通过IGNORE哨兵对象，选择性地跳过更新，Apollo Client将这个临时（且可能不正确）的响应缓存在完成变更为止，从而实现更快速的用户界面更新。

有关更多信息，请参阅乐观变更加速结果。

update (可选)

MutationUpdaterFunction<NoInfer<TData>, NoInfer<TVariables>, TContext, TCache>

一个函数，用于变更完变更大后更新Apollo Client缓存。

有关更多信息，请参阅变更之后更新缓存。

其他

keepRootFields (可选)

boolean

为了避免保留来自变异root字段的敏感信息，Apollo Client v3.4+会在每个变更大完成后自动清除缓存中所有的ROOT_MUTATION字段。

updateQueries (可选)

MutationQueryReducersMap<NoInfer<TData>>

从MutationQueryReducersMap，它是从查询名称到变异查询还原器的映射。简而言之，这个映射定义了如何将变异结果整合到您应用程序正在监视的查询的当前结果中。

结果

[
  mutate: (options?: MutationFunctionOptions<TData, TVariables>) => Promise<FetchResult<TData>>,
  result: MutationResult<TData>
]
两个值的元组
名称类型描述
mutate( options?: MutationFunctionOptions<TData, TVariables> ) => Promise<FetchResult<TData>>
一个从您的用户触发变异的函数。您可以选择性地传递以下任何选项。
  • awaitRefetchQueries
  • context
  • fetchPolicy
  • onCompleted
  • onError
  • optimisticResponse
  • refetchQueries
  • onQueryUpdated
  • update
  • variables
  • client

您在这里传递的任何选项覆盖了您传递给useMutation的任何现有值。

变更函数返回一个解析为您的变更结果的承诺。

结果MutationResult<TData>变更的结果。
显示/隐藏子属性
其他

called

boolean

如果true，则已调用变更的mutate函数。

client

ApolloClient<object>

执行变更的Apollo Client实例。

可以用于手动执行后续或向缓存写入数据。

data（可选）

TData | null

从你的mutation返回的数据。如果ignoreResults设置为true，undefined。

error (可选)

ApolloError

如果mutation产生一个或多个错误，此对象包含graphQLErrors的数组或单个networkError。否则，此值undefined。

有关更多信息，请参阅 处理操作错误。

loading

boolean

如果true，则mutation当前正在进行中。

reset

() => void

一个你可以调用的函数，用于将mutation的结果重置为其初始、未调用的状态。

useSubscription
自从3.0.0

有关useSubscription更详细的概述，请参阅订阅部分。

请考虑使用 onData 而不是 useEffect

如果你想对传入的数据做出反应，请使用onData选项而不是useEffect。你在useEffect钩子内部进行的任何状态更新可能导致额外的重新渲染，而useEffect主要用于渲染的副作用，而不是作为事件处理函数。类似于onData的事件处理函数中的状态更新可能——根据React版本的不同——被批量处理并导致仅重新渲染一次。

考虑以下组件

export function Subscriptions() {
  const { data, error, loading } = useSubscription(query);
  const [accumulatedData, setAccumulatedData] = useState([]);


  useEffect(() => {
    setAccumulatedData((prev) => [...prev, data]);
  }, [data]);


  return (
    <>
      {loading && <p>Loading...</p>}
      {JSON.stringify(accumulatedData, undefined, 2)}
    </>
  );
}

在这里使用useEffect之后，我们可以重写该组件以使用useSubscription的选项对象中接受的onData回调函数：

export function Subscriptions() {
  const [accumulatedData, setAccumulatedData] = useState([]);
  const { data, error, loading } = useSubscription(
    query,
    {
      onData({ data }) {
        setAccumulatedData((prev) => [...prev, data])
      }
    }
  );


  return (
    <>
      {loading && <p>Loading...</p>}
      {JSON.stringify(accumulatedData, undefined, 2)}
    </>
  );
}

⚠️ 注意:在useSubscription选项中，onData功能在Apollo Client >= 3.7 版本中提供。在之前的版本中，等效选项名为onSubscriptionData。

现在，第一条消息将在组件重新渲染前被添加到accumulatedData数组中，因为_call_beforedata被调用。React 18 自动批量处理仍然有效，并导致仅重渲染一次，但使用onData，我们可以保证在组件挂载后收到的每条消息都添加到accumulatedData。

示例

const COMMENTS_SUBSCRIPTION = gql`
  subscription OnCommentAdded($repoFullName: String!) {
    commentAdded(repoFullName: $repoFullName) {
      id
      content
    }
  }
`;


function DontReadTheComments({ repoFullName }) {
  const {
    data: { commentAdded },
    loading,
  } = useSubscription(COMMENTS_SUBSCRIPTION, { variables: { repoFullName } });
  return <h4>New comment: {!loading && commentAdded.content}</h4>;
}

签名

function useSubscription<TData, TVariables>(
  subscription: DocumentNode | TypedDocumentNode<TData, TVariables>,
  options?: SubscriptionHookOptions<NoInfer<TData>, NoInfer<TVariables>>
): {
    restart(): void;
    loading: boolean;
    data?: TData | undefined;
    error?: ApolloError;
    variables?: TVariables | undefined;
}

(src/react/hooks/useSubscription.ts)

参数

名称 / 类型
描述

subscription

DocumentNode | TypedDocumentNode<TData, TVariables>

一个由gql解析为AST的GraphQL订阅文档。

options (optional)

SubscriptionHookOptions<NoInfer<TData>, NoInfer<TVariables>>

控制订阅执行的选项。

显示/隐藏子属性
其他

client (可选)

ApolloClient<object>

一个ApolloClient实例。默认情况下，useSubscription/Subscription通过上下文传递的客户端使用，但可以传入不同的客户端。

context（可选）

DefaultContext

组件和您的网络接口（）之间的共享上下文。

errorPolicy（可选）

ErrorPolicy

指定用于此操作ErrorPolicy。

extensions (optional)

Record＜string, any＞

组件和您的网络接口（Apollo Link）之间的共享上下文。

fetchPolicy（可选）

FetchPolicy

指定组件如何与Apollo缓存交互。有关详细信息，请参阅设置fetch策略。

ignoreResults（可选）

boolean

如果为true，则hook不会导致组件重新渲染。这对于您希望用onData和onError回调中的逻辑来控制组件的渲染非常有用。

在此hook有data时将其更改为true将重置data为undefined。

onComplete (optional)

自从3.7.0

() => void

允许注册一个回调函数，当useSubscription Hook /Subscription组件完成订阅时将触发。

onData (optional)

自从3.7.0

(options: OnDataOptions＜NoInfer＜TData＞＞) => any

允许注册一个回调函数，每当useSubscription Hook /Subscription组件接收到数据时将触发。回调options对象参数包括client中当前Apollo Client实例和接收到的订阅数据中的data。

onError（可选）

自从3.7.0

(错误: ApolloError) => void

允许注册一个回调函数，每当useSubscription Hook /Subscription组件收到错误时将触发。

shouldResubscribe (optional)

boolean | ((options: BaseSubscriptionOptions＜NoInfer＜TData＞, NoInfer＜TVariables＞＞) => boolean)

确定您的订阅在hook的输入（例如subscription或variables）更改时是否应取消订阅并重新订阅。

skip（可选）

boolean

确定当前subscription是否应跳过。如果，例如variables依赖于以前的查询并且尚未就绪，则非常有用。

variables（可选）

NoInfer<TVariables>

包含所有你的订阅需要执行

变量的对象

onSubscriptionComplete（可选）

() => void

⚠️ 已弃用

应使用 onComplete 代替

允许注册一个回调函数，当 useSubscription 钩子/ Subscription 组件完成订阅时被触发。

onSubscriptionData（可选）

(options: OnSubscriptionDataOptions>) => any

⚠️ 已弃用

应使用 onData 代替

允许注册一个回调函数，每次 useSubscription 钩子/ Subscription 组件接收到数据时都会被触发。回调函数 options 参数对象包括当前的 Apollo 客户端实例在 client 中，以及接收到的订阅数据在 subscriptionData 中。

结果

查询结果对象
{
    restart(): void;
    loading: boolean;
    data?: TData | undefined;
    error?: ApolloError;
    variables?: TVariables | undefined;
}

useApolloClient
自从3.0.0

示例

import { useApolloClient } from '@apollo/client';


function SomeComponent() {
  const client = useApolloClient();
  // `client` is now set to the `ApolloClient` instance being used by the
  // application (that was configured using something like `ApolloProvider`)
}

签名

function useApolloClient(
  override?: ApolloClient<object>
): ApolloClient<object>

(src/react/hooks/useApolloClient.ts)

参数

名称 / 类型
描述

override（可选）

ApolloClient

结果

应用程序正在使用的 ApolloClient 实例。
ApolloClient<object>

useReactiveVar
自从3.2.0

读取一个reactive variable的值，并在该变量值变化时重新渲染包含的组件。这允许反应变量在没有依赖于 useQuery 钩子的情况下触发更改。

示例

import { makeVar, useReactiveVar } from "@apollo/client";
export const cartItemsVar = makeVar([]);


export function Cart() {
  const cartItems = useReactiveVar(cartItemsVar);
  // ...
}

签名

function useReactiveVar<T>(
  rv: ReactiveVar<T>
): T

(src/react/hooks/useReactiveVar.ts)

参数

名称 / 类型
描述

rv

ReactiveVar

一个反应性变量。

显示/隐藏子属性
其他

attachCache

( cache: ApolloCache ) => this

forgetCache

( cache: ApolloCache ) => boolean

onNextChange

( listener: ReactiveListener ) => () => void

结果

反应性变量的当前值。
T

useFragment
自从3.8.0

useFragment 代表对 Apollo 客户端缓存的轻量级即时绑定，并使得 Apollo 客户端能够向个别组件发送非常具体的片段结果。此钩子返回缓存中当前包含的针对给定片段的始终是最新的视图。 useFragment 从不触发它自己的网络请求。

请注意，useQuery 钩子仍然是负责 以及在缓存（查看API参考）中填充数据的主要钩子。因此，通过 fragment 数据读取的组件仍订阅 查询数据的所有更改，但只有在对应 fragment 的特定数据更改时才接收更新。

注意：此钩子于 3.7.0 作为实验性功能引入，并在 3.8.0 中稳定。在 3.7.x 和 3.8.0-alpha.x 版本中，此钩子作为 useFragment_experimental 导出。自 3.8.0-beta.0 及以后版本起，从其命名导出中移除了 _experimental 后缀。

示例

要查看 useFragment 的示例，请参见 片段 页面。

函数签名

function useFragment<
  TData = any,
  TVars = OperationVariables
>({
  from: string | StoreObject | Reference;
  fragment: DocumentNode | TypedDocumentNode<TData, TVars>;
  fragmentName?: string;
  optimistic?: boolean;
  variables?: TVars;
  returnPartialData?: boolean;
}): UseFragmentResult<TData> {}

参数

选项

名称 /
类型		描述

操作选项

从

字符串 | StoreObject | Reference

必需。 包含一个 __typename 和主键字段（例如 id）的对象，用于标识从中检索片段的实体对象，或 { __ref: "..." } 引用，或 string ID（不常见）。

片段

DocumentNode

必需。 使用 gql 表达式模板将 GraphQL 片段文档解析为 AST。

片段名称

字符串

要调用的文档中定义的片段的名称。

必需 如果文档中包含多个片段，则是必需的；否则为可选。

乐观

boolean

如果为 true，则 readFragment 返回乐观结果。

默认值为 true。

variables

{ [key: string]: any }

包含您片段所需的所有 GraphQL 变量。

对象中的每个键对应一个变量名称，该键的值对应于变量值。

canonizeResults

boolean

⚠️ 已弃用: 使用 canonizeResults 可能导致内存泄漏，所以我们通常不推荐再使用此选项。Apollo Client 的未来版本将包含一个类似的功能，但没有内存泄漏的风险。

如果 true，从缓存中读取的返回结果对象将被 规范，这意味着深度相等的对象也将是 ===（字面上是相同的对象），允许更有效地比较过去/现在的结果。

默认值是false。

结果

名称 /
类型		描述

操作结果

data

TData

包含给定 GraphQL 摘要的 数据 的对象。

如果 a 查询 有一个或多个错误，此值可能是 undefined（具体取决于查询的 errorPolicy）。

完整

boolean

一个表示为摘要返回的数据是否完整的布尔值。当 false 时，missing 字段应解释哪些字段导致了不完整性。

missing

MissingTree

一个包含在摘要阅读过程中报告的所有 MissingFieldError 信息的树，树的分支指示在查询结果中的错误路径。

useSuspenseQuery
自从3.8.0

有关 useSuspenseQuery 的详细说明，请参阅 使用 Suspense 进行数据获取参考。

示例

import { Suspense } from 'react';
import { useSuspenseQuery } from '@apollo/client';


const listQuery = gql`
  query {
    list {
      id
    }
  }
`;


function App() {
  return (
    <Suspense fallback={<Spinner />}>
      <List />
    </Suspense>
  );
}


function List() {
  const { data } = useSuspenseQuery(listQuery);


  return (
    <ol>
      {data.list.map(item => <Item key={item.id} id={item.id}/>)}
    </ol>
  );
}

签名

function useSuspenseQuery<TData, TVariables>(
  query: DocumentNode,
  options?: SuspenseQueryHookOptions<TData, TVariables> | SkipToken,
): UseSuspenseQueryResult<TData, TVariables>

参数

查询

Param类型描述
查询(类型化)DocumentNodeA GraphQL 查询文档由 gql 解析成 AST。

选项

您可以将一个 SuspenseQueryHookOptions 对象传递给缇钩，也可以传递一个 skipToken，以防止 useSuspenseQuery 冒钩执行查询或挂起。

SuspenseQueryHookOptions

属性

名称 / 类型
描述

variables（可选）

TVariables

包含您的查询执行所需的全部 GraphQL 变量的对象。

对象中的每个键对应一个变量名称，该键的值对应于变量值。

errorPolicy（可选）

ErrorPolicy

指定查询如何处理返回GraphQL错误和部分结果的响应。

有关详细信息，请参阅GraphQL错误策略。

默认值是none，这意味着查询结果包含错误详情，但不包含部分结果。

skip（可选）

boolean

⚠️ 已弃用

我们建议使用 skipToken 替代 skip 选项，因为它更类型安全。

此选项已弃用，仅保留以简化从 useQuery迁移。它将在未来的版本中删除。

如果 true，则不执行查询。默认值为 false。

操作选项

client (可选)

ApolloClient<any>

用于执行查询的 ApolloClient 实例。

默认情况下，使用通过上下文传递的实例，但您也可以在此提供不同的实例。

queryKey（可选）

string | number | any[]

查询的 query 的唯一标识符。数组中的每个条目必须是一个稳定的标识符，以防止无限次获取。

当在多个组件中使用相同的查询和变量组合时，这很有用，否则组件可能会相互覆盖。这还可以用来强制查询重新评估。

网络选项

context（可选）

DefaultContext

如果您正在使用Apollo Link，此对象是传递到您的链中的context对象的初始值。

缓存选项

fetchPolicy（可选）

SuspenseQueryHookFetchPolicy

指定查询在执行期间如何与 Apollo Client 缓存交互（例如，在向服务器发送请求之前是否检查缓存中的结果）。

有关详情，请参阅 设置获取策略。

默认值是 cache-first。

refetchWritePolicy（可选）

RefetchWritePolicy

受监视的查询必须选择在重新获取时覆盖现有数据，通过在他们的 WatchQuery 选项中传递 refetchWritePolicy: "overwrite"。

The default value is "overwrite".

returnPartialData（可选）

boolean

如果为true，当缓存中未包含所有查询字段的结果时，查询可以返回缓存的局部结果。

默认值是false。

其他

canonizeResults（可选）

boolean

⚠️ 已弃用

使用 canonizeResults 可能会导致内存泄漏，因此我们通常不推荐再使用此选项。Apollo Client 的未来版本将包含一个类似的功能，但不会有内存泄漏的风险。

在返回结果前是否对缓存结果进行统一化。统一化会花费更多时间，但可以加快未来的深度比较。默认为 false。

结果

名称 /
类型		描述

操作结果

data

TData

包含您好 GraphQL 查询完成后的结果的 对象。

如果 a 查询 有一个或多个错误，此值可能是 undefined（具体取决于查询的 errorPolicy）。

error

ApolloError

如果查询产生了一个或多个错误，此对象包含一个 graphQLErrors 数组或一个单独的 networkError。如果不是，此值是 undefined。

当使用默认 errorPolicy 或一个 errorPolicy of none 时，可以忽略此属性。钩子将抛出错误而不是设置此属性。

networkStatus

NetworkStatus

表示查询's关联请求的当前网络状态的一个数字。查看可能的值。

Client

client

ApolloClient

执行查询的 Apollo Client 实例。

可以用来手动执行后续查询或将数据写入缓存。

辅助函数

refetch

(variables?: Partial<TVariables>) => Promise<ApolloQueryResult>

一个函数，允许你重新执行查询，可以选择传递新的variables。

为了保证refetch执行网络请求，其fetchPolicy设置为network-only（除非原始查询的fetchPolicy是no-cache或cache-and-network，这也会保证一个网络请求）。

调用此函数会使组件重新挂起，除非调用位置被startTransition.包裹

fetchMore

({ query?: 文档节点, variables?: TVariables, updateQuery: Function}) => Promise<Apollo查询结果>

一个帮助您获取分页列表字段下一组结果的函数。

调用此函数会使组件重新挂起，除非调用位置被startTransition.包裹

subscribeToMore

(options: { document: 文档节点, variables?: TVariables, updateQuery?: Function, onError?: Function}) => () => void

一个函数，可以用来执行订阅，通常用于订阅查询中包含的特定字段。

此函数返回另一个函数，您可以调用该函数来终止订阅。

useBackgroundQuery
自从3.8.0

有关useBackgroundQuery的详细说明，请参阅使用Suspense进行获取参考。

示例

import { Suspense } from 'react';
import {
  ApolloClient,
  InMemoryCache,
  useBackgroundQuery,
  useReadQuery,
} from '@apollo/client';


const query = gql`
  foo {
    bar
  }
`;


const client = new ApolloClient({
  uri: "http://localhost:4000/graphql",
  cache: new InMemoryCache()
});


function SuspenseFallback() {
  return <div>Loading...</div>;
}


function Child({ queryRef }) {
  const { data } = useReadQuery(queryRef);


  return <div>{data.foo.bar}</div>;
}


function Parent() {
  const [queryRef] = useBackgroundQuery(query);


  return (
    <Suspense fallback={<SuspenseFallback />}>
      <Child queryRef={queryRef} />
    </Suspense>
  );
}


function App() {
  return (
    <ApolloProvider client={client}>
      <Parent />
    </ApolloProvider>
  );
}

签名

function useBackgroundQuery<TData, TVariables>(
  query: DocumentNode | TypedDocumentNode<TData, TVariables>,
  options: BackgroundQueryHookOptions<TData, TVariables> | SkipToken,
): [
  // Will return `undefined` here if no query has been executed yet and the query
  // is currently skipped using `skipToken` or { skip: true }
  QueryRef<TData> | undefined,
  {
    fetchMore: FetchMoreFunction<TData, TVariables>;
    refetch: RefetchFunction<TData, TVariables>;
  }
]

参数

查询

Param类型描述
查询(类型化)DocumentNodeA GraphQL 查询文档由 gql 解析成 AST。

选项

您可以将BackgroundQueryHookOptions对象传递到hook中，也可以传递一个skipToken来防止useBackgroundQueryhook执行查询。

如果您尚未执行任何查询并且跳过了查询，hook将返回undefined而不是queryRef。

名称 /
类型		描述

操作选项

variables

{ [key: string]: any }

包含您的查询执行所需的全部 GraphQL 变量的对象。

对象中的每个键对应一个变量名称，该键的值对应于变量值。

errorPolicy

ErrorPolicy

指定查询如何处理返回GraphQL错误和部分结果的响应。

有关详细信息，请参阅GraphQL错误策略。

默认值为none，这会导致useReadQueryhook抛出错误。

网络选项

context

Record＜string, any＞

如果您正在使用Apollo Link，此对象是传递到您的链中的context对象的初始值。

canonizeResults

Boolean

⚠️ 已弃用: 使用 canonizeResults 可能导致内存泄漏，所以我们通常不推荐再使用此选项。Apollo Client 的未来版本将包含一个类似的功能，但没有内存泄漏的风险。

如果 true，从缓存中读取的返回结果对象将被 规范，这意味着深度相等的对象也将是 ===（字面上是相同的对象），允许更有效地比较过去/现在的结果。

默认值是false。

client

ApolloClient

用于执行查询的 ApolloClient 实例。

默认情况下，使用通过上下文传递的实例，但您也可以在此提供不同的实例。

缓存选项

fetchPolicy

SuspenseQueryHookFetchPolicy

指定查询在执行期间如何与 Apollo Client 缓存交互（例如，在向服务器发送请求之前是否检查缓存中的结果）。

有关详细信息，请参阅设置获取策略。此hook仅支持cache-first、network-only、no-cache和cache-and-network获取策略。

默认值是 cache-first。

returnPartialData

boolean

如果true，当缓存中不包含所有查询字段的部分结果时，查询可以返回部分结果。

默认值是false。

refetchWritePolicy

"merge" | "overwrite"

监控查询必须选择在重新查询时覆盖现有数据，通过在WatchQueryOptions中传递refetchWritePolicy: "overwrite"。

默认值为"overwrite"。

skip (已弃用)

boolean

如果 true，则不执行查询。默认值为 false。

此选项已弃用，仅为了简化从 useQuery 迁移而提供支持。它将在未来的版本中被移除。请使用 skipToken 取代 skip 选项，因为它更安全。

结果

名称 /
类型		描述

查询引用

queryRef

QueryRef

为了将由 query 调用 useBackgroundQuery 发起的连接到其数据使用的位置 - 可以通过查询和变量来唯一标识，也可以通过用户提供的可选的 queryKey 来标识 - 该钩子返回一个 queryRef，该 queryRef 可以稍后通过 useReadQuery 读取。

辅助函数

refetch

(variables?: Partial<TVariables>) => Promise<ApolloQueryResult>

一个函数，允许你重新执行查询，可以选择传递新的variables。

为了保证refetch执行网络请求，其fetchPolicy设置为network-only（除非原始查询的fetchPolicy是no-cache或cache-and-network，这也会保证一个网络请求）。

调用此函数会使组件重新挂起，除非调用位置被startTransition.包裹

fetchMore

({ query?: 文档节点, variables?: TVariables, updateQuery: Function}) => Promise<Apollo查询结果>

一个帮助您获取分页列表字段下一组结果的函数。

调用此函数会使组件重新挂起，除非调用位置被startTransition.包裹

useReadQuery
自从3.8.0

有关 useReadQuery 的详细信息，请参阅 使用 Suspense 进行获取参考。

示例

请参阅上面 useBackgroundQuery 部分的 示例。

签名

function useReadQuery<TData>(
  queryRef: QueryRef<TData>
): {
  data: TData;
  networkStatus: NetworkStatus;
  error: ApolloError | undefined;
} {}

参数

queryRef

Param类型描述
queryRefQueryRefqueryRef 是通过 useBackgroundQuery 生成的。

结果

名称 /
类型		描述

操作结果

data

TData

包含您好 GraphQL 查询完成后的结果的 对象。

如果 a 查询 有一个或多个错误，此值可能是 undefined（具体取决于查询的 errorPolicy）。

error

ApolloError

如果查询产生了一个或多个错误，此对象包含一个 graphQLErrors 数组或一个单独的 networkError。如果不是，此值是 undefined。

当使用默认 errorPolicy 或一个 errorPolicy of none 时，可以忽略此属性。钩子将抛出错误而不是设置此属性。

networkStatus

NetworkStatus

表示查询's关联请求的当前网络状态的一个数字。查看可能的值。

useLoadableQuery
自从3.9.0

一个用于强制加载数据的钩子，例如响应用户交互。

请参阅 Suspense - 对用户交互进行获取 部分，以了解更多关于 useLoadableQuery 的信息。

示例

import { gql, useLoadableQuery } from "@apollo/client";


const GET_GREETING = gql`
  query GetGreeting($language: String!) {
    greeting(language: $language) {
      message
    }
  }
`;


function App() {
  const [loadGreeting, queryRef] = useLoadableQuery(GET_GREETING);


  return (
    <>
      <button onClick={() => loadGreeting({ language: "english" })}>
        Load greeting
      </button>
      <Suspense fallback={<div>Loading...</div>}>
        {queryRef && <Hello queryRef={queryRef} />}
      </Suspense>
    </>
  );
}


function Hello({ queryRef }) {
  const { data } = useReadQuery(queryRef);


  return <div>{data.greeting.message}</div>;
}

签名

function useLoadableQuery<TData, TVariables>(
  query: DocumentNode | TypedDocumentNode<TData, TVariables>,
  options?: LoadableQueryHookOptions
): UseLoadableQueryResult<TData, TVariables>

(src/react/hooks/useLoadableQuery.ts)

参数

名称 / 类型
描述

查询

DocumentNode | TypedDocumentNode

一个由 GraphQL 查询 document 解析成 AST 的gql。

选项 (可选)

LoadableQueryHookOptions

用于控制查询执行的选项。

显示/隐藏子属性
操作选项

client (可选)

ApolloClient<any>

用于执行查询的 ApolloClient 实例。

默认情况下，使用通过上下文传递的实例，但您也可以在此提供不同的实例。

errorPolicy（可选）

ErrorPolicy

指定查询如何处理返回GraphQL错误和部分结果的响应。

有关详细信息，请参阅GraphQL错误策略。

默认值是none，这意味着查询结果包含错误详情，但不包含部分结果。

queryKey（可选）

string | number | any[]

查询的 query 的唯一标识符。数组中的每个条目必须是一个稳定的标识符，以防止无限次获取。

当在多个组件中使用相同的查询和变量组合时，这很有用，否则组件可能会相互覆盖。这还可以用来强制查询重新评估。

网络选项

context（可选）

DefaultContext

如果您正在使用Apollo Link，此对象是传递到您的链中的context对象的初始值。

缓存选项

fetchPolicy（可选）

LoadableQueryHookFetchPolicy

指定查询在执行期间如何与 Apollo Client 缓存交互（例如，在向服务器发送请求之前是否检查缓存中的结果）。

有关详情，请参阅 设置获取策略。

默认值是 cache-first。

refetchWritePolicy（可选）

RefetchWritePolicy

指定是否将NetworkStatus.refetch操作与现有数据合并字段数据，还是覆盖现有数据。

returnPartialData（可选）

boolean

如果为true，当缓存中未包含所有查询字段的结果时，查询可以返回缓存的局部结果。

默认值是false。

其他

canonizeResults（可选）

boolean

⚠️ 已弃用

使用 canonizeResults 可能会导致内存泄漏，因此我们通常不推荐再使用此选项。Apollo Client 的未来版本将包含一个类似的功能，但不会有内存泄漏的风险。

在返回结果前是否对缓存结果进行统一化。统一化会花费更多时间，但可以加快未来的深度比较。默认为 false。

结果

[
  loadQuery: LoadQueryFunction<TVariables>,
  queryRef: QueryRef<TData, TVariables> | null,
  {
    fetchMore: FetchMoreFunction<TData, TVariables>;
    refetch: RefetchFunction<TData, TVariables>;
    reset: ResetFunction;
  }
]
三个值的元组
名称类型描述
loadQueryLoadQueryFunction用于强制加载数据的函数。调用此函数将创建或更新由 useLoadableQuery 返回的 queryRef，该 queryRef 应传递给 useReadQuery。
queryRefQueryRef | nullqueryRef，由 useReadQuery 使用来读取查询结果。
显示/隐藏子属性
handlers{ fetchMore: FetchMoreFunction, refetch: RefetchFunction, reset: ResetFunction; }用于查询的附加处理程序，例如 refetch。

useQueryRefHandlers
自从3.9.0

一个React钩子，返回一个给定的 queryRef 的 refetch 和 fetchMore 函数。

这很有用，可以获取通过 createQueryPreloader 创建的 queryRef 的处理程序，或者在另一个组件中创建的 queryRef 产生的处理程序无法访问时。

示例

const MyComponent({ queryRef }) {
  const { refetch, fetchMore } = useQueryRefHandlers(queryRef);


  // ...
}

签名

function useQueryRefHandlers<TData, TVariables>(
  queryRef: QueryRef<TData, TVariables>
): UseQueryRefHandlersResult<TData, TVariables>

(src/react/hooks/useQueryRefHandlers.ts)

参数

名称 / 类型
描述

queryRef

QueryRef<TData, TVariables>

从 useBackgroundQuery、useLoadableQuery 或 createQueryPreloader 返回的 QueryRef。

显示/隐藏子属性

结果

UseQueryRefHandlersResult<TData, TVariables>
显示/隐藏子属性
其他

fetchMore

FetchMoreFunction<TData, TVariables>

一个辅助函数，帮助你获取分页列表字段的下一组结果。

refetch

RefetchFunction<TData, TVariables>

更新此可观察查询的 variables，并获取新的结果。在大多数情况下，该方法应优先于 setVariables。

subscribeToMore

SubscribeToMoreFunction<TData, TVariables>

一个函数，允许你执行一个订阅，通常用来订阅查询中包含的特定字段。

此函数返回另一个函数，您可以调用该函数来终止订阅。

skipToken
自从3.8.0

虽然 skipToken 本身不是一个 Hook，但它被设计用来与 useSuspenseQuery 和 useBackgroundQuery 一起使用。如果一个 skipToken 被传递到这些 Hook 中而不是 options 对象，则该 Hook 不会引起任何请求或挂起行为，同时保留最后的数据。

使用 useSuspenseQuery 的 skipToken 推荐用法
import { skipToken, useSuspenseQuery } from '@apollo/client';
const { data } = useSuspenseQuery(
  query,
  id ? { variables: { id } } : skipToken
);
使用 useBackgroundQuery 的 skipToken 推荐用法
import { skipToken, useBackgroundQuery } from '@apollo/client';
const [queryRef] = useBackgroundQuery(
  query,
  id ? { variables: { id } } : skipToken
);

注意：为什么我们推荐 skipToken 而不是 { skip: true }？

想象一下这个非常常见的场景：你想在你某个变量未设置时跳过查询。你可能会想写成这样：

const { data } = useSuspenseQuery(query, {
  variables: { id },
  skip: !id
});

但是在这种情况下，TypeScript 会抱怨

Type 'number | undefined' is not assignable to type 'number'.
      Type 'undefined' is not assignable to type 'number'.ts(2769)

为了解决这个问题，你必须告诉 TypeScript 忽略这样一个事实：id 可能是 undefined:

const { data } = useSuspenseQuery(query, {
  variables: { id: id! },
  skip: !id
});

或者，你也可以使用一些难以理解的自定义默认值

const { data } = useSuspenseQuery(query, {
  variables: { id: id || 0 },
  skip: !id
});

这两种解决方案的共同点：它们隐藏了一个潜在的 bug。如果你的 skip 逻辑在未来变得更复杂，你可能会不小心引入一个 bug，导致虽然 id 仍然是 undefined，但你的查询没有被跳过——TypeScript 不会警告你。

所以，我们推荐使用 skipToken，因为它将在不欺骗编译器或不使用难以理解的默认值的情况下工作：

const { data } = useSuspenseQuery(
  query,
  id ? { variables: { id } } : skipToken
);

在这种情况下，TypeScript 会明显地看出跳过与 variables 选项之间的直接联系——这样它就可以不使用不安全的方法。

上一页
可观察查询
下一页
预加载
评分文章评分在GitHub上编辑编辑论坛Discord

©2024Apollo Graph Inc.，商业行为名为Apollo GraphQL。

隐私政策

公司

资源

联系我们