useFetch

源文件
从 API 端点获取数据，使用对 SSR 友好的组合式函数。

此组合式函数提供了对 useAsyncData 和 $fetch 的便捷封装。它根据 URL 和获取选项自动生成一个键，根据服务器路由提供请求 URL 的类型提示，并推断 API 响应类型。

useFetch 是一个旨在直接在 setup 函数、插件或路由中间件中调用的组合式函数。它返回响应式的组合式函数，并处理将响应添加到 Nuxt Payload 中，以便在服务器到客户端传递数据时，在客户端水合 (hydrate) 时无需重新获取数据。

使用

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。

你也可以使用拦截器 (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
  },
})

响应式键和共享状态

你可以使用 computed 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 > 入门 > 数据获取中阅读更多信息。

响应式获取选项

获取选项可以作为响应式提供，支持 computed, ref 和computed getters。当响应式获取选项更新时，它将使用更新后的解析响应式值触发重新获取。

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 的函数。支持 URL 的响应式，以实现动态端点。
  • options (对象): 获取请求的配置。扩展了unjs/ofetchoptions 和 AsyncDataOptions。所有选项都可以是静态值、ref 或 computed 值。它们将被 watch 并且在任何新值更新时自动触发新请求。
选项类型默认描述
keyMaybeRefOrGetter<string>自动生成用于去重的唯一键。如果未提供，则根据 URL 和选项生成。
methodMaybeRefOrGetter<string>'GET'HTTP 请求方法。
queryMaybeRefOrGetter<SearchParams>-要追加到 URL 的查询/搜索参数。别名：params。
paramsMaybeRefOrGetter<SearchParams>-query 的别名。
bodyMaybeRefOrGetter<RequestInit['body'] | Record<string, any>>-请求体。对象会自动字符串化。
headersMaybeRefOrGetter<Record<string, string> | [key, value][] | Headers>-请求头。
baseURLMaybeRefOrGetter<string>-请求的基础 URL。
timeoutMaybeRefOrGetter<number>-超时时间（毫秒），用于中止请求。
缓存boolean | string-缓存控制。布尔值禁用缓存，或使用 Fetch API 值：default, no-store 等。
服务器booleantrue是否在服务器上获取。
lazybooleanfalse如果为 true，则在路由加载后解析（不阻止导航）。
immediatebooleantrue如果为 false，则阻止请求立即发出。
默认() => DataT-在异步解析之前，为 data 设置默认值的工厂函数。
timeoutnumber-在请求超时前等待的毫秒数（默认为 undefined，表示没有超时）
transform(input: DataT) => DataT | Promise<DataT>-解析后转换结果的函数。
getCachedData(key, nuxtApp, ctx) => DataT | undefined-返回缓存数据的函数。参见下文了解默认值。
pickstring[]-只从结果中选取指定的键。
watchMultiWatchSources | false-要 watch 和自动刷新的响应式源数组。false 禁用 watch。
deepbooleanfalse以深度 ref 对象返回数据。
dedupe'cancel' | 'defer''cancel'避免同时获取相同的键。
$fetchtypeof globalThis.$fetch-自定义 $fetch 实现。请参阅 Nuxt 中的自定义 useFetch
所有获取选项都可以使用 computed 或 ref 值。这些将被 watch，并在任何新值更新时自动以新值触发新请求。

getCachedData 默认值

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

只有当 nuxt.config 中的 experimental.payloadExtraction 启用时，这才会缓存数据。

返回值

名称类型描述
dataRef<DataT | undefined>异步获取的结果。
refresh(opts?: AsyncDataExecuteOptions) => Promise<void>手动刷新数据的函数。默认情况下，Nuxt 会等到一个 refresh 完成后才能再次执行。
execute(opts?: AsyncDataExecuteOptions) => Promise<void>refresh 的别名。
errorRef<ErrorT | undefined>如果数据获取失败，返回的错误对象。
statusRef<'idle' | 'pending' | 'success' | 'error'>数据请求的状态。参见下文了解可能的值。
clear() => void将 data 重置为 undefined（如果提供了 options.default()，则为该值），将 error 重置为 undefined，将 status 设置为 idle，并取消任何挂起的请求。

状态值

  • idle: 请求尚未开始（例如 { immediate: false } 或服务器渲染时的 { server: false }）
  • pending: 请求进行中
  • success: 请求成功完成
  • error: 请求失败
如果你没有在服务器上获取数据（例如使用 server: false），那么在水合完成之前，数据不会被获取。这意味着即使你在客户端 await useFetch，data 在 <script setup> 中仍将保持 null。

示例

在 文档 > 4 X > 示例 > 高级 > 使用自定义获取组合式函数 中阅读和编辑实时示例。
在 文档 > 4 X > 示例 > 特性 > 数据获取 中阅读和编辑实时示例。