useFetch

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

使用

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

使用 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 }) {
    // 设置请求头
    // 请注意，这依赖于 ofetch >= 1.4.0 - 你可能需要刷新你的锁定文件。
    options.headers.set('Authorization', '...')
  },
  onRequestError({ request, options, error }) {
    // 处理请求错误
  },
  onResponse({ request, response, options }) {
    // 处理响应数据
    localStorage.setItem('token', response._data.token)
  },
  onResponseError({ request, response, options }) {
    // 处理响应错误
  }
})

参数

• 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。

• Options (来自 useAsyncData):
  • key: 一个唯一的键，以确保数据获取可以跨请求正确地去重，如果不提供，它将根据 URL 和获取选项自动生成。
  • server: 是否在服务器上获取数据（默认为 true）。
  • lazy: 是否在加载路由后解析异步函数，而不是阻塞客户端的导航（默认为 false）。
  • immediate: 当设置为 false 时，将阻止请求立即发起。（默认为 true）。
  • default: 一个工厂函数，用于设置异步函数解决之前 data 的默认值。当 lazy: true 或 immediate: false 时，这个选项非常有用。（您可以在这里看到使用 watch 的一个例子）
  • 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。
  • deep: 返回深度引用对象的数据。默认为 false，以便为性能返回浅引用对象中的数据。
  • dedupe: 避免在一次时间内对同一键进行更多的请求（默认为 cancel）。可能的选项：
    • cancel - 当有新请求时，取消现有请求。
    • defer - 如果当前有一个待处理的请求，不会做出新的请求。

返回值

• data: 异步函数传递的结果。
• refresh/execute: 一个用于刷新由 handler 函数返回的数据的函数。
• error: 一个错误对象，如果数据获取失败。
• status: 一个字符串，指示数据请求的状态（"idle"、"pending"、"success"、"error"）。
• clear: 一个函数，将 data 设置为 undefined，将 error 设置为 null，将 status 设置为 'idle'，并将任何当前待处理的请求标记为取消。

默认情况下，Nuxt 会在 refresh 执行完毕之前才能再次执行。

类型

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'