Skip to content

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。服务建议在客户端交互处理器或生命周期中调用,容器遮罩则可直接在模板中使用指令。

ts
// 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 | HTMLElementdocument.body
body是否追加到 body 容器booleanfalse
fullscreen是否渲染为全屏固定遮罩booleantrue
lock是否锁定目标容器滚动booleanfalse
text加载提示文本stringundefined
spinner自定义图标、组件或 VNodestring | Component | VNodeundefined
background自定义遮罩背景色stringundefined
customClass额外附加到遮罩上的类名stringundefined
glass是否启用玻璃风格遮罩booleanfalse
color加载器颜色、渐变色或颜色映射string | string[] | Record<string, string>undefined
dot是否启用点状加载风格booleanfalse
spinnerType内置加载动画类型LoadingSpinnerType'circle'
themeOverrides组件级主题变量覆盖ComponentThemeVarsundefined

指令属性 ​

名称说明类型
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-indexLoading 遮罩层级2000

类型导出 ​

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

Released under the MIT License.