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

使用方法

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

パラメータの監視

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

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

リアクティブキー

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

const route = useRoute()
const userId = computed(() => `user-${route.params.id}`)

// ルートが変更されuserIdが更新されると、データは自動的に再フェッチされます
const { data: user } = useAsyncData(
  userId,
  () => fetchUserById(route.params.id)
)

パラメータ

• key: リクエスト間でデータフェッチを適切に重複排除するための一意のキー。キーを指定しない場合、useAsyncDataのインスタンスのファイル名と行番号に基づいて一意のキーが生成されます。
• handler: 真値を返す必要がある非同期関数（例えば、undefinedやnullであってはならない）。そうでないと、クライアント側でリクエストが重複する可能性があります。

• 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オブジェクトで返す（デフォルトはtrue）。データが深くリアクティブである必要がない場合、パフォーマンスを向上させるためにfalseに設定できます。
  • dedupe: 同じキーを一度に複数回フェッチするのを避ける（デフォルトはcancel）。可能なオプション：
    • cancel - 新しいリクエストが行われたときに既存のリクエストをキャンセル
    • defer - 保留中のリクエストがある場合、新しいリクエストを全く行わない

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

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

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

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

次のオプションは、警告をトリガーすることなく異なることができます：

• server
• lazy
• immediate
• dedupe
• watch

// ❌ これは開発警告をトリガーします
const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { deep: false })
const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { deep: true })

// ✅ これは許可されています
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をnullに設定し、statusをidleに設定し、現在保留中のリクエストをキャンセル済みとしてマークするために使用できる関数。

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

型

function useAsyncData<DataT, DataE>(
  handler: (nuxtApp?: NuxtApp) => Promise<DataT>,
  options?: AsyncDataOptions<DataT>
): AsyncData<DataT, DataE>
function useAsyncData<DataT, DataE>(
  key: string | Ref<string> | ComputedRef<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[] | false
  getCachedData?: (key: string, nuxtApp: NuxtApp, ctx: AsyncDataRequestContext) => DataT | undefined
}

type AsyncDataRequestContext = {
  /** このデータリクエストの理由 */
  cause: 'initial' | 'refresh:manual' | 'refresh:hook' | 'watch'
}

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'