useAsyncData

useAsyncData 提供了对异步解析的数据的访问,这是一个 SSR 友好的组合式函数。

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

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

使用方法

app/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,当在 <script setup> 中使用时应该通过 .value 访问,而 refresh/execute 和 clear 是普通函数。

监听参数

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

app/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>

响应式键

你可以使用 computed ref、plain ref 或 getter 函数作为键,允许动态数据获取在键更改时自动更新:

app/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

你也可以向 refresh/execute 函数传递 AbortSignal 来手动取消单个请求。

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() // 中止正在进行的 refresh 请求
}

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

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

Handler 信号将在以下情况时被中止:

使用 dedupe: 'cancel' 发出新请求
调用 clear 函数
超过 options.timeout 持续时间

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

在 https://nuxt.com/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: 提供一个返回缓存数据的函数。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 和 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(即当 status.value === 'pending' 时)。
clear: 一个可用于将 data 设置为 undefined(如果提供了则为 options.default() 的值),将 error 设置为 undefined,将 status 设置为 idle,并将任何当前待处理的请求标记为已取消的函数。

默认情况下,Nuxt 会等到 refresh 完成才能再次执行。

如果你没有在服务器上获取数据(例如,使用 server: false),则数据在水分完成之前_不会_被获取。这意味着即使你在客户端 await useAsyncData``,在 data将保持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 = {
  /** 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>
  pending: Ref<boolean>
}

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

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

报告问题或在 GitHub 上编辑此页面

useAppConfig

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

工具函数

发现 Nuxt 中可用的工具函数。