---
title: Spin 加载中
description: 包裹内容显示加载遮罩，或作为独立的加载指示器
---

# Spin 加载中

`Spin` 表达「正在加载」。它会**遮罩被包裹的内容并阻止交互**，这是它与只显示图标的纯视觉 loading 的区别。

## 何时使用

- 区域级加载：表格、卡片、表单在请求期间需要冻结交互时；
- 局部刷新：点「重新加载」后只遮住该区域，而不是整页 loading；
- 全局 loading 建议用顶部进度条或 [Message](/ui/feedback/message)，避免整页白屏。

## 基础用法

传默认插槽即「包裹模式」：`spinning` 为 true 时给内容加遮罩并显示指示器。

:::demo{name="spin/basic"}
:::

## 独立使用

不传默认插槽时就是独立指示器，配 `description` 显示加载文案。

:::demo{name="spin/standalone"}
:::

## 延迟显示

`delay` 用来防「闪一下」：请求很快时根本不显示加载态，只有超过 `delay` 才出现。

:::demo{name="spin/delay"}
:::

## 使用建议

```vue
<!-- 推荐：局部冻结，用户知道「正在刷新的是哪一块」 -->
<G3Spin :spinning="loading" :delay="300">
  <DataTable :rows="rows" />
</G3Spin>

<!-- 不推荐：把整页包起来，用户失去上下文 -->
<G3Spin :spinning="loading"><App /></G3Spin>
```

## API

### Props

| 名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `spinning` | `boolean` | `false` | 是否加载中。包裹模式下会显示遮罩并阻止点击；独立模式下控制指示器显隐 |
| `delay` | `number` | `0` | 延迟显示（ms）。请求快于该值时不显示加载态，避免闪烁 |
| `description` | `string` | — | 加载文案，显示在指示器下方 |

### Slots

| 名称 | 参数 | 说明 |
| --- | --- | --- |
| `default` | — | 被遮罩的内容。不传时渲染为独立指示器 |
| `indicator` | — | 自定义指示器（替换默认转圈） |
| `description` | — | 自定义文案内容 |

### 类型定义

```ts
export interface SpinProps {
  spinning?: boolean
  delay?: number
  description?: string
}
```

### 样式变量

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `--g3-spin-size` | `20px` | 指示器尺寸 |
| `--g3-spin-description-gap` | `8px` | 指示器与文案的间距 |
| `--g3-color-primary` | `#18181b` | 指示器颜色 |

## 实现说明

- 遮罩是绝对定位覆盖在内容之上（内容区保持原尺寸，不会因为加载而跳高跳宽），并吃掉点击，避免用户在加载中重复提交；
- 遮罩带 `aria-busy="true"`，屏幕阅读器能感知「该区域忙」，并且不会改变内容的可访问名称；
- `delay` 的计时在 `spinning` 变 true 时启动、变 false 时清除：这样连续多次短请求不会累积显示；
- 转圈动画在 `prefers-reduced-motion: reduce` 下会变成静态（保留图形、停止旋转），避免诱发不适。