useAsyncData

useAsyncData 提供了一种在 SSR 友好的可组合函数中访问异步解析数据的功能。

在你的页面、组件和插件中，你可以使用 useAsyncData 来访问异步解析的数据。

useAsyncData 是一个设计为直接在 Nuxt 上下文中调用的可组合函数。它返回响应式可组合对象，并处理将响应添加到 Nuxt 负载中，以便在页面水合时无需在客户端重新获取数据即可从服务器传递到客户端。

使用方法

pages/index.vue

<script setup lang="ts">
const { data, status, error, refresh, clear } = await useAsyncData(
  'mountains',
  () => $fetch('https://api.nuxtjs.dev/mountains')
)
</script>

如果使用自定义的 useAsyncData 包装器，请不要在可组合函数中对其进行 await，因为这可能导致意外行为。请参考此配方以获取有关如何创建自定义异步数据获取器的更多信息。

data、status 和 error 是 Vue ref 对象，在 <script setup> 中使用时需要通过 .value 访问，而 refresh/execute 和 clear 是普通函数。

监听参数

内置的 watch 选项允许在检测到任何更改时自动重新运行获取函数。

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>

响应式键

你可以使用计算属性 ref、普通 ref 或 getter 函数作为键，以实现动态数据获取，并在键更改时自动更新：

pages/[id].vue

<script setup lang="ts">
const route = useRoute()
const userId = computed(() => `user-${route.params.id}`)

// 当路由更改且 userId 更新时，数据将自动重新获取
const { data: user } = useAsyncData(
  userId,
  () => fetchUserById(route.params.id)
)
</script>

useAsyncData 是一个由编译器转换的保留函数名称，因此你不应该将自己的函数命名为 useAsyncData。

阅读更多 Docs > Getting Started > Data Fetching#useasyncdata.

参数

key：一个唯一键，用于确保数据获取在请求之间能够正确去重。如果未提供键，将为你生成一个基于文件名和 useAsyncData 实例行号的唯一键。
handler：一个异步函数，必须返回一个真值（例如，不应为 undefined 或 null），否则请求可能在客户端重复执行。
handler 函数应无副作用，以确保在 SSR 和 CSR 水合期间的行为可预测。如果需要触发副作用，请使用 callOnce 工具来实现。
options：
- 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：监听响应式数据源以自动刷新
- deep：以深层 ref 对象返回数据。默认为 false，以浅层 ref 对象返回数据，如果数据不需要深层响应性，可以提高性能。
- dedupe：避免同一键同时多次获取（默认：cancel）。可能选项：
  - cancel - 当发起新请求时取消现有请求
  - defer - 如果有待处理的请求，则完全不发起新请求

在底层，lazy: false 使用 <Suspense> 在数据获取完成前阻止路由加载。考虑使用 lazy: true 并实现加载状态以获得更流畅的用户体验。

你可以使用 useLazyAsyncData 来获得与 useAsyncData 中 lazy: true 相同的行为。

共享状态和选项一致性

当对多个 useAsyncData 调用使用相同的键时，它们将共享相同的 data、error 和 status ref。这确保了组件之间的一致性，但需要选项一致性。

以下选项在所有使用相同键的调用中必须保持一致：

handler 函数
deep 选项
transform 函数
pick 数组
getCachedData 函数
default 值

以下选项可以不同，不会触发警告：

server
lazy
immediate
dedupe
watch

// ❌ 这将触发开发警告
const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { deep: false })
const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { deep: true })

// ✅ 这是允许的
const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { immediate: true })
const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { immediate: false })

使用 useAsyncData 创建的键控状态可以通过 useNuxtData 在你的 Nuxt 应用中检索。

返回值

data：传入的异步函数的结果。
refresh/execute：一个可用于刷新 handler 函数返回数据的函数。
error：如果数据获取失败，则为错误对象。
status：指示数据请求状态的字符串：
- idle：当请求尚未开始时，例如：
  - 当 execute 尚未调用且设置了 { immediate: false }
  - 当在服务器上渲染 HTML 且设置了 { server: false }
- pending：请求正在进行
- success：请求成功完成
- error：请求失败
clear：一个可用于将 data 设置为 undefined（或如果提供了 options.default()，则为其值）、将 error 设置为 undefined、将 status 设置为 idle，并将当前待处理的请求标记为取消的函数。

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

如果未在服务器上获取数据（例如，使用 server: false），则在水合完成前不会获取数据。这意味着即使在客户端 await useAsyncData，在 <script setup> 中 data 仍将保持 undefined。

类型

签名

function useAsyncData<DataT, DataE>(
  handler: (nuxtApp?: NuxtApp) => Promise<DataT>,
  options?: AsyncDataOptions<DataT>
): AsyncData<DataT, DataE>
function useAsyncData<DataT, DataE>(
  key: MaybeRefOrGetter<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?: MultiWatchSources | false
  getCachedData?: (key: string, nuxtApp: NuxtApp, ctx: AsyncDataRequestContext) => DataT | undefined
}

type AsyncDataRequestContext = {
  /** 数据请求的原因 */
  cause: 'initial' | 'refresh:manual' | 'refresh:hook' | 'watch'
}

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

interface AsyncDataExecuteOptions {
  dedupe?: 'cancel' | 'defer'
}

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

阅读更多 Docs > Getting Started > Data Fetching.

Was this helpful?

Report an issue or Edit this page on GitHub

useAppConfig

访问项目中定义的响应式应用程序配置。

useCookie

useCookie 是一个 SSR 友好的可组合函数，用于读取和写入 cookie。