`useQuery` 是 `react-query` 库中的一个核心钩子（Hook），它用于从异步数据源（如 API 服务器）获取数据，并在 React 组件中管理这些数据的状态。`useQuery` 不仅提供了数据获取的功能，还内置了数据缓存、状态更新、错误处理和数据刷新等功能。这使得开发者能够更加方便地在应用中处理和展示异步数据。
### 基本用法
`useQuery` 需要至少两个参数：一个唯一的 `queryKey` 和一个 `queryFn`，其中 `queryFn` 是一个异步函数，用于获取数据。
```javascript
import { useQuery } from 'react-query';
function fetchUserData(userId) {
return fetch(`https://api.example.com/users/${userId}`).then(res => res.json());
}
function UserProfile({ userId }) {
const { data, error, isLoading } = useQuery(['user', userId], () => fetchUserData(userId));
if (isLoading) return <div>Loading...</div>;
if (error) return <div>An error occurred: {error.message}</div>;
return (
<div>
<h1>{data.name}</h1>
<p>Email: {data.email}</p>
</div>
);
}
```
### 参数详解
- **`queryKey`**：一个数组或字符串，用作查询的唯一标识符。如果查询依赖于某些变量（如用户 ID），这些变量应包含在 `queryKey` 中，以确保每个唯一的查询都有其对应的缓存。
- **`queryFn`**：一个返回 Promise 的函数，用于获取数据。当查询被触发时（组件挂载或 `queryKey` 改变时），`react-query` 会调用这个函数。
### 返回值
`useQuery` 返回一个对象，包含了多个字段和方法，用于管理查询状态：
- **`data`**：包含异步函数成功解析后的数据。
- **`error`**：如果查询函数抛出错误，此处会包含错误对象。
- **`isLoading`**：如果查询正在进行中（包括初始加载和后续的背景更新），则为 `true`。
- **`isError`**：如果查询出错，则为 `true`。
- **`isSuccess`**：如果查询成功且数据已经被设置，则为 `true`。
- **`refetch`**：一个函数，可以手动触发查询。
### 高级配置
`useQuery` 还接受一个可选的配置对象，允许你定制查询行为：
- **`enabled`**：布尔值，控制查询是否自动执行。如果设置为 `false`，则需要手动调用 `refetch` 来触发查询。
- **`initialData`**：在数据加载完成前显示的初始数据。
- **`onSuccess`**、**`onError`**：成功或失败时的回调函数。
- **`refetchOnWindowFocus`**：当窗口重新获得焦点时，是否自动重新获取数据（默认为 `true`）。
- **`retry`**：失败时重试的次数（默认为 3 次）。
### 使用场景
`useQuery` 非常适合于任何需要从服务器获取数据并展示的场景，尤其是当这些数据需要缓存、状态更新或频繁更新时。通过 `react-query` 的管理，可以大大简化状态管理的复杂性，让开发者专注于业务逻辑的实现。