Este composable fornece um wrapper conveniente em torno de useAsyncData e $fetch. Ele gera automaticamente uma chave com base na URL e nas opções de busca, fornece dicas de tipo para a URL da solicitação com base nas rotas do servidor e infere o tipo de resposta da API.

Uso

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

Usando a opção query, você pode adicionar parâmetros de busca à sua consulta. Esta opção é estendida de unjs/ofetch e usa unjs/ufo para criar a URL. Objetos são automaticamente convertidos em strings.

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

O exemplo acima resulta em https://api.nuxt.com/modules?param1=value1&param2=value2.

Você também pode usar interceptores:

const { data, status, error, refresh, clear } = await useFetch('/api/auth/login', {
  onRequest({ request, options }) {
    // Defina os cabeçalhos da solicitação
    // note que isso depende do ofetch >= 1.4.0 - você pode precisar atualizar seu lockfile
    options.headers.set('Authorization', '...')
  },
  onRequestError({ request, options, error }) {
    // Lide com os erros da solicitação
  },
  onResponse({ request, response, options }) {
    // Processe os dados da resposta
    localStorage.setItem('token', response._data.token)
  },
  onResponseError({ request, response, options }) {
    // Lide com os erros da resposta
  }
})

Chaves Reativas e Estado Compartilhado

Você pode usar um ref computado ou um ref simples como a URL, permitindo a busca de dados dinâmica que atualiza automaticamente quando a URL muda:

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

// Quando a rota muda e o id é atualizado, os dados serão automaticamente buscados novamente
const { data: post } = await useFetch(() => `/api/posts/${id.value}`)

Ao usar useFetch com a mesma URL e opções em vários componentes, eles compartilharão os mesmos refs data, error e status. Isso garante consistência entre os componentes.

Tipo

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 = {
  /** A razão para esta solicitação de dados */
  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'

Parâmetros

• URL (string | Request | Ref<string | Request> | () => string | Request): A URL ou solicitação a ser buscada. Pode ser uma string, um objeto Request, um ref do Vue ou uma função que retorna uma string/Request. Suporta reatividade para endpoints dinâmicos.

• options (objeto): Configuração para a solicitação de busca. Estende as opções de unjs/ofetch e AsyncDataOptions. Todas as opções podem ser um valor estático, um ref ou um valor computado.

getCachedData padrão:

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

Isso só armazena dados em cache quando experimental.payloadExtraction no nuxt.config está habilitado.

Valores de Retorno

Valores de Status

• idle: Solicitação não foi iniciada (por exemplo, { immediate: false } ou { server: false } na renderização do servidor)
• pending: Solicitação está em andamento
• success: Solicitação concluída com sucesso
• error: Solicitação falhou

Exemplos