useFetch

このコンポーザブルは、useAsyncDataと$fetchの便利なラッパーを提供します。URLとフェッチオプションに基づいてキーを自動的に生成し、サーバールートに基づいてリクエストURLの型ヒントを提供し、APIレスポンスの型を推測します。

使用方法

<script setup lang="ts">
const { data, status, error, refresh, clear } = await useFetch('/api/modules', {
  pick: ['title']
})
</script>

queryオプションを使用すると、クエリに検索パラメーターを追加できます。このオプションはunjs/ofetchから拡張されており、unjs/ufoを使用してURLを作成します。オブジェクトは自動的に文字列化されます。

const param1 = ref('value1')
const { data, status, error, refresh } = await useFetch('/api/modules', {
  query: { param1, param2: 'value2' }
})

上記の例では、https://api.nuxt.com/modules?param1=value1&param2=value2になります。

インターセプターも使用できます。

const { data, status, error, refresh, clear } = await useFetch('/api/auth/login', {
  onRequest({ request, options }) {
    // Set the request headers
    // note that this relies on ofetch >= 1.4.0 - you may need to refresh your lockfile
    options.headers.set('Authorization', '...')
  },
  onRequestError({ request, options, error }) {
    // Handle the request errors
  },
  onResponse({ request, response, options }) {
    // Process the response data
    localStorage.setItem('token', response._data.token)
  },
  onResponseError({ request, response, options }) {
    // Handle the response errors
  }
})

パラメーター

• URL: 取得するURL。
• オプション (unjs/ofetchオプションとAsyncDataOptionsを拡張)
  • method: リクエストメソッド。
  • query: ufoを使用してURLにクエリ検索パラメーターを追加します。
  • params: queryのエイリアス。
  • body: リクエストボディ - （オブジェクトが渡された場合）自動的に文字列化されます。
  • headers: リクエストヘッダー。
  • baseURL: リクエストのベースURL。
  • timeout: リクエストを自動的に中止するミリ秒数。
  • cache: Fetch APIに従ってキャッシュ制御を処理します。
    • キャッシュを無効にするにはブール値を渡すことができます。または、default、no-store、reload、no-cache、force-cache、only-if-cachedのいずれかの値を渡すことができます。

• オプション ( useAsyncDataから)
  • key: データ取得をリクエスト間で適切に重複排除できるようにするためのユニークなキー。指定されていない場合、URLとフェッチオプションに基づいて自動的に生成されます。
  • 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: リアクティブなソースの配列を監視し、それらが変更されたときにフェッチ結果を自動的に更新します。フェッチオプションとURLはデフォルトで監視されます。watch: falseを使用して、リアクティブなソースを完全に無視できます。immediate: falseと組み合わせて使用することで、完全に手動のuseFetchが可能です。（watchの使用方法の例はこちらを参照してください）。
  • deep: 深いrefオブジェクトでデータ返す（デフォルトはtrue）。データに深いリアクティブ性が不要な場合は、浅いrefオブジェクトでデータ返すようにfalseに設定してパフォーマンスを向上させることができます。
  • dedupe: 同一のキーを一度に複数回フェッチすることを回避します（デフォルトはcancel）。可能なオプション
    • cancel - 新しいリクエストが作成されると、既存のリクエストがキャンセルされます。
    • defer - 保留中のリクエストがある場合、新しいリクエストはまったく作成されません。

戻り値

• data: 渡された非同期関数の結果。
• refresh/execute: handler関数によって返されたデータを更新するために使用できる関数。
• error: データ取得に失敗した場合のエラーオブジェクト。
• status: データリクエストのステータスを示す文字列（"idle"、"pending"、"success"、"error"）。
• clear: dataをundefinedに設定し、errorをnullに設定し、statusを'idle'に設定し、現在保留中のリクエストをすべてキャンセル済みにマークする関数。

デフォルトでは、Nuxtはrefreshが完了するまで、再度実行できません。

型

function useFetch<DataT, ErrorT>(
  url: string | Request | Ref<string | Request> | (() => string) | Request,
  options?: UseFetchOptions<DataT>
): Promise<AsyncData<DataT, ErrorT>>

type UseFetchOptions<DataT> = {
  key?: string
  method?: string
  query?: SearchParams
  params?: SearchParams
  body?: RequestInit['body'] | Record<string, any>
  headers?: Record<string, string> | [key: string, value: string][] | Headers
  baseURL?: string
  server?: boolean
  lazy?: boolean
  immediate?: boolean
  getCachedData?: (key: string, nuxtApp: NuxtApp) => DataT
  deep?: boolean
  dedupe?: 'cancel' | 'defer'
  default?: () => DataT
  transform?: (input: DataT) => DataT | Promise<DataT>
  pick?: string[]
  watch?: WatchSource[] | false
}

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'