useFetch · Nuxt Composables

這個組合式函式提供一個方便的 useAsyncData 和 $fetch 包裝器。它會根據 URL 和擷取選項自動產生一個鍵值，為伺服器路由提供請求 URL 的類型提示，並推斷 API 回應類型。

useFetch 是一個組合式函式，旨在直接在設定函式、外掛程式或路由中介軟體中呼叫。它會傳回響應式組合式函式，並處理將回應新增至 Nuxt 載荷，以便它們可以從伺服器傳遞到用戶端，而無需在頁面水合時在用戶端重新擷取資料。

使用方式

pages/modules.vue

<script setup lang="ts">
const { data, status, error, refresh, clear } = await useFetch('/api/modules', {
  pick: ['title']
})
</script>

如果您正在使用自訂的 useFetch 包裝器，請勿在組合式函式中等待它，因為這可能會導致非預期的行為。請參閱此配方，以取得有關如何建立自訂非同步資料擷取器的更多資訊。

data、status 和 error 是 Vue refs，當在 <script setup> 中使用時，應該使用 .value 來存取，而 refresh/execute 和 clear 是普通的函式。

使用 query 選項，您可以將搜尋參數新增至您的查詢。此選項是從 unjs/ofetch 延伸而來，並使用 unjs/ufo 來建立 URL。物件會自動字串化。

const param1 = ref('value1')
const { data, status, error, refresh } = await useFetch('/api/modules', {
  query: { param1, param2: 'value2' }
})

上述範例會產生 https://api.nuxt.com/modules?param1=value1&param2=value2。

您也可以使用攔截器

const { data, status, error, refresh, clear } = await useFetch('/api/auth/login', {
  onRequest({ request, options }) {
    // Set the request headers
    // note that this relies on ofetch >= 1.4.0 - you may need to refresh your lockfile
    options.headers.set('Authorization', '...')
  },
  onRequestError({ request, options, error }) {
    // Handle the request errors
  },
  onResponse({ request, response, options }) {
    // Process the response data
    localStorage.setItem('token', response._data.token)
  },
  onResponseError({ request, response, options }) {
    // Handle the response errors
  }
})

useFetch 是一個保留的函式名稱，會由編譯器轉換，因此您不應該將自己的函式命名為 useFetch。

如果您遇到從 useFetch 解構的 data 變數傳回字串而不是 JSON 解析的物件，請確保您的元件不包含像 import { useFetch } from '@vueuse/core 這樣的 import 語句。

觀看 Alexander Lichter 的影片，以避免錯誤地使用 useFetch！

在文件 > 範例 > 進階 > 使用自訂 Fetch 組合式函式中讀取和編輯即時範例。

在文件 > 開始使用 > 資料擷取中閱讀更多資訊。

在文件 > 範例 > 功能 > 資料擷取中讀取和編輯即時範例。

參數

URL：要擷取的 URL。
選項 (延伸 unjs/ofetch 選項 & AsyncDataOptions)
- method：請求方法。
- query：使用 ufo 將查詢搜尋參數新增至 URL
- params：query 的別名
- body：請求主體 - 自動字串化（如果傳遞物件）。
- headers：請求標頭。
- baseURL：請求的基本 URL。
- timeout：自動中止請求的毫秒數
- cache：根據 Fetch API 處理快取控制
  - 您可以傳遞布林值來停用快取，或者您可以傳遞下列其中一個值：default、no-store、reload、no-cache、force-cache 和 only-if-cached。

所有擷取選項都可以給定 computed 或 ref 值。這些值將會被監看，並且如果更新，將會使用任何新值自動發出新請求。

選項 (來自 useAsyncData)
- key：一個唯一鍵，以確保資料擷取可以在請求之間正確地取消重複資料，如果未提供，它將根據 URL 和擷取選項自動產生
- server：是否在伺服器上擷取資料（預設為 true）
- lazy：是否在載入路由後解析非同步函式，而不是封鎖用戶端導覽（預設為 false）
- immediate：當設定為 false 時，將防止請求立即觸發。（預設為 true）
- default：一個工廠函式，用於設定 data 的預設值，在非同步函式解析之前 - 對於 lazy: true 或 immediate: false 選項很有用
- transform：一個函式，可用於在解析後修改 handler 函式結果
- getCachedData：提供一個傳回快取資料的函式。null 或 undefined 的傳回值將會觸發擷取。預設情況下，這是：key => nuxt.isHydrating ? nuxt.payload.data[key] : nuxt.static.data[key]，只有在啟用 payloadExtraction 時才會快取資料。
- pick：僅從 handler 函式結果中選擇此陣列中指定的鍵
- watch: 監看反應式來源陣列，並在它們變更時自動重新整理抓取結果。預設會監看抓取選項和 URL。您可以使用 watch: false 完全忽略反應式來源。搭配 immediate: false，這可以實現完全手動的 useFetch。（您可以在這裡看到使用 watch 的範例。）
- deep: 以深度 ref 物件的形式回傳資料（預設為 true）。可以設定為 false 以淺層 ref 物件的形式回傳資料，如果您的資料不需要深度反應式，這可以提高效能。
- dedupe: 避免同時多次抓取相同的鍵（預設為 cancel）。可能的選項有
  - cancel - 當發出新請求時，取消現有的請求
  - defer - 如果有待處理的請求，則完全不發出新請求

如果您提供函數或 ref 作為 url 參數，或者如果您提供函數作為 options 參數的引數，則 useFetch 呼叫將不會與程式碼庫中其他地方的 useFetch 呼叫匹配，即使選項看起來相同。如果您希望強制匹配，您可以在 options 中提供自己的鍵。

如果您使用 useFetch 在開發中呼叫具有自我簽署憑證的（外部）HTTPS URL，您需要在您的環境中設定 NODE_TLS_REJECT_UNAUTHORIZED=0。

了解如何使用 transform 和 getCachedData 來避免不必要的 API 呼叫，並為用戶端上的訪客快取資料。

回傳值

data: 傳入的非同步函數的結果。
refresh/execute: 一個可以用來重新整理 handler 函數回傳的資料的函數。
error: 如果資料抓取失敗，則為錯誤物件。
status: 一個字串，表示資料請求的狀態（"idle"、"pending"、"success"、"error"）。
clear: 一個將 data 設定為 undefined，將 error 設定為 null，將 status 設定為 'idle'，並將任何目前待處理的請求標記為已取消的函數。

預設情況下，Nuxt 會等到 refresh 完成後，才能再次執行。

如果您沒有在伺服器上抓取資料（例如，使用 server: false），則資料將不會被抓取，直到水合作用完成。這表示即使您在客戶端等待 useFetch，data 在 <script setup> 中仍將保持為 null。

類型

簽名

function useFetch<DataT, ErrorT>(
  url: string | Request | Ref<string | Request> | (() => string) | Request,
  options?: UseFetchOptions<DataT>
): Promise<AsyncData<DataT, ErrorT>>

type UseFetchOptions<DataT> = {
  key?: string
  method?: string
  query?: SearchParams
  params?: SearchParams
  body?: RequestInit['body'] | Record<string, any>
  headers?: Record<string, string> | [key: string, value: string][] | Headers
  baseURL?: string
  server?: boolean
  lazy?: boolean
  immediate?: boolean
  getCachedData?: (key: string, nuxtApp: NuxtApp) => DataT
  deep?: boolean
  dedupe?: 'cancel' | 'defer'
  default?: () => DataT
  transform?: (input: DataT) => DataT | Promise<DataT>
  pick?: string[]
  watch?: WatchSource[] | false
}

type AsyncData<DataT, ErrorT> = {
  data: Ref<DataT | null>
  refresh: (opts?: AsyncDataExecuteOptions) => Promise<void>
  execute: (opts?: AsyncDataExecuteOptions) => Promise<void>
  clear: () => void
  error: Ref<ErrorT | null>
  status: Ref<AsyncDataRequestStatus>
}

interface AsyncDataExecuteOptions {
  dedupe?: 'cancel' | 'defer'
}

type AsyncDataRequestStatus = 'idle' | 'pending' | 'success' | 'error'

useError

useError composable 回傳正在處理的 global Nuxt 錯誤。

useHead

useHead 可自訂您的 Nuxt 應用程式個別頁面的 head 屬性。