useFetch · Nuxt 組合式函式

此組合式函式為 useAsyncData 和 $fetch 提供了方便的包裝器。它會根據 URL 和提取選項自動產生金鑰，為基於伺服器路由的請求 URL 提供類型提示，並推斷 API 回應類型。

useFetch 是一個組合式函式，旨在直接在 setup 函式、外掛程式或路由中介軟體中呼叫。它會回傳響應式組合式函式，並處理將回應新增至 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。

您也可以使用 interceptors

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 的匯入陳述式。

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

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

在文件 > 開始使用 > 資料提取中閱讀更多內容。

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

參數

URL：要提取的 URL。
Options（擴展 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 值。這些值將被監看，並且在更新任何新值時自動發出新的請求。

Options（來自 useAsyncData）
- key：一個唯一的金鑰，以確保可以跨請求正確地對資料提取進行重複資料刪除，如果未提供，它將根據 URL 和提取選項自動產生
- server：是否在伺服器上提取資料（預設為 true）
- lazy：是否在載入路由後解析非同步函式，而不是封鎖用戶端導航（預設為 false）
- immediate：設定為 false 時，將防止請求立即觸發。（預設為 true）
- default：一個工廠函式，用於設定 data 的預設值，在非同步函式解析之前 - 與 lazy: true 或 immediate: false 選項一起使用時很有用
- transform：一個函式，可用於在解析後更改 handler 函式結果
- getCachedData：提供一個回傳快取資料的函式。null 或 undefined 回傳值將觸發提取。預設情況下，這是
```
const getDefaultCachedData = (key, nuxtApp) => nuxtApp.isHydrating 
  ? nuxtApp.payload.data[key] 
  : nuxtApp.static.data[key]
```
  僅當啟用 nuxt.config 的 experimental.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：當請求尚未開始時，例如
  - 當 execute 尚未被呼叫且設定了 { immediate: false } 時
  - 當在伺服器上呈現 HTML 且設定了 { server: false } 時
- 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 | undefined
  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 組合式函式回傳正在處理的全域 Nuxt 錯誤。

useHead

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