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

title, description

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

Spin 加载中

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

何时使用

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

基础用法

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

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

独立使用

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

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

延迟显示

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

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

使用建议

<!-- 推荐：局部冻结，用户知道「正在刷新的是哪一块」 -->
<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	—	自定义文案内容

类型定义

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