查询
查询基础
查询是对异步数据源的声明性依赖，它与一个唯一键相关联。查询可以与任何基于 Promise 的方法（包括 GET 和 POST 方法）一起使用以从服务器获取数据。如果您的方法修改服务器上的数据，我们建议改用变更。
要订阅组件或自定义钩子中的查询，请至少使用以下内容调用 useQuery 钩子：
- 查询的唯一键
- 一个返回 Promise 的函数，该 Promise：
- 解析数据，或
- 抛出错误
tsx
import { useQuery } from '@tanstack/react-query'
function App() {
const info = useQuery({ queryKey: ['todos'], queryFn: fetchTodoList })
}
import { useQuery } from '@tanstack/react-query'
function App() {
const info = useQuery({ queryKey: ['todos'], queryFn: fetchTodoList })
}
您提供的唯一键在内部用于在整个应用程序中重新获取、缓存和共享您的查询。
useQuery 返回的查询结果包含您模板化和任何其他数据用法所需的所有查询信息：
tsx
const result = useQuery({ queryKey: ['todos'], queryFn: fetchTodoList })
const result = useQuery({ queryKey: ['todos'], queryFn: fetchTodoList })
result 对象包含一些您需要了解才能高效工作的重要状态。在任何给定时刻，查询只能处于以下状态之一：
- isPending 或 status === 'pending' - 查询尚无数据
- isError 或 status === 'error' - 查询遇到错误
- isSuccess 或 status === 'success' - 查询成功并且数据可用
除了这些主要状态之外，根据查询的状态还可以��用更多信息：
- error - 如果查询处于 isError 状态，则可通过 error 属性获取错误。
- data - 如果查询处于 isSuccess 状态，则可通过 data 属性获取数据。
- isFetching - 在任何状态下，如果查询正在随时获取（包括后台重新获取），则 isFetching 将为 true。
对于大多数查询，通常足以检查 isPending 状态，然后是 isError 状态，最后假设数据可用并呈现成功状态：
tsx
function Todos() {
const { isPending, isError, data, error } = useQuery({
queryKey: ['todos'],
queryFn: fetchTodoList,
})
if (isPending) {
return <span>加载中...</span>
}
if (isError) {
return <span>错误：{error.message}</span>
}
// 此时我们可以假设 `isSuccess === true`
return (
<ul>
{data.map((todo) => (
<li key={todo.id}>{todo.title}</li>
))}
</ul>
)
}
function Todos() {
const { isPending, isError, data, error } = useQuery({
queryKey: ['todos'],
queryFn: fetchTodoList,
})
if (isPending) {
return <span>加载中...</span>
}
if (isError) {
return <span>错误：{error.message}</span>
}
// 此时我们可以假设 `isSuccess === true`
return (
<ul>
{data.map((todo) => (
<li key={todo.id}>{todo.title}</li>
))}
</ul>
)
}
如果布尔值不是您的菜，您也可以使用 status 状态：
tsx
function Todos() {
const { status, data, error } = useQuery({
queryKey: ['todos'],
queryFn: fetchTodoList,
})
if (status === 'pending') {
return <span>加载中...</span>
}
if (status === 'error') {
return <span>错误：{error.message}</span>
}
// 也是 status === 'success'，但“else”逻辑也有效
return (
<ul>
{data.map((todo) => (
<li key={todo.id}>{todo.title}</li>
))}
</ul>
)
}
function Todos() {
const { status, data, error } = useQuery({
queryKey: ['todos'],
queryFn: fetchTodoList,
})
if (status === 'pending') {
return <span>加载中...</span>
}
if (status === 'error') {
return <span>错误：{error.message}</span>
}
// 也是 status === 'success'，但“else”逻辑也有效
return (
<ul>
{data.map((todo) => (
<li key={todo.id}>{todo.title}</li>
))}
</ul>
)
}
如果您在访问 data 之前检查了 pending 和 error，TypeScript 也会正确地缩小 data 的类型。
FetchStatus
除了 status 字段之外，您还将获得一个额外的 fetchStatus 属性，其中包含以下选项：
- fetchStatus === 'fetching' - 查询当前正在获取。
- fetchStatus === 'paused' - 查询想要获取，但已暂停。有关更多信息，请阅读网络模式指南。
- fetchStatus === 'idle' - 查询目前未执行任何操作。
为什么存在两种不同的状态？
后台重新获取和 stale-while-revalidate 逻辑使得 status 和 fetchStatus 的所有组合都成为可能。例如：
- 处于 success 状态的查询通常处于 idle fetchStatus，但如果正在进行后台重新获取，它也可能处于 fetching 状态。
- 挂载且没有数据的查询通常处于 pending 状态和 fetching fetchStatus，但如果网络连接中断，它也可能处于 paused 状态。
因此，请记住，查询可以处于 pending 状态而无需实际获取数据。经验法则是：
- status 提供有关 data 的信息：我们是否有数据？
- fetchStatus 提供有关 queryFn 的信息：它是否正在运行？
进一步阅读
有关执行状态检查的替代方法，请参阅社区资源。
