useAsyncData

源码
useAsyncData 提供了一个 SSR 友好的组合式函数，用于访问异步解析的数据。

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

useAsyncData 是一个组合式函数，旨在直接在 Nuxt 上下文 中调用。它返回响应式的组合式函数并处理将响应添加到 Nuxt 负载中，使其能够从服务器传递到客户端，在页面水合时不会重新在客户端获取数据。

用法

pages/index.vue
<script setup lang="ts">
const { data, status, pending, error, refresh, clear } = await useAsyncData(
  'mountains',
  (_nuxtApp, { signal }) => $fetch('https://api.nuxtjs.dev/mountains', { signal }),
)
</script>
如果你正在使用自定义的 useAsyncData 包装器，请勿在组合式函数中对其加 await，因为这可能导致意外行为。请参考此示例了解如何制作自定义的异步数据获取器。
data、status、pending`` 和 error是 Vue 的 ref，使用时需要通过.value访问（比如在refresh/execute和clear` 是普通函数。

监听参数

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

pages/index.vue
<script setup lang="ts">
const page = ref(1)
const { data: posts } = await useAsyncData(
  'posts',
  (_nuxtApp, { signal }) => $fetch('https://fakeApi.com/posts', {
    params: {
      page: page.value,
    },
    signal,
  }), {
    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>

使你的 handler 函数支持中止

你可以通过第二个参数中提供的 signal 来使你的 handler 函数可中止。当请求不再需要（例如用户离开页面时）时，这非常有用。$fetch 原生支持中止信号。

const { data, error } = await useAsyncData(
  'users',
  (_nuxtApp, { signal }) => $fetch('/api/users', { signal }),
)

refresh() // 实际会取消 $fetch 请求（如果 dedupe 设置为 cancel）
refresh() // 实际会取消 $fetch 请求（如果 dedupe 设置为 cancel）
refresh()

clear() // 会取消最新的待处理 handler

你也可以手动传入 AbortSignal 到 refresh/execute 函数中，以取消单独的请求。

const { refresh } = await useAsyncData(
  'users',
  (_nuxtApp, { signal }) => $fetch('/api/users', { signal }),
)
let abortController: AbortController | undefined

function handleUserAction () {
  abortController = new AbortController()
  refresh({ signal: abortController.signal })
}

function handleCancel () {
  abortController?.abort() // 终止正在进行的刷新请求
}

如果你的 handler 函数不支持中止信号，你可以利用提供的 signal 实现自己的中止逻辑。

const { data, error } = await useAsyncData(
  'users',
  (_nuxtApp, { signal }) => {
    return new Promise((resolve, reject) => {
      signal?.addEventListener('abort', () => {
        reject(new Error('请求已中止'))
      })
      return Promise.resolve(callback.call(this, yourHandler)).then(resolve, reject)
    })
  },
)

以下情况下，handler 的 signal 会被中止：

  • 使用 dedupe: 'cancel' 发起新请求
  • 调用 clear 函数时
  • 超过 options.timeout 时间时
useAsyncData 是编译器保留的函数名，所以你不应该将自定义函数命名为 useAsyncData。
在 Docs > Getting Started > Data Fetching#useasyncdata 中查看详情

参数

  • key：唯一键，确保在请求间正确去重数据获取。如果不提供，系统会为 useAsyncData 实例生成基于文件名和行号的唯一键。
  • handler：异步函数，必须返回真值（例如，不应返回 undefined 或 null），否则客户端可能会重复请求数据。
    handler 函数应无副作用以确保 SSR 和客户端水合期间行为可预测。如果你需要触发副作用，请使用 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 包装数据（默认值为 true）。如果数据无需深度响应，可设为 false，提高性能。
    • dedupe：避免在同一时间内针对相同键发起多次请求（默认为 cancel），可选值：
      • cancel - 在发起新请求时取消现有请求
      • defer - 如果有挂起请求，则不发起新请求
    • timeout：超时时间，单位毫秒（默认为 undefined，表示无超时）
底层，lazy: false 利用 <Suspense> 阻塞路由加载直到数据获取完成。建议使用 lazy: true 并实现加载状态，以获得更流畅的用户体验。
你可以使用 useLazyAsyncData 来获得与 useAsyncData 中 lazy: true 相同的行为。

共享状态与选项一致性

当多次调用 useAsyncData 使用相同键时，它们会共享同一个 data、error、status 和 pending ref。这确保了跨组件的数据一致性，但要求使用的选项也保持一致。

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

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

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

  • server
  • lazy
  • immediate
  • dedupe
  • watch
// ❌ 这样会触发开发环境警告
const { data: users1 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { deep: false })
const { data: users2 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { deep: true })

// ✅ 这样是允许的
const { data: users1 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { immediate: true })
const { data: users2 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { immediate: false })
通过 useAsyncData 创建的带键状态可以通过 useNuxtData 在整个 Nuxt 应用中获取。

返回值

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

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

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

类型

Signature
export type AsyncDataHandler<ResT> = (nuxtApp: NuxtApp, options: { signal: AbortSignal }) => Promise<ResT>

export function useAsyncData<DataT, DataE> (
  handler: AsyncDataHandler<DataT>,
  options?: AsyncDataOptions<DataT>,
): AsyncData<DataT, DataE>
export function useAsyncData<DataT, DataE> (
  key: MaybeRefOrGetter<string>,
  handler: AsyncDataHandler<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
  timeout?: number
}

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>
  pending: Ref<boolean>
}

interface AsyncDataExecuteOptions {
  dedupe?: 'cancel' | 'defer'
  timeout?: number
  signal?: AbortSignal
}

type AsyncDataRequestStatus = 'idle' | 'pending' | 'success' | 'error'
在 Docs > Getting Started > Data Fetching 中查看详情