u

code/g3soft-libs/docs/content/ui/5.feedback/spin.md

@@ -0,0 +1,90 @@
+---
+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` 下会变成静态（保留图形、停止旋转），避免诱发不适。