useFetch
使用 SSR 友好的组合式函数从 API 端点获取数据。
此组合式函数为 useAsyncData
和 $fetch
提供了便捷的封装。它基于 URL 和 fetch 选项自动生成键,为基于服务器路由的请求 URL 提供类型提示,并推断 API 响应类型。
useFetch
是一个组合式函数,旨在直接在 setup 函数、插件或路由中间件中调用。它返回响应式组合式函数,并处理将响应添加到 Nuxt payload,以便它们可以从服务器传递到客户端,而无需在页面水合时在客户端重新获取数据。用法
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¶m2=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
的 import 语句。在 文档 > 示例 > 高级 > 使用自定义 Fetch 组合式函数 中阅读和编辑实时示例。
在 文档 > 示例 > 功能 > 数据获取 中阅读和编辑实时示例。
参数
URL
:要获取的 URL。Options
(继承自 unjs/ofetch options & AsyncDataOptions)
所有 fetch 选项都可以给定一个
computed
或 ref
值。这些值将被监视,并且如果更新,则会自动发出新的请求。Options
(来自useAsyncData
)key
:一个唯一的键,以确保数据获取可以在跨请求中正确地去重,如果未提供,它将根据 URL 和 fetch 选项自动生成server
:是否在服务器上获取数据(默认为true
)lazy
:是否在加载路由后解析异步函数,而不是阻止客户端导航(默认为false
)immediate
:设置为false
时,将阻止请求立即触发。(默认为true
)default
:一个工厂函数,用于设置data
的默认值,在异步函数解析之前 - 与lazy: true
或immediate: false
选项一起使用很有用transform
:一个函数,可用于在解析后更改handler
函数结果getCachedData
:提供一个返回缓存数据的函数。null
或undefined
返回值将触发 fetch。默认情况下,这是仅当启用const getDefaultCachedData = (key, nuxtApp) => nuxtApp.isHydrating ? nuxtApp.payload.data[key] : nuxtApp.static.data[key]
nuxt.config
的experimental.payloadExtraction
时才缓存数据。pick
:仅从此数组中选择handler
函数结果中指定的键watch
:监视响应式源数组,并在它们更改时自动刷新 fetch 结果。默认情况下,会监视 Fetch 选项和 URL。您可以使用watch: false
完全忽略响应式源。与immediate: false
一起使用,这允许完全手动useFetch
。(您可以在 此处查看使用watch
的示例。)deep
:在深度 ref 对象中返回数据(默认情况下为true
)。可以将其设置为false
以在浅层 ref 对象中返回数据,如果您的数据不需要深度响应式,这可以提高性能。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
,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 | undefined
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'