useAsyncData · Nuxt Composables

您可以在頁面、元件和插件中使用 useAsyncData 來取得非同步解析的資料。

useAsyncData 是一個組合式函式，旨在直接在 Nuxt 環境中呼叫。它會回傳響應式的組合式函式，並處理將回應添加到 Nuxt 的 payload 中，以便在頁面水合 (hydrate) 時，可以從伺服器傳遞到客戶端，而**無需在客戶端重新獲取資料**。

用法

pages/index.vue

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

如果您正在使用自訂的 useAsyncData 包裝函式，請勿在組合式函式中 await 它，因為這可能會導致意外的行為。請參考此範例，以獲取更多關於如何建立自訂的非同步資料擷取器的資訊。

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：一個必須回傳真值 (truthy value) 的非同步函式 (例如，它不應該是 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 來獲得與使用 useAsyncData 時的 lazy: true 相同的行為。

學習如何使用 transform 和 getCachedData 來避免不必要的 API 呼叫，並為客戶端的訪客快取資料。

回傳值

data：傳入的非同步函式的結果。
refresh/execute：一個可用於刷新 handler 函式所回傳的資料的函式。
error：如果資料擷取失敗，則為錯誤物件。
status：一個字串，指示資料請求的狀態（"idle"、"pending"、"success"、"error"）。
clear：一個函式，它會將 data 設定為 undefined，將 error 設定為 null，將 status 設定為 'idle'，並將任何目前待處理的請求標記為已取消。

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

如果您沒有在伺服器上擷取資料（例如，使用 server: false），那麼在水合完成之前，資料將不會被擷取。這意味著即使您在客戶端 await 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
}

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