useFetch

使用支持SSR的可组合函数从API端点获取数据。

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

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

用法

pages/modules.vue

const { data, status, error, refresh, clear } = await useFetch('/api/modules', {
  pick: ['title']
})

如果你正在使用自定义的useFetch封装，不要在可组合函数中等待它，因为这可能会导致意外行为。请参阅这个示例以获取有关如何制作自定义异步数据获取器的更多信息。

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 }) {
    // 设置请求头
    // 注意这依赖于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 }) {
    // 处理响应错误
  }
})

响应式键和共享状态

你可以使用计算ref或普通ref作为URL，允许动态数据获取，当URL更改时自动更新：

pages/[id\

const route = useRoute()
const id = computed(() => route.params.id)

// 当路由更改并且id更新时，数据将自动重新获取
const { data: post } = await useFetch(() => `/api/posts/${id.value}`)

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

useFetch是编译器转换的保留函数名，因此不应将自己的函数命名为useFetch。

如果你遇到从useFetch解构的data变量返回的是字符串而不是JSON解析对象，请确保你的组件没有包含类似import { useFetch } from '@vueuse/core'的导入语句。

另请参阅 getting-started > data-fetching

类型

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 = {
  /** 此数据请求的原因 */
  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'

参数

URL (string | Request | Ref<string | Request> | () => string | Request): 要获取的URL或请求。可以是字符串、Request对象、Vue ref或返回字符串/Request的函数。支持动态端点的响应性。
options (object): fetch请求的配置。扩展自unjs/ofetch选项和AsyncDataOptions。所有选项可以是静态值、ref或计算值。

选项	类型	默认值	描述
`key`	`string`	自动生成	用于去重的唯一键。如果未提供，则从URL和选项生成。
`method`	`string`	`'GET'`	HTTP请求方法。
`query`	`object`	-	要附加到URL的查询/搜索参数。别名：`params`。支持refs/computed。
`params`	`object`	-	`query`的别名。
`body`	`RequestInit['body'] \| Record<string, any>`	-	请求体。对象会自动字符串化。支持refs/computed。
`headers`	`Record<string, string> \| [key, value][] \| Headers`	-	请求头。
`baseURL`	`string`	-	请求的基本URL。
`timeout`	`number`	-	中止请求的超时时间（毫秒）。
`cache`	`boolean \| string`	-	缓存控制。布尔值禁用缓存，或使用Fetch API值：`default`、`no-store`等。
`server`	`boolean`	`true`	是否在服务器上获取。
`lazy`	`boolean`	`false`	如果为true，则在路由加载后解析（不阻止导航）。
`immediate`	`boolean`	`true`	如果为false，则阻止请求立即触发。
`default`	`() => DataT`	-	异步解析之前`data`的默认值工厂。
`transform`	`(input: DataT) => DataT \| Promise<DataT>`	-	解析后转换结果的函数。
`getCachedData`	`(key, nuxtApp, ctx) => DataT \| undefined`	-	返回缓存数据的函数。见下文默认值。
`pick`	`string[]`	-	仅从结果中选择指定的键。
`watch`	`WatchSource[] \| false`	-	要监视和自动刷新的一组响应式源。`false`禁用监视。
`deep`	`boolean`	`false`	在深度ref对象中返回数据。
`dedupe`	`'cancel' \| 'defer'`	`'cancel'`	避免同时多次获取相同键。
`$fetch`	`typeof $fetch`	-	自定义$fetch实现。

所有fetch选项都可以给定computed或ref值。这些将被监视，并在更新时自动发起新请求。

getCachedData默认值：

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

这仅在nuxt.config中启用experimental.payloadExtraction时缓存数据。

返回值

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

状态值

idle: 请求尚未开始（例如{ immediate: false }或{ server: false }在服务器渲染时）
pending: 请求正在进行中
success: 请求成功完成
error: 请求失败

如果你没有在服务器上获取数据（例如，使用server: false），那么数据_不会_在加载完成之前获取。这意味着即使你在客户端等待useFetch，data在<script setup>中仍将保持null。

示例

示例代码的编辑与预览examples > advanced > use-custom-fetch-composable

示例代码的编辑与预览examples > features > data-fetching

※此页面是 Nuxt.js 官方文档的非官方翻译页面。

官方文档中的相应页面在此处：
https://nuxt.com/docs/3.x/api/composables/use-fetch