useFetch

Этот композабл представляет собой удобную обертку для useAsyncData и $fetch. Он автоматически генерирует ключ на основе URL и параметров выборки, предоставляет подсказки типов для url-запроса на основе маршрутов сервера и определяет тип ответа API.

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

<script setup lang="ts">
const { data, status, error, refresh, clear } = await useFetch('/api/modules', {
  pick: ['title']
})
</script>

Используя свойство query, вы можете добавить параметры поиска в запрос. Эта опция расширена из unjs/ofetch и использует unjs/ufo для создания URL. Объекты автоматически превращаются в строку.

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 }) {
    // Устанавливает заголовки запроса
    options.headers = options.headers || {}
    options.headers.authorization = '...'
  },
  onRequestError({ request, options, error }) {
    // Обрабатывает ошибки запроса
  },
  onResponse({ request, response, options }) {
    // Обрабатывает данные ответа
    localStorage.setItem('token', response._data.token)
  },
  onResponseError({ request, response, options }) {
    // Обрабатывает ошибки ответа
  }
})

Параметры

• URL: URL-адрес для получения данных.
• Options (расширяет опции unjs/ofetch и опции AsyncData):
  • method: Метод запроса.
  • query: Добавляет query-параметры запроса к URL с помощью ufo.
  • params: Псевдоним для query.
  • body: Тело запроса - автоматически превращается в строку (если передан объект).
  • headers: Заголовки запроса.
  • baseURL: Базовый URL для запроса.
  • timeout: Миллисекунды для автоматического прерывания запроса.
  • cache: Управляет кэшем в соответствии с Fetch API.
    • Вы можете передать boolean, чтобы отключить кэш, или передать одно из следующих значений: default, no-store, reload, no-cache, force-cache и only-if-cached.

• Options (из useAsyncData):
  • key: Уникальный ключ для обеспечения правильной дедупликации данных в запросах. Если ключ не указан, он будет сгенерирован автоматически на основе URL и параметров запроса.
  • server: Следует ли получать данные на сервере (по умолчанию true).
  • lazy: Разрешать ли async-функцию после загрузки маршрута, чтобы не блокировать навигацию на стороне клиента (по умолчанию false).
  • immediate: Если установить значение false, то запрос не будет выполняться немедленно. (по умолчанию true).
  • default: Фабричная функция для установки значения по умолчанию для data перед разрешением async-функции - полезно при использовании опции lazy: true или immediate: false.
  • transform: Функция, которая может быть использована для изменения результата функции handler после разрешения.
  • getCachedData: Функция, которая возвращает кэшированные данные. Возвращаемое значение null или undefined будет перевыполнять запрос. По умолчанию это: key => nuxt.isHydrating ? nuxt.payload.data[key] : nuxt.static.data[key], которая кэширует данные, только если включено payloadExtraction.
  • pick: Выбор из результата функции handler только указанныx в этом массиве ключей.
  • watch: Следит за массивом реактивных источников и автоматически обновляет данные при их изменении. По умолчанию отслеживаются параметры запроса и URL. Вы можете полностью игнорировать реактивные источники, используя watch: false. Вместе с immediate: false это позволяет использовать useFetch полностью в ручном режиме. (Пример использования watch можно посмотреть здесь).
  • deep: Возвращает данные в виде глубокого ref-объекта. Для повышения производительности по умолчанию используется значение false для возврата данных в виде shallow-ref объекта.
  • dedupe: Позволяет избегать получения одного и того же ключа более одного раза за вызов (по умолчанию cancel). Возможные опции:
    • cancel - Отменяет существующие запросы при выполнении нового.
    • defer - не делает новых запросов вообще, если есть ожидающий запрос.

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

• data: результат работы переданной асинхронной функции.
• refresh/execute: функция, которая может быть использована для обновления данных, возвращенных функцией handler.
• error: объект ошибки, если запрос данных не удался.
• status: строка, указывающая на статус запроса данных ("idle", "pending", "success", "error").
• clear: функция, которая установит data в undefined, error в null, pending в false, status в "idle", и пометит все текущие запросы как отмененные.

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

Тип

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

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'