이 composable은 useAsyncData와 $fetch를 편리하게 감싸는 래퍼를 제공합니다. URL과 fetch 옵션에 기반하여 자동으로 키를 생성하고, 서버 경로에 기반한 요청 URL에 대한 타입 힌트를 제공하며, API 응답 타입을 추론합니다.

사용법

const { data, status, error, refresh, clear } = await useFetch('/api/modules', {
  pick: ['title']
})

query 옵션을 사용하여 쿼리에 검색 매개변수를 추가할 수 있습니다. 이 옵션은 unjs/ofetch에서 확장되었으며, URL을 생성하기 위해 unjs/ufo를 사용합니다. 객체는 자동으로 문자열로 변환됩니다.

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 }) {
    // 요청 헤더 설정
    // 이는 ofetch >= 1.4.0에 의존하므로, lockfile을 새로 고쳐야 할 수 있습니다.
    options.headers.set('Authorization', '...')
  },
  onRequestError({ request, options, error }) {
    // 요청 오류 처리
  },
  onResponse({ request, response, options }) {
    // 응답 데이터 처리
    localStorage.setItem('token', response._data.token)
  },
  onResponseError({ request, response, options }) {
    // 응답 오류 처리
  }
})

반응형 키와 공유 상태

URL로 계산된 ref 또는 일반 ref를 사용할 수 있으며, URL이 변경될 때 자동으로 업데이트되는 동적 데이터 페칭을 허용합니다:

const route = useRoute()
const id = computed(() => route.params.id)

// 라우트가 변경되고 id가 업데이트되면 데이터가 자동으로 다시 가져옵니다.
const { data: post } = await useFetch(() => `/api/posts/${id.value}`)

여러 컴포넌트에서 동일한 URL과 옵션으로 useFetch를 사용하는 경우, 동일한 data, error, status ref를 공유합니다. 이는 컴포넌트 간의 일관성을 보장합니다.

타입

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, ctx: AsyncDataRequestContext) => DataT | undefined
  deep?: boolean
  dedupe?: 'cancel' | 'defer'
  default?: () => DataT
  transform?: (input: DataT) => DataT | Promise<DataT>
  pick?: string[]
  watch?: WatchSource[] | false
}

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'

매개변수

• URL (string | Request | Ref<string | Request> | () => string | Request): 가져올 URL 또는 요청. 문자열, Request 객체, Vue ref, 또는 문자열/Request를 반환하는 함수일 수 있습니다. 동적 엔드포인트에 대한 반응성을 지원합니다.

• options (object): fetch 요청에 대한 구성. unjs/ofetch 옵션과 AsyncDataOptions를 확장합니다. 모든 옵션은 정적 값, ref, 또는 계산된 값일 수 있습니다.

getCachedData 기본값:

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

이는 nuxt.config에서 experimental.payloadExtraction이 활성화된 경우에만 데이터를 캐시합니다.

반환 값

상태 값

• idle: 요청이 시작되지 않음 (예: { immediate: false } 또는 서버 렌더링 시 { server: false })
• pending: 요청이 진행 중
• success: 요청이 성공적으로 완료됨
• error: 요청 실패

예시