Loading 加载

加载数据时显示的遮罩层。具备旗舰级亚克力视觉效果，完美适配 Nuxt 3/4。

Loading 与 Spin 的关系

Loading 是 YH-UI 提供的指令与服务封装，而 Spin 是其核心 UI 组件。

• 底层核心 (Spin)：负责加载动画（SVG/Dot/Chaser/Gear）的视觉呈现与文字排列。它是一个纯粹的 Vue 组件。
• 高层封装 (Loading)：基于 Spin 构建的增强方案，提供了指令与命令式服务，专门用于处理全屏遮罩、锁定滚动、动态挂载等交互。

使用方式

区域加载 (指令版)

通过 v-yh-loading 指令可以快速在宿主元素上覆盖一层加载遮罩。

这里是容器内容

基础用法

指令进阶用法

通过修饰符 .fullscreen、.lock、.glass 以及扩展属性 yh-loading-*，可以实现更复杂的加载交互。

指令全屏与锁定

这里是深色容器背景

指令扩展属性

系统核心看板

正在通过亚克力玻璃滤镜渲染实时数据流...

指令旗舰 Glass 模式

资产管理队列

点状加载模式适配轻量级容器反馈

指令 Dot 模式

自定义深度定制

正在应用 my-custom-mask 类名提供的特殊滤镜...

指令自定义类名

组合式 API (推荐)

在 script setup 中使用 YhLoading.service 是最高效的调用方式。

组合式 API 调用

选项式 API

在非 setup 环境下，可以通过原型上的 $loading 进行调用。

选项式 API 调用

在 Axios 中使用

在实际项目中，通过结合 Axios 拦截器与“引用计数”方案，可以完美处理多个并发请求时的 Loading 状态，确保加载效果平滑。

该计数器方案确保：只有第一个请求会开启 Loading，而直到最后一个并发请求完成后才会关闭，有效防止界面闪烁。

网络请求拦截示例

旗舰级 Loading 样式

借鉴 loading.io 的动感设计。

旗舰动效

自定义色彩方案

支持单色、渐变色数组 or CSS 变量。

多色动效

完全自定义扩展 (VNode/Component)

YH-UI 允许跳过内置样式，通过 spinner 属性注入 any Vue 组件 or VNode，实现完全自主控制 Loading 呈现内容。

自定义 VNode 演示

应用程序上下文

现在 Loading 接受一条 context 作为消息构造器的第二个参数，允许你将当前应用的上下文注入到 Loading 中，这将允许你继承应用程序的所有属性。

TIP

如果您全局注册了 YhLoading 组件，它将自动继承应用的上下文环境。

通过传递 appContext，Loading 内部挂载的组件可以访问到全局注册的插件（如 Pinia、Router）以及全局组件。

应用上下文注入

API

LoadingOptions (Service 配置)

| 属性名 | 说明 | 类型 | 默认值 | | ----------- | ------------------------------------------------------------------- | -------------------- | ------------ | --------------- | --- | | target | 挂载目标。支持 DOM 或 CSS 选择器 | string | HTMLElement | document.body | | body | 是否将遮罩插入至 body 元素（同 target: body） | boolean | false | | fullscreen | 是否全屏 (position: fixed) | boolean | true | | lock | 是否锁定宿主元素的滚动 | boolean | false | | text | 加载文案 | string | - | | glass | 是否开启旗舰模式（亚克力玻璃效果） | boolean | false | | background | 遮罩层背景颜色 | string | - | | customClass | 自定义遮罩层类名 | string | - | | spinner | 自定义图标/组件 (高于 spinnerType) | string | Component | VNode | - | | spinnerType | 加载动画类型。可选：circle, chaser, gear, dual-ring, rect | LoadingSpinnerType | circle | | color | 加载图标颜色，支持渐变色数组或 CSS 变量 | string | string[] | object | - | | dot | 是否使用点状加载样式（Antd 风格） | boolean | false |

指令 Attributes (v-yh-loading)

名称	说明	类型
yh-loading-text	加载文案	string
yh-loading-background	遮罩背景色	string
yh-loading-custom-class	自定义类名	string
yh-loading-glass	是否开启亚克力效果	boolean
yh-loading-dot	是否使用点状模式	boolean
yh-loading-color	图标颜色	string
yh-loading-type	动画类型 (circle, chaser 等)	LoadingSpinnerType

指令 Modifiers (修饰符)

名称	说明
.fullscreen	等同于 fullscreen: true
.lock	等同于 lock: true
.glass	等同于 glass: true

LoadingInstance (服务实例方法)

属性名	说明	类型
service	创建并显示加载遮罩	(options: LoadingOptions, appContext?: AppContext) => LoadingInstance
close	关闭并销毁遮罩实例	() => void
visible	(Readonly) 获取当前遮罩的显示状态	boolean

Slots (通过 spinner 属性注入时可用)

在使用 <yh-spin> 或单独引用组件时，支持以下插槽：

• default: 遮罩宿主内容
• tip: 自定义文字内容
• icon: 替代内置 Loading 图标

主题变量 (CSS Variables)

变量名	说明	默认值
--yh-bg-color-overlay	基础遮罩背景颜色	rgba(255, 255, 255, 0.7)
--yh-spin-blur-radius	亚克力模糊半径	20px
--yh-loading-z-index	遮罩层级	2000