useFetch

SSRフレンドリーなコンポーザブルを使ってAPIエンドポイントからデータをフェッチします。

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

useFetch は、セットアップ関数、プラグイン、またはルーティングミドルウェアで直接呼び出されることを意図したコンポーザブルです。リアクティブなコンポーザブルを返し、Nuxtペイロードに応答を追加することで、ページがハイドレートされる際にクライアント側でデータを再フェッチすることなく、サーバーからクライアントにデータを渡すことができます。

使用方法

app/pages/modules.vue

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

カスタムの useFetch ラッパーを使用している場合、予期せぬ動作を引き起こす可能性があるため、コンポーザブル内で await しないでください。カスタムの非同期データフェッチャーを作成する方法については、このレシピに従ってください。

data、status、および error は Vue の ref であり、<script setup> 内で使用する場合は .value でアクセスする必要があります。一方、refresh/execute と clear はプレーンな関数です。

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
  },
})

リアクティブキーと共有状態

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

app/pages/[id].vue

<script setup lang="ts">
const route = useRoute()
const id = computed(() => route.params.id)

// When the route changes and id updates, the data will be automatically refetched
const { data: post } = await useFetch(() => `/api/posts/${id.value}`)
</script>

複数のコンポーネントで同じURLとオプションを持つ useFetch を使用すると、同じ data、error、および status ref を共有します。これにより、コンポーネント間で一貫性が保たれます。

useFetch を使用して作成されたキー付き状態は、useNuxtData を使用してNuxtアプリケーション全体で取得できます。

useFetch はコンパイラによって変換される予約済みの関数名であるため、独自の関数に useFetch という名前を付けないでください。

useFetch から分割された data 変数が、JSONパースされたオブジェクトではなく文字列を返す場合、コンポーネントに import { useFetch } from '@vueuse/core のような import ステートメントが含まれていないことを確認してください。

Docs > 4 X > Getting Started > Data Fetching で詳細をご覧ください。

リアクティブなフェッチオプション

フェッチオプションはリアクティブとして提供でき、computed、ref および算出ゲッターをサポートします。リアクティブなフェッチオプションが更新されると、更新された解決済みリアクティブ値を使用して再フェッチがトリガーされます。

const searchQuery = ref('initial')
const { data } = await useFetch('/api/search', {
  query: { q: searchQuery },
})
// triggers a refetch: /api/search?q=new%20search
searchQuery.value = 'new search'

必要に応じて、watch: false を使用してこの動作をオプトアウトできます。

const searchQuery = ref('initial')
const { data } = await useFetch('/api/search', {
  query: { q: searchQuery },
  watch: false,
})
// does not trigger a refetch
searchQuery.value = 'new search'

タイプ

署名

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

type UseFetchOptions<DataT> = {
  key?: MaybeRefOrGetter<string>
  method?: MaybeRefOrGetter<string>
  query?: MaybeRefOrGetter<SearchParams>
  params?: MaybeRefOrGetter<SearchParams>
  body?: MaybeRefOrGetter<RequestInit['body'] | Record<string, any>>
  headers?: MaybeRefOrGetter<Record<string, string> | [key: string, value: string][] | Headers>
  baseURL?: MaybeRefOrGetter<string>
  server?: boolean
  lazy?: boolean
  immediate?: boolean
  getCachedData?: (key: string, nuxtApp: NuxtApp, ctx: AsyncDataRequestContext) => DataT | undefined
  deep?: boolean
  dedupe?: 'cancel' | 'defer'
  timeout?: number
  default?: () => DataT
  transform?: (input: DataT) => DataT | Promise<DataT>
  pick?: string[]
  $fetch?: typeof globalThis.$fetch
  watch?: MultiWatchSources | false
  timeout?: MaybeRefOrGetter<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'

パラメーター

URL (string | Request | Ref<string | Request> | () => string | Request): フェッチするURLまたはリクエスト。文字列、Request オブジェクト、Vue ref、または文字列/Request を返す関数にすることができます。動的なエンドポイントのリアクティビティをサポートします。
options (object): フェッチリクエストの構成。これはunjs/ofetchoptions と AsyncDataOptions を拡張します。すべてのオプションは静的な値、ref、または算出値にすることができます。

オプション	タイプ	デフォルト	説明
`キー`	`MaybeRefOrGetter<string>`	自動生成	重複排除のためのユニークキー。指定されない場合、URLとオプションから生成されます。
`method`	`MaybeRefOrGetter<string>`	`'GET'`	HTTPリクエストメソッド。
`query`	`MaybeRefOrGetter<SearchParams>`	-	URLに追加するクエリ/検索パラメータ。エイリアス: `params`。
`params`	`MaybeRefOrGetter<SearchParams>`	-	`query` のエイリアス。
`body`	`MaybeRefOrGetter<RequestInit['body'] \| Record<string, any>>`	-	リクエストボディ。オブジェクトは自動的に文字列化されます。
`headers`	`MaybeRefOrGetter<Record<string, string> \| [key, value][] \| Headers>`	-	リクエストヘッダー。
`baseURL`	`MaybeRefOrGetter<string>`	-	リクエストのベースURL。
`timeout`	`MaybeRefOrGetter<number>`	-	リクエストを中止するまでのタイムアウト（ミリ秒）。
`cache`	`boolean \| string`	-	キャッシュ制御。ブーリアンはキャッシュを無効にし、Fetch API の値（`default`, `no-store` など）も使用できます。
`サーバー`	`ブール値`	`true`	サーバー上でフェッチするかどうか。
`lazy`	`ブール値`	`false`	trueの場合、ルートロード後に解決します（ナビゲーションをブロックしません）。
`immediate`	`ブール値`	`true`	falseの場合、リクエストがすぐに実行されるのを防ぎます。
`default`	`() => DataT`	-	非同期解決前の `data` のデフォルト値のファクトリ。
`timeout`	`number`	-	リクエストのタイムアウトを待つミリ秒単位の数値（デフォルトは `undefined` で、タイムアウトなしを意味します）
`transform`	`(input: DataT) => DataT \| Promise<DataT>`	-	解決後に結果を変換する関数。
`getCachedData`	`(key, nuxtApp, ctx) => DataT \| undefined`	-	キャッシュされたデータを返す関数。デフォルトについては以下を参照。
`pick`	`string[]`	-	結果から指定されたキーのみを選択します。
`watch`	`MultiWatchSources \| false`	-	監視して自動的に更新するリアクティブソースの配列。`false` は監視を無効にします。
`deep`	`ブール値`	`false`	データをディープRefオブジェクトで返します。
`dedupe`	`'cancel' \| 'defer'`	`'cancel'`	同じキーを一度に複数回フェッチしないようにします。
`$fetch`	`typeof globalThis.$fetch`	-	カスタム $fetch 実装。詳細については Nuxt のカスタム useFetch を参照してください。

すべてのフェッチオプションは、computed または ref の値を与えることができます。これらは監視され、更新されると新しい値で新しいリクエストが自動的に行われます。

getCachedData のデフォルト

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

これは、nuxt.config の experimental.payloadExtraction が有効になっている場合にのみデータをキャッシュします。

戻り値

名前	タイプ	説明
`data`	`Ref<DataT \| undefined>`	非同期フェッチの結果。
`refresh`	`(opts?: AsyncDataExecuteOptions) => Promise<void>`	データを手動で更新する関数。デフォルトでは、Nuxt は `refresh` が完了するまで次の実行を待ちます。
`execute`	`(opts?: AsyncDataExecuteOptions) => Promise<void>`	`refresh` のエイリアス。
`error`	`Ref<ErrorT \| undefined>`	データフェッチが失敗した場合のエラーオブジェクト。
`status`	`Ref<'idle' \| 'pending' \| 'success' \| 'error'>`	データリクエストのステータス。取り得る値については以下を参照してください。
`clear`	`() => void`	`data` を `undefined` (または `options.default()` が指定されていればその値) に、`error` を `undefined` にリセットし、`status` を `idle` に設定し、保留中のリクエストをキャンセルします。

ステータスの値

idle: リクエストが開始されていない（例：{ immediate: false } またはサーバーレンダリング時の { server: false }）
pending: リクエストが進行中
success: リクエストが正常に完了
error: リクエストが失敗

サーバー上でデータをフェッチしていない場合 (例えば、server: false を使用した場合)、データはハイドレーションが完了するまでフェッチされません。これは、クライアント側で useFetch を await しても、<script setup> 内では data が null のままであることを意味します。

例

Docs > 4 X > Examples > Advanced > Use Custom Fetch Composable でライブの例を読み、編集します。

Docs > 4 X > Examples > Features > Data Fetching でライブの例を読み、編集します。

お役に立ちましたか？

問題を報告またはGitHub でこのページを編集

useError

useError composableは、処理中のグローバルなNuxtエラーを返します。

useHead

useHead は、Nuxt アプリケーションの個々のページのheadプロパティをカスタマイズします。