1. 为什么需要二次封装v-loading指令在Vue3ElementPlus的项目开发中v-loading指令是使用频率极高的一个功能组件。它能够为指定区域添加加载状态提升用户体验。但原生指令在实际业务场景中往往存在以下痛点样式定制困难ElementPlus默认的loading样式可能与项目UI规范不符每次使用都需要重复覆盖样式功能扩展不足缺少自动错误处理、延迟加载等常见业务需求支持API不够友好需要手动管理loading状态在复杂场景下容易造成状态混乱复用性差相同配置需要在多个组件中重复声明我在最近一个后台管理系统的开发中发现项目中竟然有87处v-loading的使用其中60%以上需要定制加载文案或图标。这促使我决定对v-loading进行二次封装实现以下目标统一加载样式符合项目设计规范简化API调用支持一行代码实现复杂逻辑内置常用功能扩展如自动错误处理、请求重试提供全局配置和局部覆盖能力2. 封装方案设计与技术选型2.1 基础架构设计二次封装的核心思路是创建一个高阶指令组件它应该继承ElementPlus v-loading的全部功能通过Vue的自定义指令API进行扩展支持全局默认配置和组件级覆盖提供更语义化的API技术实现上我们需要使用Vue3的directiveAPI创建自定义指令利用app.config.globalProperties注入全局方法通过TypeScript增强类型提示采用Composition API组织代码逻辑2.2 核心功能扩展点基于实际项目经验我规划了以下增强功能样式统一管理通过SCSS变量控制加载图标、背景色、文字样式智能状态管理自动绑定异步操作状态无需手动切换loading错误处理机制捕获异常并显示友好提示支持重试回调防抖与延迟避免快速切换导致的闪烁问题多场景预设提供全屏加载、局部加载、按钮加载等预设模式3. 实现步骤详解3.1 项目结构与初始化首先创建指令文件结构/src/directives/ ├── loading/ │ ├── index.ts # 主入口文件 │ ├── types.ts # 类型定义 │ ├── config.ts # 默认配置 │ └── LoadingService.ts # 核心逻辑安装必要依赖npm install lodash-es element-plus3.2 核心逻辑实现在LoadingService.ts中我们创建核心服务类import { LoadingInstance } from element-plus import { debounce } from lodash-es class LoadingService { private instance: LoadingInstance | null null private options: ILoadingOptions constructor(options: ILoadingOptions) { this.options { text: 加载中..., background: rgba(0, 0, 0, 0.5), delay: 300, ...options } } // 显示加载状态 show debounce((el: HTMLElement) { if (this.instance) return this.instance ElLoading.service({ target: el, ...this.options }) }, this.options.delay) // 隐藏加载状态 hide() { this.instance?.close() this.instance null } // 自动绑定Promise状态 watchPromise(el: HTMLElement, promise: Promiseany) { this.show(el) promise.finally(() this.hide()) } }3.3 自定义指令实现在index.ts中注册全局指令import { App, Directive } from vue import LoadingService from ./LoadingService import { defaultOptions } from ./config const loadingDirective: Directive { mounted(el, binding) { const service new LoadingService({ ...defaultOptions, ...(binding.value?.options || {}) }) el._loadingService service if (binding.value?.promise) { service.watchPromise(el, binding.value.promise) } }, updated(el, binding) { if (binding.value?.promise) { el._loadingService?.watchPromise(el, binding.value.promise) } }, unmounted(el) { el._loadingService?.hide() delete el._loadingService } } export default { install(app: App) { app.directive(loading, loadingDirective) // 注入全局方法 app.config.globalProperties.$loading (options) { return new LoadingService(options) } } }3.4 类型增强在types.ts中定义类型import { LoadingOptions } from element-plus import { DirectiveBinding } from vue export interface ILoadingOptions extends LoadingOptions { delay?: number } export interface ILoadingBinding { promise?: Promiseany options?: PartialILoadingOptions } declare module vue/runtime-core { interface ComponentCustomProperties { $loading: (options: ILoadingOptions) LoadingService } }4. 高级功能实现4.1 自动错误处理扩展watchPromise方法加入错误处理watchPromise(el: HTMLElement, promise: Promiseany) { this.show(el) promise .then(() { // 可在这里添加成功提示 }) .catch((error) { this.showError(el, error) }) .finally(() { this.hide() }) } private showError(el: HTMLElement, error: any) { // 创建错误提示元素 const errorEl document.createElement(div) errorEl.className loading-error errorEl.innerHTML div classerror-content i classel-icon-warning/i span${error.message || 加载失败}/span button classretry-btn重试/button /div // 添加到原容器 el.appendChild(errorEl) // 重试按钮事件 errorEl.querySelector(.retry-btn)?.addEventListener(click, () { el.removeChild(errorEl) this.retryCallback?.() }) }4.2 预设场景支持在config.ts中定义预设配置export const presets { fullscreen: { fullscreen: true, lock: true, text: 系统处理中..., background: rgba(255, 255, 255, 0.9) }, button: { target: .el-button, text: , spinner: el-icon-loading, background: transparent }, table: { target: .el-table__body-wrapper, text: 数据加载中..., spinner: el-icon-loading } } export type LoadingPreset keyof typeof presets5. 实际应用示例5.1 基本使用方式template div v-loadingisLoading/div !-- 绑定Promise自动管理状态 -- div v-loading{ promise: fetchData() }/div !-- 使用预设配置 -- el-button v-loading{ promise: submitForm(), options: { preset: button } } 提交 /el-button /template5.2 全局配置修改在main.ts中import loadingDirective from /directives/loading const app createApp(App) app.use(loadingDirective, { defaultOptions: { spinner: custom-spinner-class, text: 请稍候..., background: rgba(0, 0, 0, 0.7) } })5.3 复杂场景示例script setup const handleComplexOperation async () { try { const result await $loading({ preset: fullscreen, text: 正在处理大数据... }).watchPromise( fetchBigData() ) // 处理结果... } catch (error) { // 错误已由指令自动处理 } } /script6. 性能优化与注意事项6.1 性能优化技巧防抖处理快速切换loading状态时避免频繁渲染show debounce((el: HTMLElement) { // 实现代码... }, 300)单例模式确保同一元素只有一个loading实例if (this.instance) return内存管理在unmounted钩子中清理资源unmounted(el) { el._loadingService?.hide() delete el._loadingService }6.2 常见问题解决z-index冲突// 在全局配置中设置比项目最高z-index更大的值 defaultOptions: { zIndex: 9999 }SSR兼容问题mounted(el, binding) { if (typeof window undefined) return // ... }动态内容高度计算// 在显示loading前确保容器有最小高度 if (el.clientHeight 100) { el.style.minHeight 100px }7. 样式定制技巧7.1 SCSS变量覆盖创建loading.scss文件$--loading-spinner-size: 42px !default; $--loading-fullscreen-spinner-size: 64px !default; $--loading-text-color: #409EFF !default; $--loading-spinner-color: $--loading-text-color !default; .el-loading-spinner { .circular { animation: loading-rotate 2s linear infinite; } .path { stroke-dasharray: 90, 150; stroke-dashoffset: 0; stroke-width: 3; stroke: $--loading-spinner-color; stroke-linecap: round; animation: loading-dash 1.5s ease-in-out infinite; } } keyframes loading-rotate { 100% { transform: rotate(360deg); } } keyframes loading-dash { 0% { stroke-dasharray: 1, 200; stroke-dashoffset: 0; } 50% { stroke-dasharray: 90, 150; stroke-dashoffset: -40px; } 100% { stroke-dasharray: 90, 150; stroke-dashoffset: -120px; } }7.2 自定义加载动画替换默认的旋转图标app.use(loadingDirective, { defaultOptions: { spinner: div classcustom-spinner div classbounce1/div div classbounce2/div div classbounce3/div /div , customClass: custom-loading } })配套CSS.custom-spinner { width: 70px; text-align: center; } .custom-spinner div { width: 18px; height: 18px; background-color: #409EFF; border-radius: 100%; display: inline-block; animation: sk-bouncedelay 1.4s infinite ease-in-out both; } .custom-spinner .bounce1 { animation-delay: -0.32s; } .custom-spinner .bounce2 { animation-delay: -0.16s; } keyframes sk-bouncedelay { 0%, 80%, 100% { transform: scale(0); } 40% { transform: scale(1.0); } }
1. 为什么需要二次封装v-loading指令在Vue3ElementPlus的项目开发中v-loading指令是使用频率极高的一个功能组件。它能够为指定区域添加加载状态提升用户体验。但原生指令在实际业务场景中往往存在以下痛点样式定制困难ElementPlus默认的loading样式可能与项目UI规范不符每次使用都需要重复覆盖样式功能扩展不足缺少自动错误处理、延迟加载等常见业务需求支持API不够友好需要手动管理loading状态在复杂场景下容易造成状态混乱复用性差相同配置需要在多个组件中重复声明我在最近一个后台管理系统的开发中发现项目中竟然有87处v-loading的使用其中60%以上需要定制加载文案或图标。这促使我决定对v-loading进行二次封装实现以下目标统一加载样式符合项目设计规范简化API调用支持一行代码实现复杂逻辑内置常用功能扩展如自动错误处理、请求重试提供全局配置和局部覆盖能力2. 封装方案设计与技术选型2.1 基础架构设计二次封装的核心思路是创建一个高阶指令组件它应该继承ElementPlus v-loading的全部功能通过Vue的自定义指令API进行扩展支持全局默认配置和组件级覆盖提供更语义化的API技术实现上我们需要使用Vue3的directiveAPI创建自定义指令利用app.config.globalProperties注入全局方法通过TypeScript增强类型提示采用Composition API组织代码逻辑2.2 核心功能扩展点基于实际项目经验我规划了以下增强功能样式统一管理通过SCSS变量控制加载图标、背景色、文字样式智能状态管理自动绑定异步操作状态无需手动切换loading错误处理机制捕获异常并显示友好提示支持重试回调防抖与延迟避免快速切换导致的闪烁问题多场景预设提供全屏加载、局部加载、按钮加载等预设模式3. 实现步骤详解3.1 项目结构与初始化首先创建指令文件结构/src/directives/ ├── loading/ │ ├── index.ts # 主入口文件 │ ├── types.ts # 类型定义 │ ├── config.ts # 默认配置 │ └── LoadingService.ts # 核心逻辑安装必要依赖npm install lodash-es element-plus3.2 核心逻辑实现在LoadingService.ts中我们创建核心服务类import { LoadingInstance } from element-plus import { debounce } from lodash-es class LoadingService { private instance: LoadingInstance | null null private options: ILoadingOptions constructor(options: ILoadingOptions) { this.options { text: 加载中..., background: rgba(0, 0, 0, 0.5), delay: 300, ...options } } // 显示加载状态 show debounce((el: HTMLElement) { if (this.instance) return this.instance ElLoading.service({ target: el, ...this.options }) }, this.options.delay) // 隐藏加载状态 hide() { this.instance?.close() this.instance null } // 自动绑定Promise状态 watchPromise(el: HTMLElement, promise: Promiseany) { this.show(el) promise.finally(() this.hide()) } }3.3 自定义指令实现在index.ts中注册全局指令import { App, Directive } from vue import LoadingService from ./LoadingService import { defaultOptions } from ./config const loadingDirective: Directive { mounted(el, binding) { const service new LoadingService({ ...defaultOptions, ...(binding.value?.options || {}) }) el._loadingService service if (binding.value?.promise) { service.watchPromise(el, binding.value.promise) } }, updated(el, binding) { if (binding.value?.promise) { el._loadingService?.watchPromise(el, binding.value.promise) } }, unmounted(el) { el._loadingService?.hide() delete el._loadingService } } export default { install(app: App) { app.directive(loading, loadingDirective) // 注入全局方法 app.config.globalProperties.$loading (options) { return new LoadingService(options) } } }3.4 类型增强在types.ts中定义类型import { LoadingOptions } from element-plus import { DirectiveBinding } from vue export interface ILoadingOptions extends LoadingOptions { delay?: number } export interface ILoadingBinding { promise?: Promiseany options?: PartialILoadingOptions } declare module vue/runtime-core { interface ComponentCustomProperties { $loading: (options: ILoadingOptions) LoadingService } }4. 高级功能实现4.1 自动错误处理扩展watchPromise方法加入错误处理watchPromise(el: HTMLElement, promise: Promiseany) { this.show(el) promise .then(() { // 可在这里添加成功提示 }) .catch((error) { this.showError(el, error) }) .finally(() { this.hide() }) } private showError(el: HTMLElement, error: any) { // 创建错误提示元素 const errorEl document.createElement(div) errorEl.className loading-error errorEl.innerHTML div classerror-content i classel-icon-warning/i span${error.message || 加载失败}/span button classretry-btn重试/button /div // 添加到原容器 el.appendChild(errorEl) // 重试按钮事件 errorEl.querySelector(.retry-btn)?.addEventListener(click, () { el.removeChild(errorEl) this.retryCallback?.() }) }4.2 预设场景支持在config.ts中定义预设配置export const presets { fullscreen: { fullscreen: true, lock: true, text: 系统处理中..., background: rgba(255, 255, 255, 0.9) }, button: { target: .el-button, text: , spinner: el-icon-loading, background: transparent }, table: { target: .el-table__body-wrapper, text: 数据加载中..., spinner: el-icon-loading } } export type LoadingPreset keyof typeof presets5. 实际应用示例5.1 基本使用方式template div v-loadingisLoading/div !-- 绑定Promise自动管理状态 -- div v-loading{ promise: fetchData() }/div !-- 使用预设配置 -- el-button v-loading{ promise: submitForm(), options: { preset: button } } 提交 /el-button /template5.2 全局配置修改在main.ts中import loadingDirective from /directives/loading const app createApp(App) app.use(loadingDirective, { defaultOptions: { spinner: custom-spinner-class, text: 请稍候..., background: rgba(0, 0, 0, 0.7) } })5.3 复杂场景示例script setup const handleComplexOperation async () { try { const result await $loading({ preset: fullscreen, text: 正在处理大数据... }).watchPromise( fetchBigData() ) // 处理结果... } catch (error) { // 错误已由指令自动处理 } } /script6. 性能优化与注意事项6.1 性能优化技巧防抖处理快速切换loading状态时避免频繁渲染show debounce((el: HTMLElement) { // 实现代码... }, 300)单例模式确保同一元素只有一个loading实例if (this.instance) return内存管理在unmounted钩子中清理资源unmounted(el) { el._loadingService?.hide() delete el._loadingService }6.2 常见问题解决z-index冲突// 在全局配置中设置比项目最高z-index更大的值 defaultOptions: { zIndex: 9999 }SSR兼容问题mounted(el, binding) { if (typeof window undefined) return // ... }动态内容高度计算// 在显示loading前确保容器有最小高度 if (el.clientHeight 100) { el.style.minHeight 100px }7. 样式定制技巧7.1 SCSS变量覆盖创建loading.scss文件$--loading-spinner-size: 42px !default; $--loading-fullscreen-spinner-size: 64px !default; $--loading-text-color: #409EFF !default; $--loading-spinner-color: $--loading-text-color !default; .el-loading-spinner { .circular { animation: loading-rotate 2s linear infinite; } .path { stroke-dasharray: 90, 150; stroke-dashoffset: 0; stroke-width: 3; stroke: $--loading-spinner-color; stroke-linecap: round; animation: loading-dash 1.5s ease-in-out infinite; } } keyframes loading-rotate { 100% { transform: rotate(360deg); } } keyframes loading-dash { 0% { stroke-dasharray: 1, 200; stroke-dashoffset: 0; } 50% { stroke-dasharray: 90, 150; stroke-dashoffset: -40px; } 100% { stroke-dasharray: 90, 150; stroke-dashoffset: -120px; } }7.2 自定义加载动画替换默认的旋转图标app.use(loadingDirective, { defaultOptions: { spinner: div classcustom-spinner div classbounce1/div div classbounce2/div div classbounce3/div /div , customClass: custom-loading } })配套CSS.custom-spinner { width: 70px; text-align: center; } .custom-spinner div { width: 18px; height: 18px; background-color: #409EFF; border-radius: 100%; display: inline-block; animation: sk-bouncedelay 1.4s infinite ease-in-out both; } .custom-spinner .bounce1 { animation-delay: -0.32s; } .custom-spinner .bounce2 { animation-delay: -0.16s; } keyframes sk-bouncedelay { 0%, 80%, 100% { transform: scale(0); } 40% { transform: scale(1.0); } }
