`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` 的管理，可以大大簡化狀態管理的複雜性，讓開發者專注於業務邏輯的實現。