useAsyncData · Nuxt Composables

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

useAsyncData是一种组合式，可以直接在设置函数、插件或路由中调用。它返回响应式的组合式，并处理将响应添加到Nuxt负载中，以便在页面水合时从服务器传递到客户端，而不需要在客户端重新获取数据。

用法

pages/index.vue

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

监听参数

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

pages/index.vue

<script setup>
const page = ref(1)
const { data: posts } = await useAsyncData(
  'posts',
  () => $fetch('https://fakeApi.com/posts', {
    params: {
      page: page.value
    }
  }), {
    watch: [page]
  }
)
</script>

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

Read more in Docs > Getting Started > Data Fetching#useasyncdata.

参数

key：一个唯一的键，用于确保数据获取可以在请求中正确去重。如果不提供键，则会为useAsyncData的实例生成一个与文件名和行号唯一对应的键。
handler：一个必须返回真值（例如，不能是undefined或null）的异步函数，否则请求可能会在客户端上重复。
options：
- server：是否在服务器上获取数据（默认为true）
- lazy：是否在加载路由后解析异步函数，而不是阻塞客户端导航（默认为false）
- immediate：当设置为false时，将阻止立即触发请求。（默认为true）
- default：在异步函数解析之前，设置data的默认值的工厂函数 - 在lazy: true或immediate: false选项下非常有用
- transform：一个在解析后可以用来修改handler函数结果的函数
- pick：只从handler函数结果中选择指定的键
- watch：监听响应式源以自动刷新
- deep：以深层响应式对象返回数据（默认为true）。可以将其设置为false以返回浅层响应式对象的数据，如果你的数据不需要深层响应式，则可以提高性能。

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

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

返回值

data：传入的异步函数的结果。
pending：一个布尔值，指示数据是否仍在获取中。
refresh/execute：一个可以用来刷新handler函数返回的数据的函数。
error：如果数据获取失败，则为一个错误对象。
status：一个字符串，表示数据请求的状态（"idle"、"pending"、"success"、"error"）。

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

如果你没有在服务器上获取数据（例如，server: false），那么直到水合完成之前，数据将不会被获取。这意味着即使在客户端上等待useAsyncData，data仍然为null。

类型

Signature

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
  default?: () => DataT | Ref<DataT> | null
  transform?: (input: DataT) => DataT
  pick?: string[]
  watch?: WatchSource[]
  getCachedData?: (key: string) => DataT
}

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

interface AsyncDataExecuteOptions {
  dedupe?: boolean
}

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

Read more in Docs > Getting Started > Data Fetching.

useAppConfig

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

useCookie

useCookie是一个适用于服务器端渲染（SSR）的组合函数，用于读取和写入cookie。