useFetch

使用一个适合服务器端渲染的组合函数从 API 端点获取数据。

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

useFetch 是一个组合函数，旨在直接在设置函数、插件或路由中间件中调用。它返回响应式组合函数，并处理将响应添加到 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。

您还可以使用拦截器：

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 更改时自动更新：

pages/[id].vue

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

// 当路由变化和 ID 更新时，数据将会自动重新获取。
const { data: post } = await useFetch(() => `/api/posts/${id.value}`)
</script>

在多个组件中使用相同的 URL 和选项时，useFetch 将共享相同的 data、error 和 status 引用。这确保了组件之间的一致性。

useFetch 是一个被编译器保留的函数名称，因此你不应将自己的函数命名为 useFetch。

如果你发现 useFetch destructed 的 data 变量返回一个字符串而不是解析后的 JSON 对象，那么请确保你的组件没有包含像 import { useFetch } from '@vueuse/core' 的导入语句。

Read and edit a live example in Docs > Examples > Advanced > Use Custom Fetch Composable.

Read more in Docs > Getting Started > Data Fetching.

Read and edit a live example in Docs > Examples > Features > Data Fetching.

参数

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, ctx) => 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: 返回深度引用对象中的数据。默认情况下为false，即返回浅层引用对象中的数据，若您的数据无需深度响应式处理，此模式可提升性能。
- dedupe: 避免在同一时间获取同一键不超过一次（默认值为 cancel）。可能的选项：
  - cancel - 当发出新请求时取消现有请求。
  - defer - 如果有待处理的请求，则不发出新的请求。

如果你提供一个函数或 ref 作为 url 参数，或者如果你向 options 参数提供函数作为参数，则 useFetch 调用将不会与代码库中其他地方的 useFetch 调用匹配，即使选项似乎相同。如果你希望强制匹配，可以在 options 中提供自己的键。

如果你使用 useFetch 来调用开发中具有自签名证书的（外部）HTTPS URL，您需要在您的环境中设置 NODE_TLS_REJECT_UNAUTHORIZED=0。

返回值

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，在 <script setup> 中，data 将保持为 null。

类型

Signature

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, ctx: AsyncDataRequestContext) => DataT | undefined
  deep?: boolean
  dedupe?: 'cancel' | 'defer'
  default?: () => DataT
  transform?: (input: DataT) => DataT | Promise<DataT>
  pick?: string[]
  watch?: WatchSource[] | false
}

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

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'

报告问题或者在 GitHub 上编辑此页面

useError

useError 组合函数返回正在处理的全局 Nuxt 错误。

useHead

useHead 自定义您 Nuxt 应用程序单个页面的头部属性。