数据获取

<script setup lang="ts">
const { data } = await useFetch('/api/data')

async function handleFormSubmit() {
  const res = await $fetch('/api/submit', {
    method: 'POST',
    body: {
      // My form data
    }
  })
}
</script>

<template>
  <div v-if="data == null">
    No data
  </div>
  <div v-else>
    <form @submit="handleFormSubmit">
      <!-- form input tags -->
    </form>
  </div>
</template>

你可以添加 <NuxtLoadingIndicator> 以在页面导航之间添加进度条。

<script setup lang="ts">
async function addTodo() {
  const todo = await $fetch('/api/todos', {
    method: 'POST',
    body: {
      // My todo data
    }
  })
}
</script>

<script setup lang="ts">
const { data } = await useFetch('/api/echo');
</script>

// /api/echo.ts
export default defineEventHandler(event => parseCookies(event))

<script setup lang="ts">
const headers = useRequestHeaders(['cookie'])

async function getCurrentUser() {
  return await $fetch('/api/me', { headers })
}
</script>

<script setup lang="ts">
const { data: count } = await useFetch('/api/count')
</script>

<template>
  <p>Page visits: {{ count }}</p>
</template>

<script setup lang="ts">
const { data, error } = await useAsyncData('users', () => myGetFunction('users'))

// This is also possible:
const { data, error } = await useAsyncData(() => myGetFunction('users'))
</script>

useAsyncData 的第一个参数是一个唯一键，用于缓存第二个参数（查询函数）的响应。可以通过直接传递查询函数来忽略此键，该键将自动生成。

由于自动生成的键仅考虑调用 useAsyncData 的文件和行，因此建议始终创建自己的键以避免出现不必要的行为，例如在创建自定义可组合组件封装 useAsyncData 时。:br
设置键对于在使用 useNuxtData 或 refresh specific data 的组件之间共享相同数据非常有用。

<script setup lang="ts">
const { id } = useRoute().params

const { data, error } = await useAsyncData(`user:${id}`, () => {
  return myGetFunction('users', { id })
})
</script>

<script setup lang="ts">
const { data: discounts, status } = await useAsyncData('cart-discount', async () => {
  const [coupons, offers] = await Promise.all([
    $fetch('/cart/coupons'),
    $fetch('/cart/offers')
  ])

  return { coupons, offers }
})
// discounts.value.coupons
// discounts.value.offers
</script>

useAsyncData 用于获取和缓存数据，不会触发副作用（例如调用 Pinia 操作），因为这可能会导致意外行为，例如重复执行并返回空值。如果你需要触发副作用，请使用 callOnce 实用程序。```vue你也可以使用 useLazyFetch 和 useLazyAsyncData 作为便捷的方法来执行相同的操作。¥You can alternatively use useLazyFetch and useLazyAsyncData as convenient methods to perform the same.:了解更多关于 useLazyFetch 的信息。¥Read more about useLazyFetch.:::了解更多关于 useLazyAsyncData 的信息。¥Read more about useLazyAsyncData.::

仅客户端抓取

¥Client-only fetching默认情况下，数据获取可组合项将在客户端和服务器环境中执行其异步函数。将 server 选项设置为 false，以便仅在客户端执行调用。初始加载时，数据在 hydration 完成之前不会被获取，因此你必须处理待处理状态。不过，在后续的客户端导航中，数据将被等待加载后再加载页面。¥By default, data fetching composables will perform their asynchronous function on both client and server environments. Set the server option to false to only perform the call on the client-side. On initial load, the data will not be fetched before hydration is complete so you have to handle a pending state, though on subsequent client-side navigation the data will be awaited before loading the page.与 lazy 选项结合使用，这对于首次渲染时不需要的数据（例如，非 SEO 敏感数据）非常有用。¥Combined with the lazy option, this can be useful for data that is not needed on the first render (for example, non-SEO sensitive data).useFetch 可组合项应在设置方法中调用，或在生命周期钩子函数的顶层直接调用，否则应使用 $fetch 方法。¥The useFetch composable is meant to be invoked in setup method or called directly at the top level of a function in lifecycle hooks, otherwise you should use $fetch method.

最小化负载大小

¥Minimize payload sizepick 选项可帮助你通过仅选择希望从可组合项返回的字段来最小化存储在 HTML 文档中的有效负载大小。¥The pick option helps you to minimize the payload size stored in your HTML document by only selecting the fields that you want returned from the composables.如果你需要更多控制或映射多个对象，你可以使用 transform 函数来更改查询结果。¥If you need more control or map over several objects, you can use the transform function to alter the result of the query.

缓存和重新获取

¥Caching and refetching

键

¥KeysuseFetch 和 useAsyncData 使用键来防止重新获取相同的数据。¥useFetch and useAsyncData use keys to prevent refetching the same data.

• useFetch 使用提供的 URL 作为键。或者，也可以将 key 值作为最后一个参数传入 options 对象。
• 如果 useAsyncData 的第一个参数是字符串，则将其用作键。如果第一个参数是执行查询的处理函数，则会为你生成一个与 useAsyncData 实例的文件名和行号唯一的键。

共享状态和选项一致性

¥Shared State and Option Consistency当多个组件使用与 useAsyncData 或 useFetch 相同的键时，它们将共享相同的 data、error 和 status 引用。这确保了跨组件的一致性，但需要一些选项保持一致。¥When multiple components use the same key with useAsyncData or useFetch, they will share the same data, error and status refs. This ensures consistency across components but requires some options to be consistent.以下选项在使用相同键的所有调用中必须保持一致：¥The following options must be consistent across all calls with the same key:

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

以下选项可以安全地不同而不会触发警告：¥The following options can safely differ without triggering warnings:

• server
• lazy
• immediate
• dedupe
• watch

如果你需要独立的实例，请使用不同的键：¥If you need independent instances, use different keys:

响应式键

¥Reactive Keys你可以使用计算引用、普通引用或 getter 函数作为键，从而实现动态数据获取，并在依赖发生变化时自动更新：¥You can use computed refs, plain refs or getter functions as keys, allowing for dynamic data fetching that automatically updates when dependencies change:

刷新并执行

¥Refresh and execute如果你想手动获取或刷新数据，请使用可组合项提供的 execute 或 refresh 函数。¥If you want to fetch or refresh data manually, use the execute or refresh function provided by the composables.execute 函数是 refresh 的别名，其工作方式完全相同，但在获取 并非立即发布 时更具语义。¥The execute function is an alias for refresh that works in exactly the same way but is more semantic for cases when the fetch is not immediate.

清除

¥Clear如果你出于某种原因想要清除提供的数据，而不需要知道传递给 clearNuxtData 的具体键，你可以使用可组合项提供的 clear 函数。¥If you want to clear the data provided, for whatever reason, without needing to know the specific key to pass to clearNuxtData, you can use the clear function provided by the composables.

观看

¥Watch要在应用中的其他响应式值每次发生变化时重新运行获取函数，请使用 watch 选项。你可以将其用于一个或多个可监视元素。¥To re-run your fetching function each time other reactive values in your application change, use the watch option. You can use it for one or multiple watchable elements.请注意，监视响应式值不会更改获取的 URL。例如，由于 URL 是在调用函数时构建的，因此这将持续获取相同的用户初始 ID。¥Note that watching a reactive value won't change the URL fetched. For example, this will keep fetching the same initial ID of the user because the URL is constructed at the moment the function is invoked.如果你需要根据响应式值更改 URL，则可能需要使用 计算 URL。¥If you need to change the URL based on a reactive value, you may want to use a computed URL instead.

计算 URL

¥Computed URL有时你可能需要根据响应式值计算 URL，并在每次更改时刷新数据。你可以将每个参数作为响应式值附加，而无需费力操作。Nuxt 将自动使用响应式值，并在每次更改时重新获取。¥Sometimes you may need to compute an URL from reactive values, and refresh the data each time these change. Instead of juggling your way around, you can attach each param as a reactive value. Nuxt will automatically use the reactive value and re-fetch each time it changes.对于更复杂的 URL 构造，你可以使用回调作为返回 URL 字符串的 计算 getter。¥In the case of more complex URL construction, you may use a callback as a computed getter that returns the URL string.每次依赖发生变化时，数据都会使用新构建的 URL 进行获取。将此与 not-immediate 结合使用，你可以等到响应式元素发生变化后再进行抓取。¥Every time a dependency changes, the data will be fetched using the newly constructed URL. Combine this with not-immediate, and you can wait until the reactive element changes before fetching.如果你需要在其他响应式值发生变化时强制刷新，也可以使用 关注其他值。¥If you need to force a refresh when other reactive values change, you can also watch other values.

非立即生效

¥Not immediateuseFetch 可组合项将在被调用时开始获取数据。例如，你可以通过设置 immediate: false 来等待用户交互，从而避免这种情况。¥The useFetch composable will start fetching data the moment is invoked. You may prevent this by setting immediate: false, for example, to wait for user interaction.这样，你将需要 status 来处理数据获取生命周期，以及 execute 来启动数据获取。¥With that, you will need both the status to handle the fetch lifecycle, and execute to start the data fetch.为了更精细地控制，status 变量可以是：¥For finer control, the status variable can be:

• idle 表示抓取尚未开始
• pending 表示抓取已开始但尚未完成
• error 表示抓取失败
• success 表示抓取成功完成

传递标头和 Cookie

¥Passing Headers and Cookies当我们在浏览器中调用 $fetch 时，像 cookie 这样的用户标头将直接发送到 API。¥When we call $fetch in the browser, user headers like cookie will be directly sent to the API.通常，在服务器端渲染期间，出于安全考虑，$fetch 不会包含用户的浏览器 Cookie，也不会传递来自 fetch 响应的 Cookie。¥Normally, during server-side-rendering, due to security considerations, the $fetch wouldn't include the user's browser cookies, nor pass on cookies from the fetch response.然而，当使用服务器上的相对 URL 调用 useFetch 时，Nuxt 将使用 useRequestFetch 来代理 headers 和 cookies（不打算转发的 headers 除外，例如 host）。¥However, when calling useFetch with a relative URL on the server, Nuxt will use useRequestFetch to proxy headers and cookies (with the exception of headers not meant to be forwarded, like host).

在 SSR 响应时从服务器端 API 调用传递 Cookie

¥Pass Cookies From Server-side API Calls on SSR Response如果你想将 cookie 从内部请求传递/代理到客户端，则需要自行处理。¥If you want to pass on/proxy cookies in the other direction, from an internal request back to the client, you will need to handle this yourself.

选项 API 支持

¥Options API supportNuxt 提供了一种在 Options API 中执行 asyncData 抓取的方法。你必须将组件定义封装在 defineNuxtComponent 中才能使其正常工作。¥Nuxt provides a way to perform asyncData fetching within the Options API. You must wrap your component definition within defineNuxtComponent for this to work.

从服务器到客户端的序列化数据

¥Serializing Data From Server to Client当使用 useAsyncData 和 useLazyAsyncData 将服务器端获取的数据传输到客户端（以及任何其他使用 Nuxt 负载 的组件）时，有效负载将使用 devalue 进行序列化。这不仅使我们能够传输基本的 JSON，还能序列化和恢复/反序列化更高级的数据类型，例如正则表达式、日期、Map 和 Set、ref、reactive、shallowRef、shallowReactive 和 NuxtError - 以及更多。¥When using useAsyncData and useLazyAsyncData to transfer data fetched on server to the client (as well as anything else that utilizes the Nuxt payload), the payload is serialized with devalue. This allows us to transfer not just basic JSON but also to serialize and revive/deserialize more advanced kinds of data, such as regular expressions, Dates, Map and Set, ref, reactive, shallowRef, shallowReactive and NuxtError - and more.对于 Nuxt 不支持的类型，也可以定义自己的序列化器/反序列化器。你可以在 useNuxtApp 文档中阅读更多信息。¥It is also possible to define your own serializer/deserializer for types that are not supported by Nuxt. You can read more in the useNuxtApp docs.

从 API 序列化数据路由

¥Serializing Data From API Routes从 server 目录获取数据时，响应会使用 JSON.stringify 进行序列化。但是，由于序列化仅限于 JavaScript 原始类型，因此 Nuxt 会尽力将 $fetch 和 useFetch 的返回类型转换为与实际值匹配的类型。¥When fetching data from the server directory, the response is serialized using JSON.stringify. However, since serialization is limited to only JavaScript primitive types, Nuxt does its best to convert the return type of $fetch and useFetch to match the actual value.:了解更多关于 JSON.stringify 的限制。¥Learn more about JSON.stringify limitations.::

示例

¥Example

自定义序列化函数

¥Custom serializer function要自定义序列化行为，你可以在返回的对象上定义一个 toJSON 函数。如果你定义了 toJSON 方法，Nuxt 将遵循该函数的返回类型，并且不会尝试转换类型。¥To customize the serialization behavior, you can define a toJSON function on your returned object. If you define a toJSON method, Nuxt will respect the return type of the function and will not try to convert the types.

使用替代序列化器

¥Using an alternative serializerNuxt 目前不支持 JSON.stringify 的替代序列化器。但是，你可以将有效负载返回为普通字符串，并使用 toJSON 方法来维护类型安全。¥Nuxt does not currently support an alternative serializer to JSON.stringify. However, you can return your payload as a normal string and utilize the toJSON method to maintain type safety.在下面的示例中，我们使用 superjson 作为序列化器。¥In the example below, we use superjson as our serializer.

Recipes

通过 POST 请求使用 SSE（服务器发送事件）

¥Consuming SSE (Server Sent Events) via POST request通过 POST 请求使用 SSE 时，你需要手动处理连接。以下是操作方法：¥When consuming SSE via POST request, you need to handle the connection manually. Here's how you can do it:

并行请求

¥Making parallel requests当请求彼此不依赖时，你可以将它们与 Promise.all() 并行运行以提高性能。¥When requests don't rely on each other, you can make them in parallel with Promise.all() to boost performance.