Skip to main content

查询 Queries

查询基础​

查询是一种对于与唯一键值相关联的异步数据源的声明性依赖。 查询可以与任何基于 Promise 的方法（包括 GET 和 POST 方法）一起使用，以从服务器获取数据。 如果你的方法修改了服务器上的数据，建议你改用修改

要在你的组件或自定义 Hook 中订阅一个查询，至少需要以下的参数来调用useQueryHook：

  • 该查询的一个唯一的键值
  • 一个返回 Promise 的函数：
    • 解析数据，或
    • 抛出错误
import { useQuery } from "@tanstack/vue-query";

const result = useQuery({ queryKey: ["todos"], queryFn: fetchTodoList });

这个唯一键值将在内部用于重新获取数据、缓存和在整个程序中共享该查询信息。

useQuery返回的查询结果将包含所有关于该查询的信息，你可以用这些信息来进行排版和或数据驱动的任何动作：

const result = useQuery(["todos"], fetchTodoList);

result对象包含一些非常重要的状态，你需要注意这些状态才能提高工作效率。 在任何给定时刻，查询只能处于以下状态之一：

  • isLoading 或者 status === 'loading' - 查询暂时还没有数据
  • isError 或者 status === 'error' - 查询遇到一个错误
  • isSuccess 或者 status === 'success' - 查询成功，并且数据可用

除了这些主要状态之外，取决于具体查询的状态，还有更多信息可用：

  • error - 如果查询处于isError状态，则可以通过error属性获取该错误
  • data - 如果查询处于success状态，则可以通过data属性获得数据

对于大多数查询，通常先检查isLoading状态，然后检查isError状态，最后假设数据可用并呈现成功状态就足够了：

<script setup>
  import { useQuery } from "@tanstack/vue-query";

  const { isLoading, isError, data, error } = useQuery({
    queryKey: ["todos"],
    queryFn: fetchTodoList,
  });
</script>

<template>
  <span v-if="isLoading">Loading...</span>
  <span v-else-if="isError">Error: {{ error.message }}</span>
  <!-- We can assume by this point that `isSuccess === true` -->
  <ul v-else-if="data">
    <li v-for="todo in data" :key="todo.id">{{ todo.title }}</li>
  </ul>
</template>

如果你不喜欢布尔值，你也可以使用status查询状态：

<script setup>
  import { useQuery } from "@tanstack/vue-query";

  const { status, data, error } = useQuery({
    queryKey: ["todos"],
    queryFn: fetchTodoList,
  });
</script>

<template>
  <span v-if="status === 'loading'">Loading...</span>
  <span v-else-if="status === 'error'">Error: {{ error.message }}</span>
  <!-- also status === 'success', but "else" logic works, too -->
  <ul v-else-if="data">
    <li v-for="todo in data" :key="todo.id">{{ todo.title }}</li>
  </ul>
</template>

如果你在访问data之前检查了loading和error，TypeScript 也会正确缩窄data的类型。

FetchStatus​

除了status字段，result对象，还会有一个额外的fetchStatus属性，它有以下选项：

  • fetchStatus === 'fetching' - 正在查询中
  • fetchStatus === 'paused' - 查询想要获取，但它被暂停了。在网络模式中阅读更多相关信息
  • fetchStatus === 'idle' - 该查询处于闲置状态

为什么有两种表示状态的东西(status/fetchStatus)？​

后台刷新和数据过期重试(stale-while-revalidate)的逻辑使status和fetchStatus的所有组合成为了可能。比如说：

  • 一个state='success'的查询通常处于fetchStatus='idle'状态。但如果同时有后台重新获取动作，它也可能为fetchStatus='fetching'状态。
  • 一个没有数据的查询通常处于status='loading'状态和fetchStatus='loading状态。如果同时无网络连接，它也可能为fetchStatus='paused'状态。

所以请记住，一个查询可以处于fetchStatus='loading'状态，但没有实际的在获取数据。 如何理清两者关系？这里有一个简单的经验法则：

  • status告诉我们有关data的状态：有或者没有？
  • fetchStatus告诉我们有关queryFn的状态：在执行还是没在执行？