---
title: "useLazyApiFetch"
description: "懒加载版 useApiFetch，不阻塞客户端导航，页面立即显示。"
seo_title: "useLazyApiFetch"
seo_description: "Lazy variant of useApiFetch — defers fetching until referenced, ideal for non-blocking client navigation."
canonical_url: "https://nuxt.mhaibaraai.cn/docs/api/use-lazy-api-fetch"
---
# useLazyApiFetch

> 懒加载版 useApiFetch，不阻塞客户端导航，页面立即显示。

## 用法

使用自动导入的 `useLazyApiFetch` composable 进行 API 请求，等价于 `useApiFetch(url, { ...options, lazy: true })`。lazy 模式下请求不会阻塞客户端导航，页面立即显示，数据在后台加载。

```vue
<script setup lang="ts">
interface User {
  id: number
  name: string
  email: string
}

// 懒加载用户数据
const { data, status } = useLazyApiFetch<User[]>('/users')
</script>

<template>
  <div>
    <div v-if="status === 'pending'">
      加载中...
    </div>
    <div v-else-if="status === 'error'">
      加载失败
    </div>
    <div v-else-if="data">
      <div v-for="user in data" :key="user.id">
        {{ user.name }}
      </div>
    </div>
  </div>
</template>
```

- `useLazyApiFetch` 不会阻塞客户端导航，适合非关键数据（如用户列表、评论等）。
- 客户端导航时 `data` 初始为 `null`，`status` 为 `'pending'`，需要处理加载状态。
- 继承 `useApiFetch` 的所有功能（认证、Toast、业务状态码检查等）。

> \[\!NOTE\]
> 
> 对于首屏必需的数据，应使用 
> 
> useApiFetch
> 
> （非 lazy 模式），以阻塞导航确保数据就绪。

> \[\!TIP\]
> See: /docs/api/use-api-fetch
> 
> 完整的 API 选项和功能说明请参考 
> 
> useApiFetch
> 
>  文档

## 示例

页面先渲染、随后进入 pending，`data` 在拿到响应前为 `null`，需配合 `pending` / `status` 处理加载态：

```vue [ApiQuickstartLazyExample.vue]
<script setup lang="ts">
interface Profile {
  id: string
  name: string
  email: string
}

const { data, pending, error, refresh } = useLazyApiFetch<Profile>('/profile')
</script>

<template>
  <div class="flex flex-col gap-3">
    <div class="flex items-center gap-2 flex-wrap">
      <UBadge v-if="pending" color="warning" variant="subtle">
        pending
      </UBadge>
      <UBadge v-else-if="error" color="error" variant="subtle">
        error
      </UBadge>
      <UBadge v-else color="success" variant="subtle">
        ready
      </UBadge>
      <UButton size="sm" variant="outline" icon="i-lucide-refresh-cw" @click="refresh()">
        刷新
      </UButton>
    </div>
    <p class="text-xs text-muted">
      lazy 模式：页面先渲染再进入 pending；data 在拿到响应前为 null
    </p>
    <pre class="text-xs p-3 rounded bg-elevated overflow-auto">{{ error ? { error: error.message } : data }}</pre>
  </div>
</template>
```

## API

### useLazyApiFetch()

`useLazyApiFetch<T = unknown, DataT = T>(url: string | (() => string), options?: UseApiFetchOptions<T, DataT>): UseApiFetchReturn<DataT>`

创建懒加载的 API 请求。

#### Parameters

**url** (`string | (() => string)`) *required*: 请求 URL 或返回 URL 的函数。支持响应式 URL。

**options** (`UseApiFetchOptions<T, DataT>`): 请求配置选项。支持所有 useApiFetch 的选项。\[\!NOTE\]lazy 选项会被强制设为 true，无需手动指定。

#### Type Parameters

**T** (`type`): 业务数据类型（已由 $api 自动解包）。

**DataT** (`type`): transform 转换后的最终类型。默认等于 T。

#### Returns

返回值与 [`useApiFetch`](/docs/api/use-api-fetch#returns) 相同。

## Changelog

See commit history for [src/runtime/composables/useLazyApiFetch.ts](https://github.com/mhaibaraai/movk-nuxt/commits/main/src/runtime/composables/useLazyApiFetch.ts).


## Sitemap

See the full [sitemap](/sitemap.md) for all pages.