useAsyncData

ページ、コンポーネント、プラグイン内で useAsyncData を使用して、非同期に解決されるデータにアクセスできます。

使用方法

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

ウォッチャー パラメーター

組み込みの watch オプションを使用すると、変更が検出されたときにフェッチャー関数を自動的に再実行できます。

<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>

リアクティブキー

キーとして computed ref、プレーン ref、または getter 関数を使用でき、キーが変更されたときに自動的に更新される動的なデータフェッチングを可能にします。

<script setup lang="ts">
const route = useRoute()
const userId = computed(() => `user-${route.params.id}`)

// When the route changes and userId updates, the data will be automatically refetched
const { data: user } = useAsyncData(
  userId,
  () => fetchUserById(route.params.id),
)
</script>

パラメータ

• key: リクエスト全体でデータフェッチングが適切に重複排除されるようにするためのユニークなキー。キーを指定しない場合、useAsyncData インスタンスのファイル名と行番号に固有のキーが自動的に生成されます。
• handler: truthy な値を返す必要がある非同期関数 (たとえば、undefined や null であってはなりません)。そうでない場合、クライアント側でリクエストが重複する可能性があります。
  handler 関数は、SSR および CSR のハイドレーション中に予測可能な動作を保証するために副作用がない必要があります。副作用をトリガーする必要がある場合は、callOnce ユーティリティを使用してそれを行ってください。
• options:
  • server: サーバーでデータをフェッチするかどうか (true がデフォルト)
  • lazy: クライアント側のナビゲーションをブロックする代わりに、ルートのロード後に非同期関数を解決するかどうか (false がデフォルト)
  • immediate: false に設定すると、リクエストがすぐに発行されるのを防ぎます (true がデフォルト)
  • default: 非同期関数が解決する前に data のデフォルト値を設定するためのファクトリ関数 - lazy: true または immediate: false オプションと組み合わせて使用すると便利です
  • transform: 解決後に handler 関数の結果を変更するために使用できる関数
  • getCachedData: キャッシュされたデータを返す関数を提供します。null または undefined の戻り値はフェッチをトリガーします。デフォルトでは、これは

    const getDefaultCachedData = (key, nuxtApp, ctx) => nuxtApp.isHydrating
      ? nuxtApp.payload.data[key]
      : nuxtApp.static.data[key]
    

    nuxt.config の experimental.payloadExtraction が有効になっている場合にのみデータをキャッシュします。
  • pick: handler 関数の結果から、この配列で指定されたキーのみを選択します。
  • watch: リアクティブソースを監視して自動更新します。
  • deep: データをディープ ref オブジェクトで返します。データが深くリアクティブである必要がない場合、パフォーマンスを向上させるために、デフォルトでは false に設定されており、シャロー ref オブジェクトでデータを返します。
  • dedupe: 同じキーを同時に複数回フェッチするのを避けます (cancel がデフォルト)。可能なオプションは次のとおりです。
    • cancel - 新しいリクエストが作成されると既存のリクエストをキャンセルします。
    • defer - 保留中のリクエストがある場合、新しいリクエストをまったく行いません。
  • timeout - リクエストがタイムアウトするまで待機するミリ秒単位の数値 (undefined がデフォルト。これはタイムアウトがないことを意味します)。

共有状態とオプションの一貫性

複数の useAsyncData 呼び出しで同じキーを使用すると、同じ data、error、status ref が共有されます。これにより、コンポーネント間の一貫性が保証されますが、オプションの一貫性が必要です。

次のオプションは、同じキーを持つすべての呼び出しで一貫している必要があります。

• handler 関数
• deep オプション
• transform 関数
• pick 配列
• getCachedData 関数
• default 値

以下のオプションは、警告をトリガーすることなく異なる場合があります。

• サーバー
• lazy
• immediate
• dedupe
• watch

// ❌ This will trigger a development warning
const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { deep: false })
const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { deep: true })

// ✅ This is allowed
const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { immediate: true })
const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { immediate: false })

戻り値

• data: 渡された非同期関数の結果。
• refresh/execute: handler 関数によって返されたデータを更新するために使用できる関数。
• error: データフェッチが失敗した場合のエラーオブジェクト。
• status: データリクエストのステータスを示す文字列。
  • idle: リクエストが開始されていない場合、たとえば
    • execute がまだ呼び出されておらず、{ immediate: false } が設定されている場合
    • サーバーで HTML をレンダリングし、{ server: false } が設定されている場合
  • pending: リクエストが進行中の場合
  • success: リクエストが正常に完了した場合
  • error: リクエストが失敗した場合
• clear: data を undefined (または options.default() が提供されている場合はその値) に設定し、error を undefined に設定し、status を idle に設定し、現在保留中のリクエストをキャンセル済みとしてマークするために使用できる関数。

デフォルトでは、Nuxt は refresh が完了するまで、再度実行されるのを待ちます。

タイプ

export function useAsyncData<DataT, DataE> (
  handler: (nuxtApp: NuxtApp, options: { signal: AbortSignal }) => Promise<DataT>,
  options?: AsyncDataOptions<DataT>
): AsyncData<DataT, DataE>
export function useAsyncData<DataT, DataE> (
  key: MaybeRefOrGetter<string>,
  handler: (nuxtApp: NuxtApp, options: { signal: AbortSignal }) => 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?: MultiWatchSources | false
  getCachedData?: (key: string, nuxtApp: NuxtApp, ctx: AsyncDataRequestContext) => DataT | undefined
  timeout?: number
}

type AsyncDataRequestContext = {
  /** The reason for this data request */
  cause: 'initial' | 'refresh:manual' | 'refresh:hook' | 'watch'
}

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

interface AsyncDataExecuteOptions {
  dedupe?: 'cancel' | 'defer'
  timeout?: number
  signal?: AbortSignal
}

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