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 响应式对象，在 <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 的导入语句。

观看 Alexander Lichter 的视频，避免错误地使用 useFetch！

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

在文档 > 快速上手 > 数据获取中了解更多信息。

在文档 > 示例 > 功能 > 数据获取中阅读和编辑实时示例。

参数

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 的返回值将触发获取。默认情况下，这是：key => nuxt.isHydrating ? nuxt.payload.data[key] : nuxt.static.data[key]，这仅在启用 payloadExtraction 时缓存数据。
- pick：仅从 handler 函数结果中选择此数组中的指定键
- watch：监视一组响应式源，并在它们更改时自动刷新获取结果。默认情况下会监视获取选项和 URL。您可以通过使用 watch: false 完全忽略响应式源。结合 immediate: false，这允许完全手动控制 useFetch。（您可以在此处查看一个示例，了解如何使用 watch。）
- deep：以深度响应式对象的形式返回数据（默认为 true）。可以将其设置为 false 以浅响应式对象的形式返回数据，如果您的数据不需要深度响应式，这可以提高性能。
- dedupe：避免同时多次获取相同的键（默认为 cancel）。可能的选项
  - cancel - 当发出新请求时，取消现有请求
  - defer - 如果有挂起的请求，则根本不发出新请求

如果您提供函数或响应式对象作为 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），则数据将不会在 hydration 完成之前获取。这意味着即使您在客户端等待 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 组合式返回正在处理的全局 Nuxt 错误。

useHead

useHead 自定义 Nuxt 应用中各个页面的头部属性。