Dentro de suas páginas, componentes e plugins, você pode usar useAsyncData para obter acesso a dados que são resolvidos de forma assíncrona.

Uso

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

Watch Params

A opção watch embutida permite executar automaticamente a função de busca quando quaisquer alterações são detectadas.

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

Chaves Reativas

Você pode usar um ref computado, ref simples ou uma função getter como chave, permitindo a busca dinâmica de dados que atualiza automaticamente quando a chave muda:

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

// Quando a rota muda e userId é atualizado, os dados serão automaticamente buscados novamente
const { data: user } = useAsyncData(
  userId,
  () => fetchUserById(route.params.id)
)

Parâmetros

• key: uma chave única para garantir que a busca de dados possa ser devidamente desduplicada entre as requisições. Se você não fornecer uma chave, uma chave única para o nome do arquivo e número da linha da instância de useAsyncData será gerada para você.
• handler: uma função assíncrona que deve retornar um valor verdadeiro (por exemplo, não deve ser undefined ou null) ou a requisição pode ser duplicada no lado do cliente.

• options:
  • server: se deve buscar os dados no servidor (padrão é true)
  • lazy: se deve resolver a função assíncrona após carregar a rota, em vez de bloquear a navegação no lado do cliente (padrão é false)
  • immediate: quando definido como false, impedirá que a requisição seja disparada imediatamente. (padrão é true)
  • default: uma função de fábrica para definir o valor padrão dos data, antes que a função assíncrona seja resolvida - útil com a opção lazy: true ou immediate: false
  • transform: uma função que pode ser usada para alterar o resultado da função handler após a resolução
  • getCachedData: Forneça uma função que retorne dados em cache. Um valor de retorno null ou undefined acionará uma busca. Por padrão, isso é:

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

    Que só armazena dados em cache quando experimental.payloadExtraction do nuxt.config está habilitado.
  • pick: escolha apenas chaves especificadas neste array do resultado da função handler
  • watch: observe fontes reativas para atualização automática
  • deep: retorne dados em um objeto ref profundo (é true por padrão). Pode ser definido como false para retornar dados em um objeto ref raso, o que pode melhorar o desempenho se seus dados não precisarem ser profundamente reativos.
  • dedupe: evite buscar a mesma chave mais de uma vez ao mesmo tempo (padrão é cancel). Opções possíveis:
    • cancel - cancela requisições existentes quando uma nova é feita
    • defer - não faz novas requisições se já houver uma pendente

Estado Compartilhado e Consistência de Opções

Ao usar a mesma chave para múltiplas chamadas de useAsyncData, elas compartilharão os mesmos refs data, error e status. Isso garante consistência entre os componentes, mas requer consistência de opções.

As seguintes opções devem ser consistentes em todas as chamadas com a mesma chave:

• Função handler
• Opção deep
• Função transform
• Array pick
• Função getCachedData
• Valor default

As seguintes opções podem diferir sem acionar avisos:

• server
• lazy
• immediate
• dedupe
• watch

// ❌ Isso acionará um aviso de desenvolvimento
const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { deep: false })
const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { deep: true })

// ✅ Isso é permitido
const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { immediate: true })
const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { immediate: false })

Valores de Retorno

• data: o resultado da função assíncrona que é passada.
• refresh/execute: uma função que pode ser usada para atualizar os dados retornados pela função handler.
• error: um objeto de erro se a busca de dados falhar.
• status: uma string indicando o status da requisição de dados:
  • idle: quando a requisição não foi iniciada, como:
    • quando execute ainda não foi chamado e { immediate: false } está definido
    • ao renderizar HTML no servidor e { server: false } está definido
  • pending: a requisição está em andamento
  • success: a requisição foi concluída com sucesso
  • error: a requisição falhou
• clear: uma função que pode ser usada para definir data como undefined (ou o valor de options.default() se fornecido), definir error como null, definir status como idle, e marcar quaisquer requisições pendentes como canceladas.

Por padrão, o Nuxt espera até que um refresh seja concluído antes que possa ser executado novamente.

Tipo

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