Spin 加载中

用于页面、卡片或局部区域的加载反馈。YH-UI 的 Spin 采用极简设计，不仅支持标准的 SVG 动画，还提供了动感的点状（Dot）模式。

基础用法

提供标准 SVG 动画，有多种尺寸可选，也支持显式传入数字像素值。

尺寸选项

点状模式

借鉴业内优秀组件库的 4 点旋转模式，视觉更加灵动且具备节奏感。

Dot 模式

旗舰级动效

除了基础的环形动画，YhSpin 还提供了多种旗舰级的 SVG 动效，满足不同场景下的视觉审美需求。

动效类型

描述文字与排列

支持添加描述文字，并可切换水平或垂直排列。

描述文字

色彩定制

支持自定义颜色，甚至可以传入 CSS 渐变值来实现更高级的视觉效果。

色彩定制

Glass 遮罩模式

通过 glass 属性可以开启全屏或局部区域的高斯模糊遮罩效果，常用于页面重要操作后的状态锁定。

Glass 遮罩

延迟显示 (防闪烁)

对于某些响应极快的请求（如 < 100ms），如果立即显示加载动画，可能会造成视觉上的“闪烁”不适感。通过 delay 属性可以设置延迟显示时间。

延迟显示

容器场景 (高级用法)

可以将 Spin 作为容器组件使用，包裹其他内容。当 show 为 true 时，容器会自动进入加载状态并应用高斯模糊。

容器包裹

自定义插槽

通过 tip 插槽可以完全自定义描述文字区域的内容。

插槽自定义

在 Nuxt 中使用

Spin 完全兼容 Nuxt 3/4 环境。在 Nuxt 项目中，组件会自动导入，您可以配合 useFetch 等异步 API 轻松实现全屏或局部加载效果。

Nuxt 使用示例

SSR 渲染表现

Spin 组件在 SSR 服务端渲染时默认不会渲染 Spinner 动画，直到客户端 Hydration 完成后才会根据状态显示，确保不影响首屏解析性能。

API

Props

属性名	说明	类型	默认值
show	是否开启加载状态	boolean	true
tip	描述文字	string	-
size	尺寸，支持关键词或自定义 px 长度	'small' | 'default' | 'large' | number	'default'
vertical	是否垂直排列图标与文字	boolean	false
delay	延迟显示时间 (ms)，防闪烁	number	0
glass	是否开启全屏 glass 遮罩模式	boolean	false
dot	是否使用点状动画逻辑	boolean	false
type	加载动画样式类型。可选：circle, chaser, gear, dual-ring, rect	LoadingSpinnerType	'circle'
color	自定义颜色 (支持十六进制、RGB、CSS 渐变字符串或渐变配置对象)	string | string[] | Record<string, string>	-

Events

事件名	说明	参数
show	加载状态显示时触发	-
hide	加载状态隐藏时触发	-

Slots

插槽名	说明
default	包裹的内容。若存在此插槽，Spin 将作为容器模式运行
tip	自定义描述文字区域

Expose

名称	说明	类型
visible	当前动画是否处于可见状态	ComputedRef<boolean>

主题变量 (CSS Variables)

组件支持通过以下变量自定义特定样式：

变量名	说明	默认值
--yh-spin-color	加载图标的基础颜色	var(--yh-color-primary)
--yh-spin-blur-radius	容器模式下的模糊半径	8px
--yh-spin-mask-bg	容器模式下的遮罩背景色	rgba(255, 255, 255, 0.4)
--yh-spin-mask-bg-dark	暗色模式下的遮罩背景色	rgba(0, 0, 0, 0.3)
--yh-spin-gradient	渐变模式下的 CSS 背景值	-

类型导出

名称	说明
YhSpinProps	组件 Props 类型
YhSpinEmits	组件事件类型
YhSpinSlots	组件插槽类型
YhSpinExpose	组件 expose 类型
YhLoadingSpinnerType	内置加载动画联合类型
YhSpinInstance	组件实例类型