useAsyncData

Вы можете использовать useAsyncData на страницах, в компонентах и плагинах, чтобы получить доступ к данным, которые разрешаются асинхронно.

Использование

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

Наблюдение за параметрами

Встроенный параметр watch позволяет автоматически повторно выполнять функцию-загрузчик при обнаружении любых изменений.

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

Reactive Keys

You can use a computed ref, plain ref or a getter function as the key, allowing for dynamic data fetching that automatically updates when the key changes:

<script setup lang="ts">
const route = useRoute()
const userId = computed(() => `user-${route.params.id}`)

// When the route changes and userId updates, the data will be automatically refetched
const { data: user } = useAsyncData(
  userId,
  () => fetchUserById(route.params.id)
)
</script>

Параметры

• key: уникальный ключ, который гарантирует, что получение данных может быть правильно дедуплицировано между запросами. Если вы не предоставляете ключ, то ключ, уникальный для имени файла и номера строки экземпляра useAsyncData, будет сгенерирован для вас.
• handler: асинхронная функция, которая должна возвращать истинное значение (например, она не должна быть undefined или null), иначе запрос может быть дублирован на клиенте.
  The handler function should be side-effect free to ensure predictable behavior during SSR and CSR hydration. If you need to trigger side effects, use the callOnce utility to do so.
• options:
  • server: параметр, определяющий, следует ли получать данные на сервере (по умолчанию true)
  • lazy: параметр, определяющий, следует ли разрешать асинхронную функцию после загрузки маршрута, вместо блокировки навигации на клиенте. (по умолчанию false)
  • immediate: если установить значение false, это предотвратит немедленное выполнение запроса. (по умолчанию true)
  • default: функция-фабрика для установки значения по умолчанию для data перед тем, как асинхронная функция будет разрешена. Это полезно при использовании параметров lazy: true или immediate: false.
  • transform: функция, которая может быть использована для изменения результата функции-обработчика после ее разрешения.
  • getCachedData: Provide a function which returns cached data. A null or undefined return value will trigger a fetch. By default, this is:

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

    Which only caches data when experimental.payloadExtraction of nuxt.config is enabled.
  • pick: only pick specified keys in this array from the handler function result
  • watch: watch reactive sources to auto-refresh
  • deep: return data in a deep ref object (it is true by default). It can be set to false to return data in a shallow ref object, which can improve performance if your data does not need to be deeply reactive.
  • dedupe: избегайте получения одного и того же ключа более одного раза за раз (по умолчанию cancel). Возможные параметры:
    • cancel - отменяет существующие запросы при поступлении нового
    • defer - вообще не делает новых запросов, если есть отложенный запрос

Shared State and Option Consistency

When using the same key for multiple useAsyncData calls, they will share the same data, error and status refs. This ensures consistency across components but requires option consistency.

The following options must be consistent across all calls with the same key:

• handler function
• deep option
• transform function
• pick array
• getCachedData function
• default value

The following options can differ without triggering warnings:

• server
• lazy
• immediate
• dedupe
• watch

// ❌ This will trigger a development warning
const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { deep: false })
const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { deep: true })

// ✅ This is allowed
const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { immediate: true })
const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { immediate: false })

Возвращаемые значения

• data: результат работы переданной асинхронной функции.
• refresh/execute: функция, которая может быть использована для обновления данных, возвращенных функцией handler.
• error: объект ошибки, если получение данных не удалось.
• status: строка, указывающая на статус запроса данных:
  • idle: when the request has not started, such as:
    • when execute has not yet been called and { immediate: false } is set
    • when rendering HTML on the server and { server: false } is set
  • pending: the request is in progress
  • success: the request has completed successfully
  • error: the request has failed
• clear: a function that can be used to set data to undefined (or the value of options.default() if provided), set error to null, set status to idle, and mark any currently pending requests as cancelled.

По умолчанию Nuxt ждет, пока refresh не будет завершен, прежде чем его можно будет выполнить снова.

Тип

function useAsyncData<DataT, DataE>(
  handler: (nuxtApp?: NuxtApp) => Promise<DataT>,
  options?: AsyncDataOptions<DataT>
): AsyncData<DataT, DataE>
function useAsyncData<DataT, DataE>(
  key: MaybeRefOrGetter<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?: MultiWatchSources | false
  getCachedData?: (key: string, nuxtApp: NuxtApp, ctx: AsyncDataRequestContext) => DataT | undefined
}

type AsyncDataRequestContext = {
  /** The reason for this data request */
  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'