useFetch

使用 SSR 友好的組合式函式從 API 端點獲取資料。

這個組合式函式為 useAsyncData 和 $fetch 提供了一個便捷的封裝。它根據 URL 和 fetch 選項自動生成一個鍵，為基於伺服器路由的請求 URL 提供型別提示，並推斷 API 響應型別。

useFetch 是一個組合式函式，旨在直接在 setup 函式、外掛或路由中介軟體中呼叫。它返回響應式組合式函式，並處理將響應新增到 Nuxt payload 中，以便在頁面 hydration 時，資料可以從伺服器傳遞到客戶端，而無需在客戶端重新獲取。

使用

app/pages/modules.vue

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

如果你使用的是自定義的 useFetch 封裝器，請不要在組合式函式中對其進行 await 操作，因為這可能會導致意外的行為。請遵循此食譜以獲取有關如何製作自定義非同步資料獲取器的更多資訊。

data、status 和 error 是 Vue ref，當在 <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
  },
})

響應式鍵和共享狀態

你可以使用計算 ref 或普通 ref 作為 URL，從而實現動態資料獲取，並在 URL 更改時自動更新

app/pages/[id].vue

<script setup lang="ts">
const route = useRoute()
const id = computed(() => route.params.id)

// When the route changes and id updates, the data will be automatically refetched
const { data: post } = await useFetch(() => `/api/posts/${id.value}`)
</script>

當在多個元件中使用相同的 URL 和選項呼叫 useFetch 時，它們將共享相同的 data、error 和 status ref。這確保了元件之間的一致性。

使用 useFetch 建立的鍵控狀態可以透過 useNuxtData 在整個 Nuxt 應用程式中檢索。

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

如果你遇到從 useFetch 解構的 data 變數返回字串而不是 JSON 解析物件的情況，請確保你的元件不包含諸如 import { useFetch } from '@vueuse/core 之類的匯入語句。

在文件 > 4 X > 入門 > 資料獲取中閱讀更多資訊。

響應式 Fetch 選項

Fetch 選項可以作為響應式提供，支援 computed、ref 和計算 getter。當響應式 fetch 選項更新時，它將觸發使用更新後的解析響應式值重新獲取。

const searchQuery = ref('initial')
const { data } = await useFetch('/api/search', {
  query: { q: searchQuery },
})
// triggers a refetch: /api/search?q=new%20search
searchQuery.value = 'new search'

如果需要，你可以使用 watch: false 停用此行為

const searchQuery = ref('initial')
const { data } = await useFetch('/api/search', {
  query: { q: searchQuery },
  watch: false,
})
// does not trigger a refetch
searchQuery.value = 'new search'

型別

簽名

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

type UseFetchOptions<DataT> = {
  key?: MaybeRefOrGetter<string>
  method?: MaybeRefOrGetter<string>
  query?: MaybeRefOrGetter<SearchParams>
  params?: MaybeRefOrGetter<SearchParams>
  body?: MaybeRefOrGetter<RequestInit['body'] | Record<string, any>>
  headers?: MaybeRefOrGetter<Record<string, string> | [key: string, value: string][] | Headers>
  baseURL?: MaybeRefOrGetter<string>
  server?: boolean
  lazy?: boolean
  immediate?: boolean
  getCachedData?: (key: string, nuxtApp: NuxtApp, ctx: AsyncDataRequestContext) => DataT | undefined
  deep?: boolean
  dedupe?: 'cancel' | 'defer'
  timeout?: number
  default?: () => DataT
  transform?: (input: DataT) => DataT | Promise<DataT>
  pick?: string[]
  $fetch?: typeof globalThis.$fetch
  watch?: MultiWatchSources | false
  timeout?: MaybeRefOrGetter<number>
}

type AsyncDataRequestContext = {
  /** The reason for this data request */
  cause: 'initial' | 'refresh:manual' | 'refresh:hook' | 'watch'
}

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

interface AsyncDataExecuteOptions {
  dedupe?: 'cancel' | 'defer'
  timeout?: number
  signal?: AbortSignal
}

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

引數

URL (string | Request | Ref<string | Request> | () => string | Request)：要獲取的 URL 或請求。可以是字串、Request 物件、Vue ref 或返回字串/Request 的函式。支援響應式動態端點。
options (object)：fetch 請求的配置。擴充套件unjs/ofetch選項和 AsyncDataOptions。所有選項都可以是靜態值、ref 或計算值。

選項	型別	預設	描述
`key`	`MaybeRefOrGetter<string>`	自動生成	用於去重處理的唯一鍵。如果未提供，則根據 URL 和選項生成。
`方法`	`MaybeRefOrGetter<string>`	`'GET'`	HTTP 請求方法。
`查詢`	`MaybeRefOrGetter<SearchParams>`	-	要新增到 URL 的查詢/搜尋引數。別名：`params`。
`引數`	`MaybeRefOrGetter<SearchParams>`	-	`query` 的別名。
`正文`	`MaybeRefOrGetter<RequestInit['body'] \| Record<string, any>>`	-	請求正文。物件會自動字串化。
`headers`	`MaybeRefOrGetter<Record<string, string> \| [key, value][] \| Headers>`	-	請求頭。
`baseURL`	`MaybeRefOrGetter<string>`	-	請求的基本 URL。
`timeout`	`MaybeRefOrGetter<number>`	-	終止請求的超時時間（毫秒）。
`快取`	`布林值 \| 字串`	-	快取控制。布林值停用快取，或使用 Fetch API 值：`default`、`no-store` 等。
`伺服器`	`boolean`	`true`	是否在伺服器端獲取。
`lazy`	`boolean`	`false`	如果為 true，則在路由載入後解析（不阻止導航）。
`immediate`	`boolean`	`true`	如果為 false，則阻止請求立即觸發。
`預設`	`() => DataT`	-	在非同步解析之前，`data` 預設值的工廠函式。
`timeout`	`number`	-	請求超時前等待的毫秒數（預設為 `undefined`，表示沒有超時）
`transform`	`(input: DataT) => DataT \| Promise<DataT>`	-	解析後轉換結果的函式。
`getCachedData`	`(key, nuxtApp, ctx) => DataT \| undefined`	-	返回快取資料的函式。預設值見下文。
`pick`	`string[]`	-	僅從結果中選取指定的鍵。
`watch`	`MultiWatchSources \| false`	-	要監視和自動重新整理的響應式源陣列。`false` 停用監視。
`deep`	`boolean`	`false`	以深層 ref 物件的形式返回資料。
`dedupe`	`'cancel' \| 'defer'`	`'cancel'`	避免同時多次獲取相同的鍵。
`$fetch`	`typeof globalThis.$fetch`	-	自定義 $fetch 實現。請參閱 Nuxt 中的自定義 useFetch

所有 fetch 選項都可以給定一個 computed 或 ref 值。這些值將被監視，如果它們更新，將自動使用任何新值發起新請求。

getCachedData 預設值

const getDefaultCachedData = (key, nuxtApp, ctx) => nuxtApp.isHydrating
  ? nuxtApp.payload.data[key]
  : nuxtApp.static.data[key]

這僅在 nuxt.config 中的 experimental.payloadExtraction 啟用時才快取資料。

返回值

名稱	型別	描述
`資料`	`Ref<DataT \| undefined>`	非同步獲取的結果。
`重新整理`	`(opts?: AsyncDataExecuteOptions) => Promise<void>`	手動重新整理資料的函式。預設情況下，Nuxt 會等待 `refresh` 完成才能再次執行。
`execute`	`(opts?: AsyncDataExecuteOptions) => Promise<void>`	`refresh` 的別名。
`error`	`Ref<ErrorT \| undefined>`	如果資料獲取失敗，則為錯誤物件。
`狀態`	`Ref<'idle' \| 'pending' \| 'success' \| 'error'>`	資料請求的狀態。可能的值見下文。
`清除`	`() => void`	將 `data` 重置為 `undefined`（如果提供了 `options.default()`，則為該值），將 `error` 重置為 `undefined`，將 `status` 設定為 `idle`，並取消所有待處理的請求。

狀態值

idle：請求尚未開始（例如，在伺服器渲染時設定了 { immediate: false } 或 { server: false }）
pending：請求正在進行中
success：請求成功完成
error：請求失敗

如果您尚未在伺服器端獲取資料（例如，使用 server: false），那麼資料將直到 hydration 完成後才會被獲取。這意味著即使您在客戶端 await useFetch，data 在 <script setup> 中仍將保持 null。

示例

在文件 > 4 X > 示例 > 高階 > 使用自定義 Fetch Composable 中閱讀並編輯即時示例。

在文件 > 4 X > 示例 > 功能 > 資料獲取中閱讀並編輯即時示例。

這有幫助嗎？

報告問題或在 GitHub 上編輯此頁面

useError

useError composable 返回正在處理的全域性 Nuxt 錯誤。

useHead

useHead 用於自定義 Nuxt 應用程式中單個頁面的 head 屬性。