译零 TransZero · TanStack Query v4 中文文档
主站

查询的键值 Query Keys

React Query 在内部基于查询键值来管理查询缓存。 传递给 React Query 的查询键值必须是一个数组。 该数组可以是简单的仅有单个常量字符串的数组,也可以是包含许多嵌套对象及变量字符串的数组。 只要数组的内容是可序列化的,并且对查询的数据来说它是唯一的,那它就是合法的!

最简形式

键值最简单形式是一个带有单个常量字符串的数组。在以下情况,我们推荐你使用这种格式:

  • 通用的 List/Index 资源
  • 非分层的(Non-hierarchical)资源
TypeScript
1// A list of todos2useQuery({ queryKey: ['todos'], ... });3 4// Something else, whatever!5useQuery({ queryKey: ['something', 'special'], ... });

包含复杂对象的数组

当查询需要更多信息来唯一地描述其数据时,数组可以为带有任意数量字符串及可序列化对象的形式。这种形式对于以下情况很有用:

  • 分层或嵌套的资源
    • 通常需要传递 ID、索引或其他原语来唯一地标识该资源
  • 带有附加参数的查询
    • 通常需要传递一个作为附加信息的对象
TypeScript
1// An individual todo2useQuery({ queryKey: ['todo', 5], ... });3 4// An individual todo in a "preview" format5useQuery({ queryKey: ['todo', 5, { preview: true }], ...});6 7// A list of todos that are "done"8useQuery({ queryKey: ['todos', { type: 'done' }], ... });

查询键值的散列是确定的(hashed deterministically)!

这意味着,不管对象中键值的顺序如何,以下所有查询都被认为是相等的:

TypeScript
1useQuery({ queryKey: ['todos', { status, page }], ... });2useQuery({ queryKey: ['todos', { page, status }], ...});3useQuery({ queryKey: ['todos', { page, status, other: undefined }], ... });

但是,以下查询键值不相等。这些数组项的顺序很重要,因为它们的散列信息并不相同!

TypeScript
1useQuery({ queryKey: ['todos', status, page], ... });2useQuery({ queryKey: ['todos', page, status], ...});3useQuery({ queryKey: ['todos', undefined, page, status], ...});

如果你的查询功能依赖于变量,则将其包含在查询键值中

由于查询键值唯一地描述了需要获取的数据,因此它们应该包括所有那些在查询函数中使用到的需要更改的变量。例如:

TypeScript
1function Todos({ todoId }) {{2  const result = useQuery({3    queryKey: ['todos', todoId],4    queryFn: () => fetchTodoById(todoId),5  });6}

延伸阅读

如何在大型应用中正确的组织查询键值?请参阅社区博客(英文)及社区扩展库

本页为 TanStack Query 文档(React 版)的非官方中文翻译,原文由上游团队维护,遵循 MIT 许可。 译文如有偏差,以英文原文为准。

本页译文取自社区中文版 react-query-web-i18n(MIT),非本站翻译,已停止更新,内容可能与当前 API 有出入。

译自上游 (未记录版本)