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，而直到最后一个并发请求完成后才会关闭，有效防止界面闪烁。

网络请求拦截示例

在 Nuxt 中使用

接入 @yh-ui/nuxt 后，YhLoading 可在 Nuxt 3/4 中直接使用。指令 v-yh-loading 可直接写在模板中参与 SSR 首屏结构输出；服务调用 YhLoading.service(...) 建议放在点击事件、请求回调或 onMounted 等客户端时机中执行。

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@yh-ui/nuxt']
})

旗舰级 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

Props

当前条目不通过组件 Props 暴露配置项。请通过 YhLoading.service(...) 或 v-yh-loading 使用加载遮罩。

Events

当前条目未暴露组件事件。

Slots

当前条目不是常规模板组件入口，不单独暴露组件插槽。

Expose

当前条目未暴露组件实例 defineExpose 成员；服务能力通过 YhLoading.service(...) 返回的 LoadingInstance 提供。

LoadingOptions (Service 配置)

属性名	说明	类型	默认值
`target`	挂载目标元素或选择器。全屏模式下始终挂载到 `document.body`	`string \| HTMLElement`	`document.body`
`body`	是否追加到 `body` 容器	`boolean`	`false`
`fullscreen`	是否以全屏固定遮罩形式渲染	`boolean`	`true`
`lock`	是否锁定目标元素滚动	`boolean`	`false`
`text`	加载提示文案；未传时回退到 locale 中的 `loading.text`	`string`	`undefined`
`spinner`	自定义图标、组件或 VNode；优先级高于 `spinnerType`	`string \| Component \| VNode`	`undefined`
`background`	自定义遮罩背景色	`string`	`undefined`
`customClass`	追加到遮罩层上的自定义类名	`string`	`undefined`
`glass`	是否启用玻璃态遮罩效果	`boolean`	`false`
`color`	加载图标颜色，支持单色、渐变数组或颜色映射对象	`string \| string[] \| Record<string, string>`	`undefined`
`dot`	是否启用点状加载样式	`boolean`	`false`
`spinnerType`	内置加载动画类型	`LoadingSpinnerType`	`'circle'`
`themeOverrides`	组件级主题变量覆盖	`ComponentThemeVars`	`undefined`

指令 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`	内置动画类型	`LoadingSpinnerType`

指令 Modifiers (修饰符)

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

LoadingInstance (服务实例方法)

属性名	说明	类型
`close`	关闭并销毁当前遮罩实例	`() => void`
`visible`	当前显示状态（只读）	`boolean`

主题变量 (CSS Variables)

变量名	说明	默认值
`--yh-loading-z-index`	加载遮罩层级	`2000`

类型导出

名称	说明
`YhLoadingOptions`	`YhLoading.service(...)` 的配置类型
`YhLoadingInstance`	Loading 服务返回的实例类型
`vYhLoading`	`v-yh-loading` 指令的具名导出

Loading 加载 ​

Loading 与 Spin 的关系 ​

使用方式 ​

区域加载 (指令版) ​

指令进阶用法 ​

系统核心看板

资产管理队列

自定义深度定制

组合式 API (推荐) ​

选项式 API ​

在 Axios 中使用 ​

在 Nuxt 中使用 ​

旗舰级 Loading 样式 ​

自定义色彩方案 ​

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

应用程序上下文 ​

API ​

Props ​

Events ​

Slots ​

Expose ​

LoadingOptions (Service 配置) ​

指令 Attributes (v-yh-loading) ​

指令 Modifiers (修饰符) ​

LoadingInstance (服务实例方法) ​

主题变量 (CSS Variables) ​

类型导出 ​