useAsyncData

源文件
useAsyncData 提供对异步解析数据的访问，它是一个对 SSR 友好的可组合函数。

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

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

使用

app/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 选项允许在检测到任何更改时自动重新运行 fetcher 函数。

app/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 函数用作 key，从而实现动态数据获取，并在 key 更改时自动更新。

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

// When the route changes and userId updates, the data will be automatically refetched
const { data: user } = useAsyncData(
  userId,
  () => fetchUserById(route.params.id),
)
</script>
useAsyncData 是一个由编译器转换的保留函数名，因此您不应将自己的函数命名为 useAsyncData。
更多信息请阅读 文档 > 4.X > 入门 > 数据获取#useasyncdata。

参数

  • key：一个唯一的键，用于确保数据获取可以跨请求正确地去重。如果您不提供键，Nuxt 将为 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 - 如果存在待处理的请求，则根本不发出新请求
    • timeout - 一个以毫秒为单位的数字，表示在请求超时前等待的时间（默认为 undefined，表示没有超时）
在底层，lazy: false 使用 <Suspense> 在数据获取完成之前阻塞路由加载。考虑使用 lazy: true 并实现加载状态，以获得更流畅的用户体验。
您可以使用 useLazyAsyncData 来获得与 useAsyncData 配合 lazy: true 相同的行为。

共享状态和选项一致性

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

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

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

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

  • 服务器
  • lazy
  • immediate
  • dedupe
  • watch
// ❌ This will trigger a development warning
const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { deep: false })
const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { deep: true })

// ✅ This is allowed
const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { immediate: true })
const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { immediate: false })
使用 useAsyncData 创建的带键状态可以在整个 Nuxt 应用程序中使用 useNuxtData 检索。

返回值

  • 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，data 在 <script setup> 内仍将保持 undefined。

类型

签名
export function useAsyncData<DataT, DataE> (
  handler: (nuxtApp: NuxtApp, options: { signal: AbortSignal }) => Promise<DataT>,
  options?: AsyncDataOptions<DataT>
): AsyncData<DataT, DataE>
export function useAsyncData<DataT, DataE> (
  key: MaybeRefOrGetter<string>,
  handler: (nuxtApp: NuxtApp, options: { signal: AbortSignal }) => 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
  timeout?: number
}

type AsyncDataRequestContext = {
  /** The reason for this data request */
  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'
  timeout?: number
  signal?: AbortSignal
}

type AsyncDataRequestStatus = 'idle' | 'pending' | 'success' | 'error'
在文档 > 4 X > 入门 > 数据获取中阅读更多信息。