useFetch · Nuxt Composables

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

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

用法

pages/index.vue

<script setup>
const route = useRoute()

const { data, pending, error, refresh } = await useFetch(`https://api.nuxtjs.dev/mountains/${route.params.slug}`, {
  pick: ['title']
})
</script>

使用query选项，您可以向查询中添加搜索参数。此选项是从unjs/ofetch扩展的，并使用unjs/ufo创建URL。对象会自动转换为字符串。

const param1 = ref('value1')
const { data, pending, error, refresh } = await useFetch('https://api.nuxtjs.dev/mountains', {
  query: { param1, param2: 'value2' }
})

结果为https://api.nuxtjs.dev/mountains?param1=value1&param2=value2

您还可以使用拦截器：

const { data, pending, error, refresh } = await useFetch('/api/auth/login', {
  onRequest({ request, options }) {
    // 设置请求头
    options.headers = options.headers || {}
    options.headers.authorization = '...'
  },
  onRequestError({ request, options, error }) {
    // 处理请求错误
  },
  onResponse({ request, response, options }) {
    // 处理响应数据
    localStorage.setItem('token', response._data.token)
  },
  onResponseError({ request, response, options }) {
    // 处理响应错误
  }
})

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

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。

所有的fetch选项都可以给定computed或ref值。如果它们被更新，将自动进行新的请求。

Options（来自useAsyncData）：
- key：一个唯一的键，用于确保数据获取可以在请求之间正确去重。如果未提供，将根据使用useAsyncData的静态代码位置生成。
- server：是否在服务器上获取数据（默认为true）。
- lazy：是否在加载路由后解析异步函数，而不是阻止客户端导航（默认为false）。
- immediate：如果设置为false，将阻止立即发出请求（默认为true）。
- default：一个工厂函数，用于设置data的默认值，在异步函数解析之前使用 - 与lazy: true或immediate: false选项一起使用。
- transform：在解析后可以用于更改handler函数结果的函数。
- pick：仅从handler函数结果中选择指定的键。
- watch：监听一组响应式源，并在它们发生变化时自动刷新获取的结果。默认情况下，会监听fetch选项和URL。您可以通过使用watch: false来完全忽略响应式源。结合immediate: false，可以实现完全手动的useFetch。
- deep：以深层ref对象的形式返回数据（默认为true）。可以将其设置为false，以在浅层ref对象中返回数据，如果您的数据不需要深层响应，则可以提高性能。

如果您将函数或ref作为url参数，或者如果您将函数作为options参数的参数传递给useFetch调用，即使选项似乎相同，该调用也不会与代码库中的其他useFetch调用匹配。如果您希望强制匹配，可以在options中提供自己的键。

返回值

data：传入的异步函数的结果。
pending：一个布尔值，指示数据是否仍在获取中。
refresh/execute：一个可以用于刷新handler函数返回的数据的函数。
error：如果数据获取失败，则为错误对象。
status：表示数据请求的状态的字符串（"idle"、"pending"、"success"、"error"）。

默认情况下，Nuxt会等待refresh完成后才能再次执行。

如果您没有在服务器上获取数据（例如，使用server: false），那么直到水合完成之前，数据将不会被获取。这意味着即使在客户端上等待useFetch，data也将在<script setup>中保持为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) => DataT
  deep?: boolean
  default?: () => DataT
  transform?: (input: DataT) => DataT
  pick?: string[]
  watch?: WatchSource[] | false
}

type AsyncData<DataT, ErrorT> = {
  data: Ref<DataT | null>
  pending: Ref<boolean>
  refresh: (opts?: AsyncDataExecuteOptions) => Promise<void>
  execute: (opts?: AsyncDataExecuteOptions) => Promise<void>
  error: Ref<ErrorT | null>
  status: Ref<AsyncDataRequestStatus>
}

interface AsyncDataExecuteOptions {
  dedupe?: boolean
}

type AsyncDataRequestStatus = 'idle' | 'pending' | 'success' | 'error'

useError

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

useHeadSafe

推荐的方法是使用用户输入来提供头数据。