类 InMemoryCache

API 参考

的InMemoryCacheApolloClient

在阅读关于单个方法的介绍之前，请参阅 Apollo Client 中的缓存。

`readQuery`

直接针对缓存执行 GraphQL 查询，并返回其结果（如果查询无法满足，则为 null）：

1
// Query a cached Todo object with id 5
2
const { todo } = cache.readQuery({
3
  query: gql`
4
    query ReadTodo {
5
      todo(id: 5) {
6
        id
7
        text
8
        completed
9
      }
10
    }
11
  `,
12
});

有关使用说明，请参阅与缓存数据交互：readQuery。

接受以下参数

名称 / 类型	描述
`options` `对象`	必需。提供了用于查询的配置选项，包括要实际执行的查询。以下列出了支持的字段。字段
`乐观` `布尔型`	如果`true`，`readQuery`会返回乐观结果。默认值为`false`.

选项

名称 / 类型	描述
`查询` `文档节点`	必需。要执行的GraphQL 查询，通过在`gql` 模板字面量中包装查询字符串来创建。
`变量` `对象`	查询需要的任何 GraphQL 变量名称和值的映射。
`id` `字符串`	查询所用的根`id`。默认值为`ROOT_QUERY`，这是根查询对象的ID。通过指定另一个缓存的对象的ID，可以在不遵守您模式支持查询的结构的情况下查询任意缓存的缓存数据。这使`readQuery`的行为类似于`readFragment`。
`canonizeResults` `布尔型`	⚠️ 已废弃：使用`canonizeResults`可能会导致内存泄漏，所以我们通常不推荐再使用此选项。Apollo Client的将来的版本将包含一个没有内存泄漏风险的功能。如果`true`，则从缓存中读取的结果对象将canonized，这意味着深度相等的对象也将是`===`（字面上相同的对象），这使得对过去/现在的结果进行比较更加高效。默认值为`false`.

签名

src/cache/core/cache.ts

1
readQuery<QueryType, TVariables = any>(
2
  options: DataProxy.Query<TVariables>,
3
  optimistic: boolean = false,
4
): QueryType | null

`writeQuery`

将数据写入缓存，形状为提供的GraphQL查询。返回写入对象的Reference或写入失败的undefined。

1
// Create or modify a cached Todo object with id 5
2
cache.writeQuery({
3
  query: gql`
4
    query ReadTodo($id: ID!) {
5
      todo(id: $id) {
6
        id
7
        text
8
        completed
9
      }
10
    }
11
  `,
12
  data: {
13
    todo: {
14
      __typename: 'Todo',
15
      id: 5,
16
      text: 'Buy grapes 🍇',
17
      completed: false
18
    },
19
  },
20
  variables: {
21
    id: 5
22
  }
23
});

有关使用说明，请参阅与缓存数据交互：writeQuery。

接受一个参数为options对象的函数。此对象支持的字段如下所述。

选项

名称 / 类型	描述
`查询` `文档节点`	必须。定义要写入的数据形状的GraphQL 查询。该查询由在`gql`模板字面量中包围查询字符串创建而成。
`数据` `对象`	必须。要写入缓存的数据。此对象的字段必须符合`query`指定的形状。
`变量` `对象`	需要由`query`依赖的GraphQL 变量名称和值的映射。
`id` `字符串`	使用`query`所需的根对象`id`。默认值为`ROOT_QUERY`，这是根查询对象的ID。通过指定另一个缓存的物体`id`，可以修改任意缓存的物品，无需符合架构的查询支持的形状。这允许`writeQuery`的行为类似于`writeFragment`。
`广播` `布尔型`	如果为`true`，则自动刷新至少依赖一个此调用修改的`字段`的所有活动查询。如果为`false`，则静默缓存更新的广播，防止自动查询刷新。默认值为`true`。
`覆盖` `布尔型`	如果为`true`，则在调用`merge`函数时忽略现有缓存数据，允许传入的数据替换现有数据，而无需警告数据丢失。默认值为`false`.

签名

src/cache/core/cache.ts

1
writeQuery<TData = any, TVariables = any>(
2
  options: Cache.WriteQueryOptions<TData, TVariables>,
3
): Reference | undefined

`更新查询`
自3.5

从提供的GraphQL 查询的形状中检索缓存数据后，然后根据提供的更新函数更新缓存数据。

返回更新后的结果或null（如果更新失败）。

1
// Fetches a Todo object with id 5 and flips its `completed` boolean
2
cache.updateQuery({ // options object
3
  query: gql`
4
    query ReadTodo($id: ID!) {
5
      todo(id: $id) {
6
        id
7
        text
8
        completed
9
      }
10
    }
11
  `,
12
  variables: {
13
    id: 5
14
  }
15
}, (data) => ({ // update function
16
  todo: {
17
    ...data.todo,
18
    completed: !data.todo.completed
19
  }
20
}));

接受一个options对象和一个更新函数作为参数（两者均列于下文）。

选项

名称 / 类型	描述
`查询` `文档节点`	必须。定义要获取的数据形状的GraphQL 查询。该查询由将查询字符串包围在`gql`模板字面量中创建而成。
`变量` `对象`	需要由`query`依赖的GraphQL 变量名称和值的映射。
`id` `字符串`	使用`query`所需的根对象`id`。默认值为`ROOT_QUERY`，这是根查询对象的ID。通过指定另一个缓存的物体`id`，可以修改任意缓存的物品，无需符合架构的查询支持的形状。这允许`updateQuery`的行为类似于`updateFragment`。
`广播` `布尔型`	如果为`true`，则自动刷新至少依赖一个此调用修改的一个字段的所有活动查询。如果为`false`，则静默缓存更新的广播，防止自动查询刷新。默认值为`true`。
`覆盖` `布尔型`	如果为`true`，则在调用`merge`函数时忽略现有缓存数据，允许传入的数据替换现有数据，而无需警告数据丢失。默认值为`false`.

`updateQuery` 更新函数

更新函数updateQuery接收一个查询的当前缓存值，并返回应替换该值的值（或者如果无需更改，则返回undefined）。

返回的值将自动传递到writeQuery，该函数会修改缓存数据。

请注意，update函数必须以不可变的方式计算新值。有关不可变更新的更多信息，请参阅React官方文档。

签名

src/cache/core/cache.ts

1
public updateQuery<TData = any, TVariables = any>(
2
  options: Cache.UpdateQueryOptions<TData, TVariables>,
3
  update: (data: TData | null) => TData | null | void,
4
): TData | null

`readFragment`

读取由提供的GraphQL片段：从缓存中读取数据。

1
const todo = cache.readFragment({
2
  id: '5', // The value of the to-do item's unique identifier
3
  fragment: gql`
4
    fragment MyTodo on Todo {
5
      id
6
      text
7
      completed
8
    }
9
  `,
10
});

返回请求的数据或null，如果缓存中不存在数据。

有关使用说明，请参阅与缓存数据交互：readFragment。

接受以下参数

名称 / 类型	描述
`options` `对象`	必需。提供配置选项，包括要使用的实际片段。支持的字段列在下表中。
`乐观` `布尔型`	如果`true`，`readFragment`返回乐观结果。默认值为`false`.

选项

名称 / 类型	描述
`id` `字符串`	必需。要读取片段的对象的ID。如果缓存中没有包含指定ID的对象，`readFragment`返回`null`。
`fragment` `文档节点`	必需。一个使用`gql`模板字符串标记创建的GraphQL文档，其中包含要读取的片段。如果文档包含多个片段，您还必须提供`fragmentName`来指定要使用哪个片段。
`fragmentName` `字符串`	在`fragment`文档中定义的片段的名称，要在调用中使用。如果`fragment`文档只包含一个片段，则无需提供此值。
`变量` `对象`	用于`fragment`的任何所需GraphQL变量名称和值。
`canonizeResults` `布尔型`	⚠️ 已废弃: 使用 `canonizeResults` 可能会导致内存泄漏，所以我们通常不再推荐使用此选项。Apollo Client 的未来版本将包含一个类似的功能，而不会有内存泄漏的风险。如果`true`，则从缓存中读取的结果对象将canonized，这意味着深度相等的对象也将是`===`（字面上相同的对象），这使得对过去/现在的结果进行比较更加高效。默认值为`false`.

签名

src/cache/core/cache.ts

1
readFragment<FragmentType, TVariables = any>(
2
  options: DataProxy.Fragment<TVariables>,
3
  optimistic: boolean = false,
4
): FragmentType | null

`writeFragment`

将数据以提供的 GraphQL 片段的形式写入缓存。返回写入对象的 Reference 或者在写入失败时返回 undefined。

1
client.writeFragment({
2
  id: 'Todo:5',
3
  fragment: gql`
4
    fragment MyTodo on Todo {
5
      completed
6
    }
7
  `,
8
  data: {
9
    completed: true,
10
  },
11
});

有关使用说明，请参阅交互缓存数据：writeFragment。

接受一个参数为options对象的函数。此对象支持的字段如下所述。

选项

名称 / 类型	描述
`id` `字符串`	必需。此调用以写入片段的缓存对象 ID。如果缓存不包含指定 ID 的对象，则 `writeFragment` 返回 `null`。
`fragment` `文档节点`	必需。使用 `gql` 模板字面标记创建的 GraphQL 文档，其中包含要写入的片段。如果文档包含多个片段，您还必须提供`fragmentName`来指定要使用哪个片段。
`数据` `对象`	必需。要写入缓存的 data。此对象的 fields 必须符合 `fragment` 定义的形状。
`fragmentName` `字符串`	在`fragment`文档中定义的片段的名称，要在调用中使用。如果`fragment`文档只包含一个片段，则无需提供此值。
`变量` `对象`	用于`fragment`的任何所需GraphQL变量名称和值。
`广播` `布尔型`	如果为`true`，则自动刷新至少依赖一个此调用修改的一个字段的所有活动查询。如果为`false`，则静默缓存更新的广播，防止自动查询刷新。默认值为`true`。
`覆盖` `布尔型`	如果为`true`，则在调用`merge`函数时忽略现有缓存数据，允许传入的数据替换现有数据，而无需警告数据丢失。默认值为`false`.

签名

src/cache/core/cache.ts

1
writeFragment<TData = any, TVariables = any>(
2
  options: Cache.WriteFragmentOptions<TData, TVariables>,
3
): Reference | undefined

`watchFragment`
自3.10.0

根据指定的选项监视片段的缓存存储，并返回一个 Observable。我们可以订阅此 Observable，并在缓存存储更改时通过观察者接收到更新结果。

你必须传入一个包含单个片段的 GraphQL document 或一个包含多个片段的 document，这些片段代表你要读取的内容。如果你传入一个包含多个片段的 document，那么你也必须指定一个 fragmentName。

签名

1
function watchFragment(
2
  options: WatchFragmentOptions<TFragmentData, TVariables>
3
): Observable<WatchFragmentResult<TFragmentData>>

参数

名称 / 类型

描述

options

WatchFragmentOptions<TFragmentData, TVariables>

一个类型为 WatchFragmentOptions 的对象，它允许缓存识别片段并且可以可选地指定是否响应乐观更新。

显示/隐藏子属性

必需选项

fragment

DocumentNode | TypedDocumentNode<TFragmentData, TVariables>

一个使用 gql 模板字面标记解析的 GraphQL 片段 document 到 AST 的片段。

from

StoreObject | Reference | string

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

缓存选项

fragmentName（可选）

string

在片段 document 中定义的片段名称。

如果片段 document 包含多个片段，则为必需，否则为可选。

optimistic（可选）

boolean

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

默认值为true。

variables（可选）

TVariables

任何变量，该 GraphQL 片段可能依赖于它们。

结果

1
Observable<WatchFragmentResult<TFragmentData>>

`updateFragment`
自3.5

从缓存中以提供的 GraphQL 片段形式检索数据，然后更新根据提供的更新函数。

返回更新后的结果或null（如果更新失败）。

1
// Fetches a Todo object with id 5 and sets its `completed` boolean to true
2
const todo = cache.updateFragment({ // options object
3
  id: '5', // The value of the to-do item's unique identifier
4
  fragment: gql`
5
    fragment MyTodo on Todo {
6
      completed
7
    }
8
  `,
9
}, (data) => ({ ...data, completed: true }) // update function
10
);

接受一个options对象和一个更新函数作为参数（两者均列于下文）。

选项

名称 / 类型	描述
`id` `字符串`	必需。要读取片段的对象的ID。如果缓存中没有指定 ID 的对象，`updateFragment` 返回 `null`。
`fragment` `文档节点`	必需。用于读取片段的`gql` 模板字面量标签创建的 GraphQL 文档。如果文档包含多个片段，您还必须提供`fragmentName`来指定要使用哪个片段。
`fragmentName` `字符串`	在`fragment`文档中定义的片段的名称，要在调用中使用。如果`fragment`文档只包含一个片段，则无需提供此值。
`变量` `对象`	用于`fragment`的任何所需GraphQL变量名称和值。
`广播` `布尔型`	如果为`true`，则自动刷新至少依赖一个此调用修改的一个字段的所有活动查询。如果为`false`，则静默缓存更新的广播，防止自动查询刷新。默认值为`true`。
`覆盖` `布尔型`	如果为`true`，则在调用`merge`函数时忽略现有缓存数据，允许传入的数据替换现有数据，而无需警告数据丢失。默认值为`false`.

`updateFragment` 更新函数

updateFragment的更新函数接受一个片段当前缓存值，并返回应替换它的值（或者undefined如果没有变化应进行）。

返回的值将自动传递给writeFragment，它修改缓存数据。

请注意，update函数必须以内敛的方式计算新值。您可以在React 文档中了解更多关于内敛更新的信息。

签名

src/cache/core/cache.ts

1
public updateFragment<TData = any, TVariables = any>(
2
  options: Cache.UpdateFragmentOptions<TData, TVariables>,
3
  update: (data: TData | null) => TData | null | void,
4
): TData | null

`identify`

为指定的缓存对象返回规范 ID。

您可以为此函数提供对象或此对象引用：

如果您提供对象，identify 返回基于字符串的对象 ID（例如，Car:1）。
如果您提供引用，identify 返回引用的 __ref ID 字符串。

有关使用说明，请参阅与缓存数据交互：标识缓存实体。

接受以下参数

名称 / 类型	描述
`object` `StoreObject`或`Reference`	必需。要获取规范 ID 的缓存对象（或对象引用）。

签名

src/cache/inmemory/inMemoryCache.ts

1
identify(object: StoreObject | Reference): string | undefined

`modify`

修改一个或多个缓存对象的字段值。必须为要修改的每个字段提供修改函数。修改函数接受缓存字段的当前值并返回应该替换它的值。

如果缓存修改成功返回 true，否则返回 false。

有关使用说明，请参阅使用 cache.modify。

接受一个参数为options对象的函数。此对象支持的字段如下所述。

选项

名称 / 类型	描述
`fields` `对象`	必需。一个映射，指定了对每个修改的缓存对象字段调用的修改器函数。见下面的修改器函数API。
`id` `string`	要修改的缓存对象的ID。默认值是`ROOT_QUERY`（根查询单例对象的ID）。
`乐观` `布尔型`	如果为`true`，则还会修改包含字段的可乐观缓存值。默认值为`false`.
`广播` `布尔型`	如果为`true`，则自动刷新至少依赖一个此调用修改的一个字段的所有活动查询。如果为`false`，则静默缓存更新的广播，防止自动查询刷新。默认值为`true`。

修改器函数API

修改器函数接受一个缓存字段的当前值，并返回替换它的值，或者返回DELETE哨兵对象来完全删除该字段。

传递给修改器函数的第一个参数是正在修改的字段的当前缓存值。

第二个参数是一个包含以下实用工具的帮助器对象

名称 / 类型	描述
`fieldName` `字符串`	正在修改的字段名称。
`storeFieldName` `字符串`	字段在内部使用的完整键，包括序列化键参数。
`readField` `函数`	读取修改器函数作为第一个参数传递的对象上其他字段的辅助函数。
`canRead` `函数`	返回`true`的辅助函数，对于非规范化`StoreObject`和非悬挂`Reference`。这表示readField(name, objOrRef)有可能工作。用于从列表中过滤悬挂引用很有用。
`isReference` `函数`	返回`true`的辅助函数，如果特定对象是缓存实体的引用。
`DELETE` `对象`	你可以从修改器函数中返回的哨兵对象来指示应该完全删除该字段。

签名

src/cache/inmemory/inMemoryCache.ts

1
modify(options: Cache.ModifyOptions): boolean

`gc`

执行缓存中不可达的规范化对象的垃圾回收。

1
cache.gc();

返回包含从缓存中移除的所有对象的ID的数组。

有关使用说明，请参阅cache.gc。

签名

src/cache/inmemory/inMemoryCache.ts

1
gc()

`evict`

要么从缓存中删除规范化对象，要么从缓存中的规范化对象中删除特定字段：

1
cache.evict({ id: 'my-object-id', fieldName: 'myFieldName' });

如果从缓存中删除了数据，返回true，否则返回false。

有关使用说明，请参阅cache.evict。

接受一个参数为options对象的函数。此对象支持的字段如下所述。

选项

名称 / 类型	描述
`id` `字符串`	要删除的缓存对象ID（或从缓存中删除字段）。默认值为`ROOT_QUERY`，这是根查询对象的ID。
`fieldName` `字符串`	从缓存对象中删除的字段名称。如果要从对象中删除整个对象，则省略此选项。
`args` `Record<string, any>`	如果与`fieldName`一起提供，则只从缓存中删除具有指定参数的字段实例。否则，将移除缓存的字段的所有实例。
`广播` `布尔型`	如果`true`，则自动刷新所有至少依赖一个被此调用移除的字段的有效查询。如果`false`，则静默缓存更新的广播并阻止自动查询刷新。默认值为`true`。

签名

src/cache/inmemory/inMemoryCache.ts

1
evict(options: Cache.EvictOptions): boolean

`提取`

返回缓存当前内容序列化的表示形式，作为NormalizedCacheObject。

接受以下参数

名称 / 类型	描述
`乐观` `布尔型`	如果`true`，将在序列化中包含乐观数据。默认值为`false`.

签名

src/cache/inmemory/inMemoryCache.ts

1
extract(optimistic: boolean = false): NormalizedCacheObject

`恢复`

从序列化的NormalizedCacheObject（例如extract返回的）中恢复缓存的状态。这将移除缓存中的所有现有数据。

返回被调用实例的InMemoryCache实例。

接受以下参数

名称 / 类型	描述
`数据` `NormalizedCacheObject`	必需。恢復缓存的序列化。

签名

src/cache/inmemory/inMemoryCache.ts

1
restore(data: NormalizedCacheObject): this

`makeVar`

创建一个具有可选初始值的响应式变量：

1
const cartItems = makeVar([]);

返回用于读取或修改变量值的响应式变量函数。

有关使用说明，请参阅响应式变量。

接受以下参数

名称 / 类型	描述
`值` Any	响应式变量的初始值。

签名

src/cache/inmemory/inMemoryCache.ts

1
makeVar<T>(value: T): ReactiveVar<T>

ApolloClient

ObservableQuery

类 InMemoryCache

API 参考

watchFragment自3.10.0

updateFragment自3.5

`watchFragment`
自3.10.0

`updateFragment`
自3.5