useAsyncData · Nuxt 组合式函数

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

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

用法

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

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 。

在文档 > 入门 > 数据获取#useasyncdata 中阅读更多内容。

参数

key：一个唯一的键，以确保可以在请求之间正确地消除数据获取的重复。如果您不提供键，则会为您生成一个对 useAsyncData 实例的文件名和行号唯一的键。
handler：一个异步函数，必须返回真值（例如，它不应为 undefined 或 null），否则请求可能会在客户端重复。
选项:
- server：是否在服务器上获取数据（默认为 true）
- lazy：是否在加载路由后解析异步函数，而不是阻止客户端导航（默认为 false）
- immediate：设置为 false 时，将阻止请求立即触发。（默认为 true）
- default：一个工厂函数，用于在异步函数解析之前设置 data 的默认值 - 在使用 lazy: true 或 immediate: false 选项时很有用
- transform：一个函数，可用于在解析后更改 handler 函数的结果
- getCachedData: 提供一个返回缓存数据的函数。如果返回值为 null 或 undefined，则会触发获取操作。默认情况下，该函数为：key => nuxt.isHydrating ? nuxt.payload.data[key] : nuxt.static.data[key]，仅当启用 payloadExtraction 时才会缓存数据。
- pick: 仅从 handler 函数的结果中选取此数组中指定的键。
- watch: 监听响应式源，以自动刷新。
- deep: 返回深层 ref 对象中的数据（默认为 true）。可以设置为 false 以返回浅层 ref 对象中的数据，如果你的数据不需要深度响应式，这可以提高性能。
- dedupe: 避免一次获取同一键值多次（默认为 cancel）。可选值：
  - cancel - 当发出新的请求时，取消现有请求。
  - defer - 如果存在待处理的请求，则完全不发出新的请求。

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

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

了解如何使用 transform 和 getCachedData 来避免不必要的 API 调用，并为客户端的访问者缓存数据。

返回值

data: 传入的异步函数的结果。
refresh/execute: 可用于刷新 handler 函数返回的数据的函数。
error: 如果数据获取失败，则返回错误对象。
status: 一个字符串，表示数据请求的状态（"idle"、"pending"、"success"、"error"）。
clear: 一个函数，它会将 data 设置为 undefined，将 error 设置为 null，将 status 设置为 'idle'，并将任何当前待处理的请求标记为已取消。

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

如果你没有在服务器上获取数据（例如，使用 server: false），则数据将不会在水合完成之前获取。这意味着即使你在客户端等待 useAsyncData，在 <script setup> 中，data 仍将为 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
}

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'

请在文档 > 入门 > 数据获取中阅读更多信息。

useAppConfig

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

useCookie

useCookie 是一个 SSR 友好的 composable，用于读取和写入 cookie。