Loading

用于显示加载遮罩的服务与指令入口。它构建在 YhSpin 之上，主要通过 YhLoading.service(...) 和 v-yh-loading 指令使用。

Loading 与 Spin 的关系

Loading 是构建在 Spin 之上的指令层与服务层，而 Spin 是更底层的视觉加载组件。

• Spin 负责渲染图标、提示文案和加载动画布局。
• Loading 额外提供服务挂载、全屏遮罩、滚动锁定、指令支持以及临时宿主管理能力。

用法

局部 Loading（指令版）

使用 v-yh-loading 指令为宿主元素覆盖一层加载遮罩。

基础用法

高级指令用法

.fullscreen、.lock、.glass 等指令修饰符，配合 yh-loading-* 扩展属性，可以实现更丰富的加载交互。

指令全屏与锁定

指令扩展属性

指令旗舰玻璃模式

指令点状模式

指令自定义类名

组合式 API（推荐）

在 setup 中使用 YhLoading.service 以命令式方式打开和关闭加载遮罩。

组合式 API 调用

选项式 API

安装插件后，也可以通过 $loading 使用同一个服务。

选项式 API 调用

在 Nuxt 中使用

在 Nuxt 3/4 中注册 @yh-ui/nuxt 后即可使用 YhLoading。服务建议在客户端交互处理器或生命周期中调用，容器遮罩则可直接在模板中使用指令。

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

在 Axios 中使用

在真实项目中，建议结合 Axios 拦截器和一个轻量的引用计数器，确保只有最后一个并发请求结束后才关闭遮罩。

网络请求拦截示例

旗舰级 Loading 风格

灵感来自 loading.io 的动态样式。

高级动画

自定义配色方案

支持单色、渐变色数组以及基于 CSS 变量的颜色配置。

多彩动画

完全自定义扩展（VNode 或组件）

传入自定义 spinner，即可用自己的 VNode 或组件替换内置的加载渲染器。

自定义 VNode 示例

应用上下文

YhLoading.service 支持将当前应用上下文作为第二个参数传入，这样服务内部渲染的内容也能继承全局组件和插件。

TIP

如果 YhLoading 已全局安装，那么该服务默认就运行在插件创建的应用上下文中。

应用上下文注入

API

Props

该入口不通过组件 Props 暴露配置，请改用 YhLoading.service(...) 或 v-yh-loading。

Events

该入口不暴露组件事件。

Slots

该入口不是常规模板组件，不提供独立的组件插槽。

Expose

该入口不暴露组件实例 defineExpose 成员，服务能力由 YhLoading.service(...) 返回。

Loading 配置项

属性	说明	类型	默认值
target	挂载目标元素或选择器	string | HTMLElement	document.body
body	是否追加到 body 容器	boolean	false
fullscreen	是否渲染为全屏固定遮罩	boolean	true
lock	是否锁定目标容器滚动	boolean	false
text	加载提示文本	string	undefined
spinner	自定义图标、组件或 VNode	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

指令属性

名称	说明	类型
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

指令修饰符

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

Loading 实例

属性	说明	类型
close	关闭并销毁遮罩	() => void
visible	当前可见状态（只读）	boolean

主题变量

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

类型导出

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