TanStack Query useQuery 的 enabled 用法與 TabItemFlyout 範例

版本說明 本文範例使用 @tanstack/react-query v5。 TanStack Query v4 與 v5 對載入狀態的命名有所不同。本文使用的 isPending、isFetching 與 isLoading 定義皆為 v5

TanStack Query 的 useQuery 預設會在 Component 掛載後自動執行查詢。

但有些資料並不需要一進畫面就取得，例如：

Modal 開啟後才需要的詳細資料
使用者登入後才能取得的會員資料
必要參數準備完成後才能查詢
Hover 到某個選單後，才需要載入子資料

這時可以使用 enabled 控制 Query 何時開始運作。

useQuery({
  queryKey: ['example'],
  queryFn: fetchExample,
  enabled: false,
});

當 enabled 為 false 時，Query 不會自動執行。

條件變成 true 後，TanStack Query 才會根據目前的快取狀態，決定是否發送請求。

實際情境：Hover TabItemFlyout

假設頁面上有多個 Tab，每個 Tab 都有自己的子項目。

需求如下：

Hover 到 TabItem 時顯示 Flyout
Active Tab 的子資料已經存在，不需要重新查詢
Hover 到非 Active Tab 時，才取得該 Tab 的子資料
再次 Hover 時，優先使用快取資料

如果一進頁面就查詢所有 Tab 的子資料，會產生許多不必要的 API Request。

這種情境很適合使用 enabled。

建立查詢 Hook

import { useQuery } from '@tanstack/react-query';

interface UseTabSinglesParams {
  laboratoryId: string;
  enabled: boolean;
}

export function useTabSingles({
  laboratoryId,
  enabled,
}: UseTabSinglesParams) {
  return useQuery({
    queryKey: ['laboratory', laboratoryId, 'singles'],
    queryFn: () => getLaboratorySingles(laboratoryId),
    enabled: enabled && Boolean(laboratoryId),
    staleTime: 5 * 60 * 1000,
  });
}

這裡的 Query 只有在兩個條件都成立時才會啟用：

enabled && Boolean(laboratoryId)

也就是：

外部條件允許查詢
laboratoryId 已經存在

這可以避免參數尚未準備完成時，送出無效請求。

在 TabItemFlyout 中使用

import { useState } from 'react';

interface TabItemFlyoutProps {
  laboratoryId: string;
  isActive: boolean;
}

export function TabItemFlyout({
  laboratoryId,
  isActive,
}: TabItemFlyoutProps) {
  const [isFlyoutOpen, setIsFlyoutOpen] = useState(false);

  const shouldFetchSingles =
    isFlyoutOpen && !isActive;

  const {
    data: remoteSingles,
    isLoading,
    isError,
  } = useTabSingles({
    laboratoryId,
    enabled: shouldFetchSingles,
  });

  const isInitialLoading =
    shouldFetchSingles &&
    isLoading;

  return (
    <div
      onMouseEnter={() => setIsFlyoutOpen(true)}
      onMouseLeave={() => setIsFlyoutOpen(false)}
    >
      <TabItem />

      {isFlyoutOpen && (
        <TabSingleFlyout
          singles={remoteSingles ?? []}
          isLoading={isInitialLoading}
          isError={isError}
        />
      )}
    </div>
  );
}

最重要的是這段：

const shouldFetchSingles =
  isFlyoutOpen && !isActive;

它表示：

Flyout 已經開啟，而且目前不是 Active Tab 時，才查詢遠端資料。

Active Tab 的資料通常已經由目前頁面取得，因此不需要再次請求。

enabled 變成 true 一定會重新 Fetch 嗎？

不一定。

假設設定如下：

useQuery({
  queryKey: ['laboratory', laboratoryId, 'singles'],
  queryFn: () => getLaboratorySingles(laboratoryId),
  enabled: shouldFetchSingles,
  staleTime: 5 * 60 * 1000,
});

第一次 Hover：

Cache 沒有資料→ enabled 變成 true→ 發送 API Request→ 結果存入 Cache

短時間內再次 Hover：

Cache 已有新鮮資料→ enabled 變成 true→ 直接使用 Cache→ 不重新發送請求

超過 staleTime 後再次 Hover：

Cache 資料已過期→ 使用既有 Cache→ 可能進行背景更新

因此，enabled 只是控制 Query 是否允許自動執行。

實際是否重新請求，仍然取決於：

Cache 是否有資料
資料是否已經 stale
staleTime
其他 refetch 設定

staleTime 為什麼重要？

TanStack Query 預設會把查詢結果視為 stale。

如果 Flyout 子資料不需要每次 Hover 都更新，可以設定：

staleTime: 5 * 60 * 1000

代表資料在 5 分鐘內會被視為新鮮資料。

操作	查詢行為
第一次 Hover	發送請求
5 分鐘內再次 Hover	使用 Cache，不重新請求
超過 5 分鐘再次 Hover	可能背景更新
Hover 不同 Tab	使用不同 Query Key 查詢

Query Key 必須包含 laboratoryId：

queryKey: ['laboratory', laboratoryId, 'singles']

這樣每個 Tab 才會有各自獨立的快取。

isPending, isFetching, isLoading

延遲查詢時，不能只看 isPending。

當 Query 尚未執行，而且 Cache 沒有資料時，即使 enabled 是 false，Query 仍可能是 pending 狀態。

因此第一次載入可以這樣判斷：

const isInitialLoading =
  shouldFetchSingles &&
  isLoading

狀態	意義
`isPending`	尚未成功取得過資料
`isFetching`	Query Function 正在執行
`isLoading` (等同 isLoading && isPending, 可參考v5 官方文件)	正在進行第一次載入

這可以避免 Flyout 尚未開啟時就顯示 Loading。

v5 官方文件: 連結

enabled 適合哪些情境？

等待必要參數

useQuery({
  queryKey: ['user', userId],
  queryFn: () => getUser(userId),
  enabled: Boolean(userId),
});

依賴前一個 Query

const userQuery = useQuery({
  queryKey: ['user', email],
  queryFn: () => getUserByEmail(email),
});

const projectsQuery = useQuery({
  queryKey: ['projects', userQuery.data?.id],
  queryFn: () => getProjects(userQuery.data!.id),
  enabled: Boolean(userQuery.data?.id),
});

介面開啟後才查詢

useQuery({
  queryKey: ['item-detail', itemId],
  queryFn: () => getItemDetail(itemId),
  enabled: isModalOpen,
});

登入後才能查詢

useQuery({
  queryKey: ['current-user'],
  queryFn: getCurrentUser,
  enabled: authStatus === 'authenticated',
});

常見錯誤

Query Key 沒有包含參數

錯誤：

useQuery({
  queryKey: ['singles'],
  queryFn: () => getLaboratorySingles(laboratoryId),
});

不同 Tab 會共用同一份 Cache，可能顯示錯誤資料。

正確：

useQuery({
  queryKey: ['laboratory', laboratoryId, 'singles'],
  queryFn: () => getLaboratorySingles(laboratoryId),
});

使用 useEffect 手動呼叫 refetch

不建議：

useEffect(() => {
  if (isFlyoutOpen) {
    refetch();
  }
}, [isFlyoutOpen, refetch]);

可以直接宣告 Query 的啟用條件：

useQuery({
  queryKey,
  queryFn,
  enabled: isFlyoutOpen,
});

這樣查詢條件會更清楚，也更符合 TanStack Query 的使用方式。

總結

enabled 適合用來描述：

當某個條件成立後，這筆 Query 才應該開始運作。

在 TabItemFlyout 的案例中：

const shouldFetchSingles =
  isFlyoutOpen &&
  !isActive &&
  Boolean(laboratoryId);

可以達成：

避免初始化時查詢全部 Tab
只在 Hover 非 Active Tab 時載入
依照 laboratoryId 分開快取
搭配 staleTime 避免重複請求
不需要使用 useEffect 手動控制查詢

可以把 enabled 理解成 Query 的閘門：

條件不成立→ Query 保持待命 條件成立→ 檢查 Cache 與 staleTime→ 必要時才發送請求

TanStack Query useQuery 的 enabled 用法與 TabItemFlyout 範例

介紹 TanStack Query useQuery 的 enabled 設定與實務應用：以 Hover TabItemFlyout 為例說明如何延遲查詢、利用快取與 staleTime 避免多餘的 API 請求，並示範常見錯誤與正確做法。

這篇文章有幫助嗎？

TanStack Query useQuery 的 enabled 用法與 TabItemFlyout 範例

介紹 TanStack Query useQuery 的 enabled 設定與實務應用：以 Hover TabItemFlyout 為例說明如何延遲查詢、利用快取與 staleTime 避免多餘的 API 請求，並示範常見錯誤與正確做法。

這篇文章有幫助嗎？

推薦文章

TanStack Query Devtools 教學：用視覺化工具看懂 Query、Cache 與 Mutation

Zustand Anti-patterns：哪些狀態不該放進 Store？

Next.js + TanStack Query 的 Cache 到底在快取什麼？一次搞懂三層快取

實際情境：Hover TabItemFlyout

建立查詢 Hook

在 TabItemFlyout 中使用

enabled 變成 true 一定會重新 Fetch 嗎？

staleTime 為什麼重要？

isPending, isFetching, isLoading

enabled 適合哪些情境？

等待必要參數

依賴前一個 Query

介面開啟後才查詢

登入後才能查詢

常見錯誤

Query Key 沒有包含參數

使用 useEffect 手動呼叫 refetch

總結

推薦文章

TanStack Query Devtools 教學：用視覺化工具看懂 Query、Cache 與 Mutation

Zustand Anti-patterns：哪些狀態不該放進 Store？

Next.js + TanStack Query 的 Cache 到底在快取什麼？一次搞懂三層快取