Dentro de tus páginas, componentes y plugins puedes usar useAsyncData para acceder a datos que se resuelven de manera asíncrona.

Uso

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

Watch Params

La opción watch incorporada permite volver a ejecutar automáticamente la función fetcher cuando se detectan cambios.

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

Claves Reactivas

Puedes usar un ref computado, un ref simple o una función getter como clave, permitiendo la obtención dinámica de datos que se actualiza automáticamente cuando la clave cambia:

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

// Cuando la ruta cambia y userId se actualiza, los datos se volverán a obtener automáticamente
const { data: user } = useAsyncData(
  userId,
  () => fetchUserById(route.params.id)
)

Parámetros

• key: una clave única para asegurar que la obtención de datos pueda ser correctamente desduplicada a través de las solicitudes. Si no proporcionas una clave, se generará una clave única para el nombre del archivo y el número de línea de la instancia de useAsyncData.
• handler: una función asíncrona que debe devolver un valor verdadero (por ejemplo, no debe ser undefined o null) o la solicitud puede duplicarse en el lado del cliente.

• options:
  • server: si se deben obtener los datos en el servidor (por defecto es true)
  • lazy: si se debe resolver la función asíncrona después de cargar la ruta, en lugar de bloquear la navegación del lado del cliente (por defecto es false)
  • immediate: cuando se establece en false, evitará que la solicitud se dispare inmediatamente. (por defecto es true)
  • default: una función de fábrica para establecer el valor predeterminado de data, antes de que la función asíncrona se resuelva - útil con la opción lazy: true o immediate: false
  • transform: una función que puede ser utilizada para alterar el resultado de la función handler después de resolver
  • getCachedData: Proporciona una función que devuelve datos en caché. Un valor de retorno null o undefined desencadenará una obtención. Por defecto, esto es:

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

    Que solo almacena datos en caché cuando experimental.payloadExtraction de nuxt.config está habilitado.
  • pick: solo selecciona claves especificadas en este array del resultado de la función handler
  • watch: observa fuentes reactivas para auto-refrescar
  • deep: devuelve datos en un objeto ref profundo (es true por defecto). Puede establecerse en false para devolver datos en un objeto ref superficial, lo que puede mejorar el rendimiento si tus datos no necesitan ser profundamente reactivos.
  • dedupe: evita obtener la misma clave más de una vez a la vez (por defecto es cancel). Opciones posibles:
    • cancel - cancela solicitudes existentes cuando se realiza una nueva
    • defer - no realiza nuevas solicitudes en absoluto si hay una solicitud pendiente

Estado Compartido y Consistencia de Opciones

Cuando usas la misma clave para múltiples llamadas a useAsyncData, compartirán los mismos refs data, error y status. Esto asegura consistencia a través de los componentes pero requiere consistencia de opciones.

Las siguientes opciones deben ser consistentes en todas las llamadas con la misma clave:

• Función handler
• Opción deep
• Función transform
• Array pick
• Función getCachedData
• Valor default

Las siguientes opciones pueden diferir sin desencadenar advertencias:

• server
• lazy
• immediate
• dedupe
• watch

// ❌ Esto desencadenará una advertencia de desarrollo
const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { deep: false })
const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { deep: true })

// ✅ Esto está 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: el resultado de la función asíncrona que se pasa.
• refresh/execute: una función que puede ser utilizada para refrescar los datos devueltos por la función handler.
• error: un objeto de error si la obtención de datos falló.
• status: una cadena que indica el estado de la solicitud de datos:
  • idle: cuando la solicitud no ha comenzado, como:
    • cuando execute aún no ha sido llamado y { immediate: false } está establecido
    • cuando se renderiza HTML en el servidor y { server: false } está establecido
  • pending: la solicitud está en progreso
  • success: la solicitud se ha completado con éxito
  • error: la solicitud ha fallado
• clear: una función que puede ser utilizada para establecer data en undefined (o el valor de options.default() si se proporciona), establecer error en null, establecer status en idle, y marcar cualquier solicitud pendiente actual como cancelada.

Por defecto, Nuxt espera hasta que un refresh haya terminado antes de que pueda ser ejecutado de nuevo.

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 = {
  /** La razón para esta solicitud de datos */
  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'