useAsyncData · Nuxt 組合式函式

在您的頁面、元件和外掛程式中，您可以使用 useAsyncData 來存取非同步解析的資料。

useAsyncData 是一個組合式函式，旨在直接在 Nuxt 上下文中呼叫。它會回傳響應式組合式函式，並處理將回應新增至 Nuxt 有效負載，以便它們可以從伺服器傳遞到客戶端，而無需在頁面水合時於客戶端重新抓取資料。

用法

pages/index.vue

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

如果您使用自訂的 useAsyncData 包裝器，請勿在組合式函式中等待它，因為這可能會導致意料之外的行為。請參考此指南，以取得關於如何製作自訂非同步資料抓取器的更多資訊。

data、status 和 error 是 Vue 響應式參考，當在 <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），否則請求可能會在客戶端重複。
handler 函式應為無副作用的，以確保在伺服器端渲染和客戶端渲染水合期間的可預測行為。如果您需要觸發副作用，請使用 callOnce 工具程式來執行。
選項:
- server：是否在伺服器上抓取資料（預設為 true）
- lazy：是否在載入路由後解析非同步函式，而不是阻止客戶端導航（預設為 false）
- immediate：設定為 false 時，將防止請求立即觸發。（預設為 true）
- default：一個工廠函式，用於設定 data 的預設值，在非同步函式解析之前 - 與 lazy: true 或 immediate: false 選項一起使用時很有用
- transform：一個函式，可用於在解析後更改 handler 函式結果
- getCachedData：提供一個回傳快取資料的函式。null 或 undefined 回傳值將觸發抓取。預設情況下，這是
```
const getDefaultCachedData = (key, nuxtApp) => nuxtApp.isHydrating 
  ? nuxtApp.payload.data[key] 
  : nuxtApp.static.data[key]
```
  僅在啟用 nuxt.config 的 experimental.payloadExtraction 時快取資料。
- pick：僅從 handler 函式結果中挑選此陣列中指定的鍵
- watch：監看響應式來源以自動重新整理
- deep：在深層響應式參考物件中回傳資料（預設為 true）。可以將其設定為 false 以在淺層響應式參考物件中回傳資料，如果您的資料不需要深層響應式，這可以提升效能。
- dedupe：避免一次抓取相同鍵多次（預設為 cancel）。可能的選項
  - cancel - 在建立新請求時取消現有請求
  - defer - 如果有待處理的請求，則完全不建立新請求

在底層，lazy: false 使用 <Suspense> 來阻止路由的載入，直到資料被抓取。考慮使用 lazy: true 並實作載入狀態，以獲得更流暢的使用者體驗。

您可以使用 useLazyAsyncData 以獲得與 lazy: true 和 useAsyncData 相同的行為。

瞭解如何使用 transform 和 getCachedData 來避免多餘的 API 呼叫，並為客戶端上的訪客快取資料。

回傳值

data：傳入的非同步函式的結果。
refresh/execute：一個函式，可用於重新整理 handler 函式回傳的資料。
error：如果資料抓取失敗，則為錯誤物件。
status：一個字串，指示資料請求的狀態
- idle：當請求尚未開始時，例如
  - 當 execute 尚未被呼叫且設定了 { immediate: false } 時
  - 當在伺服器上渲染 HTML 且設定了 { server: false } 時
- pending：請求正在進行中
- success：請求已成功完成
- error：請求已失敗
clear：一個函式，它會將 data 設定為 undefined、將 error 設定為 null、將 status 設定為 'idle'，並將任何目前等待中的請求標記為已取消。

預設情況下，Nuxt 會等待 refresh 完成後，才能再次執行。

如果您未在伺服器上抓取資料（例如，使用 server: false），則資料將不會被抓取，直到水合完成。這表示即使您在客戶端等待 useAsyncData，data 在 <script setup> 中仍將保持 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 | undefined
}

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 是一個適合伺服器端渲染的組合式函式，用於讀取和寫入 Cookie。