useAsyncData
useAsyncData 提供了在 SSR 友好的 composable 中异步解析的数据的访问。
在您的页面、组件和插件中,您可以使用 useAsyncData 来访问异步解析的数据。
useAsyncData
是一个 composable,旨在直接在 Nuxt 上下文 中调用。它返回响应式 composable,并处理将响应添加到 Nuxt payload,以便它们可以从服务器传递到客户端,而无需在客户端 hydration 时重新获取数据。用法
pages/index.vue
<script setup lang="ts">
const { data, status, error, refresh, clear } = await useAsyncData(
'mountains',
() => $fetch('https://api.nuxtjs.dev/mountains')
)
</script>
如果您正在使用自定义的 useAsyncData 包装器,请不要在 composable 中等待它,因为这可能会导致意外行为。请遵循此食谱,以获取有关如何制作自定义异步数据获取器的更多信息。
data
、 status
和 error
是 Vue refs,当在 <script setup>
中使用时,应该使用 .value
访问,而 refresh
/execute
和 clear
是普通函数。Watch Params
内置的 watch
选项允许在检测到任何更改时自动重新运行 fetcher 函数。
pages/index.vue
<script setup lang="ts">
const page = ref(1)
const { data: posts } = await useAsyncData(
'posts',
() => $fetch('https://fakeApi.com/posts', {
params: {
page: page.value
}
}), {
watch: [page]
}
)
</script>
useAsyncData
是编译器转换的保留函数名,因此您不应将自己的函数命名为 useAsyncData
。参数
key
:一个唯一的键,以确保可以在请求之间正确地去重数据获取。如果您不提供键,那么将为您生成一个对于useAsyncData
实例的文件名和行号唯一的键。handler
:一个异步函数,必须返回 truthy 值(例如,它不应为undefined
或null
),否则可能会在客户端重复请求。handler
函数应该是无副作用的,以确保在 SSR 和 CSR hydration 期间的可预测行为。如果您需要触发副作用,请使用callOnce
实用程序来执行此操作。选项
:server
:是否在服务器上获取数据(默认为true
)lazy
:是否在加载路由后解析异步函数,而不是阻止客户端导航(默认为false
)immediate
:设置为false
时,将阻止立即触发请求。(默认为true
)default
:一个工厂函数,用于设置data
的默认值,在异步函数解析之前 - 与lazy: true
或immediate: false
选项一起使用很有用transform
:一个函数,可用于在解析后更改handler
函数结果getCachedData
:提供一个返回缓存数据的函数。null
或undefined
返回值将触发获取。默认情况下,这是仅当const getDefaultCachedData = (key, nuxtApp) => nuxtApp.isHydrating ? nuxtApp.payload.data[key] : nuxtApp.static.data[key]
nuxt.config
的experimental.payloadExtraction
启用时才缓存数据。pick
:仅从此数组中选择handler
函数结果中指定的键watch
:观察响应式源以自动刷新deep
:在深度 ref 对象中返回数据(默认情况下为true
)。可以将其设置为false
以在浅层 ref 对象中返回数据,如果您的数据不需要深度响应式,这可以提高性能。dedupe
:避免一次获取多个相同键(默认为cancel
)。可能的选项cancel
- 当发出新请求时取消现有请求defer
- 如果有待处理的请求,则根本不发出新请求
在幕后,
lazy: false
使用 <Suspense>
在数据获取之前阻止路由的加载。考虑使用 lazy: true
并实现加载状态以获得更快的用户体验。返回值
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
),那么在 hydration 完成之前将不会获取数据。这意味着即使您在客户端等待 useAsyncData
,data
在 <script setup>
中仍将为 null
。类型
签名
function useAsyncData<DataT, DataE>(
handler: (nuxtApp?: NuxtApp) => Promise<DataT>,
options?: AsyncDataOptions<DataT>
): AsyncData<DataT, DataE>
function useAsyncData<DataT, DataE>(
key: string,
handler: (nuxtApp?: NuxtApp) => Promise<DataT>,
options?: AsyncDataOptions<DataT>
): Promise<AsyncData<DataT, DataE>>
type AsyncDataOptions<DataT> = {
server?: boolean
lazy?: boolean
immediate?: boolean
deep?: boolean
dedupe?: 'cancel' | 'defer'
default?: () => DataT | Ref<DataT> | null
transform?: (input: DataT) => DataT | Promise<DataT>
pick?: string[]
watch?: WatchSource[]
getCachedData?: (key: string, nuxtApp: NuxtApp) => DataT | undefined
}
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'