查询键

查询键

在其核心，TanStack Query 会根据查询键为您管理查询缓存。查询键在顶层必须是一个数组，并且可以像只有一个字符串的数组一样简单，也可以像包含许多字符串和嵌套对象的数组一样复杂。只要查询键可以使用 JSON.stringify 进行序列化，并且对于查询的数据是唯一的，您就可以使用它！

简单查询键

键的最简单形式是包含常量值的数组。此格式对于以下情况很有用：

通用列表/索引资源
非分层资源

tsx

// 待办事项列表
useQuery({ queryKey: ['todos'], ... })

// 其他任何东西，随便什么！
useQuery({ queryKey: ['something', 'special'], ... })

// 待办事项列表
useQuery({ queryKey: ['todos'], ... })

// 其他任何东西，随便什么！
useQuery({ queryKey: ['something', 'special'], ... })

带变量的数组键

当查询需要更多信息来唯一描述其数据时，您可以使用包含一个字符串和任意数量的可序列化对象的数组来描述它。这对于以下情况很有用：

分层或嵌套资源
- 通常传递 ID、索引或其他基元来唯一标识项目
带有附加参数的查询
- 通常传递一个包含附加选项的对象

tsx

// 单个待办事项
useQuery({ queryKey: ['todo', 5], ... })

// “预览”格式的单个待办事项
useQuery({ queryKey: ['todo', 5, { preview: true }], ...})

// “已完成”的待办事项列表
useQuery({ queryKey: ['todos', { type: 'done' }], ... })

// 单个待办事项
useQuery({ queryKey: ['todo', 5], ... })

// “预览”格式的单个待办事项
useQuery({ queryKey: ['todo', 5, { preview: true }], ...})

// “已完成”的待办事项列表
useQuery({ queryKey: ['todos', { type: 'done' }], ... })

查询键是确定性哈希的！

这意味着无论对象中键的顺序如何，以下所有查询都被视为相等：

tsx

useQuery({ queryKey: ['todos', { status, page }], ... })
useQuery({ queryKey: ['todos', { page, status }], ...})
useQuery({ queryKey: ['todos', { page, status, other: undefined }], ... })

useQuery({ queryKey: ['todos', { status, page }], ... })
useQuery({ queryKey: ['todos', { page, status }], ...})
useQuery({ queryKey: ['todos', { page, status, other: undefined }], ... })

但是，以下查询键不相等。数组项的顺序很重要！

tsx

useQuery({ queryKey: ['todos', status, page], ... })
useQuery({ queryKey: ['todos', page, status], ...})
useQuery({ queryKey: ['todos', undefined, page, status], ...})

useQuery({ queryKey: ['todos', status, page], ... })
useQuery({ queryKey: ['todos', page, status], ...})
useQuery({ queryKey: ['todos', undefined, page, status], ...})

如果您的查询函数依赖于变量，请将其包含在查询键中

由于查询键唯一地描述了它们正在获取的数据，因此它们应包含您在查询函数中使用的任何会更改的变量。例如：

tsx

function Todos({ todoId }) {
  const result = useQuery({
    queryKey: ['todos', todoId],
    queryFn: () => fetchTodoById(todoId),
  })
}

function Todos({ todoId }) {
  const result = useQuery({
    queryKey: ['todos', todoId],
    queryFn: () => fetchTodoById(todoId),
  })
}

请注意，查询键充当查询函数的依赖项。将依赖变量添加到查询键将确保查询被独立缓存，并且每当变量更改时，查询将自动重新获取（取决于您的 staleTime 设置）。有关更多信息和示例，请参阅详尽依赖项部分。

简单查询键

带变量的数组键

查询键是确定性哈希的！

如果您的查询函数依赖于变量，请将其包含在查询键中

推荐阅读