Vant 4 Loading 加载组件实战指南类型切换、尺寸颜色、插槽与主题定制全解析【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant导读Loading 加载组件是 Vant 移动端 UI 库中负责表达加载中过渡状态的基础反馈组件常用于列表下拉刷新、表单提交、页面初始化等场景。本文以 Loading 官方文档 为主体结合 组件源码、样式实现 与 单元测试系统讲解它的引入方式、6 类典型用法、全部 Props/Slots 参数、底层渲染原理以及基于 CSS 变量的主题定制方案帮助你在真实业务中快速接入并按需定制。一、组件定位与引入方式Loading 组件用于展示加载中的过渡状态本身不承载业务逻辑通过开箱即用的默认样式降低接入成本。它支持两种内置动画形态circular 圆形描边、spinner 线性旋转也允许通过插槽完全替换默认图标。在 Vue 3 项目中可以通过以下方式全局注册组件更多注册方式参考 组件注册import { createApp } from vue; import { Loading } from vant; const app createApp(); app.use(Loading);注册完成后即可在模板中直接使用van-loading /。组件内部通过 withInstall 完成安装逻辑并在 index.ts 中声明了全局组件类型VanLoading让 Vue 的模板类型提示开箱即用。如果你只在一个页面中使用也可以选择按需局部导入import { Loading } from vant; // 在 setup 中返回后即可在模板中使用 Loading /二、代码演示六类典型用法以下用法与官方文档演示一一对应完整可运行的 Demo 可参考 demo/index.vue。1. 加载类型type通过type属性设置加载图标的类型默认为circular可选值为spinnervan-loading / van-loading typespinner /两者的差异在源码中非常直观Loading.tsx 预定义了两种图标——SpinIcon由 12 根旋转线段组成CircularIcon则是一个带描边的 SVG 圆环渲染时根据type二选一const DefaultIcon props.type spinner ? SpinIcon : CircularIcon;2. 自定义颜色color通过color属性设置加载图标的颜色van-loading color#1989fa / van-loading typespinner color#1989fa /在源码中color被直接注入到 spinner 容器的行内样式中并通过currentColor传递给线条或描边见 index.less因此无需操作 SVG 内部即可统一换色。3. 自定义大小size通过size属性设置加载图标的大小默认单位为px可传数字或带单位的字符串van-loading size24 / van-loading typespinner size24px /size的数值在运行时经getSizeStyle处理纯数字自动拼接px字符串原样透传支持%、vw、rem等任意合法 CSS 单位实现逻辑见 format.ts。测试用例也验证了size{20}时最终渲染宽高为20px见 index.spec.ts。4. 加载文案default 插槽使用默认插槽可以在图标的右侧插入加载文案van-loading size24px加载中.../van-loading5. 垂直排列vertical设置vertical属性后图标与文案会由水平排列切换为垂直居中排列van-loading size24px vertical加载中.../van-loading样式上垂直模式将容器切换为flex-direction: column并调整文案间距见 index.less--vertical { display: flex; flex-direction: column; align-items: center; .van-loading__text { margin: var(--van-padding-xs) 0 0; } }6. 自定义文案颜色与自定义图标文案颜色有两种控制粒度!-- 同时修改文案和加载图标的颜色 -- van-loading color#0094ff / !-- 只修改文案颜色 -- van-loading text-color#0094ff /二者优先级关系在源码中有明确体现Loading.tsx 中文案的颜色计算为props.textColor ?? props.color即text-color优先、color兜底对应测试用例验证了两种属性同时传入时文案最终使用textColor见 index.spec.ts。自定义图标通过icon插槽实现插槽存在时默认图标会被整体替换van-loading vertical template #icon van-icon namestar-o size30 / /template 加载中... /van-loading三、API 参考Props参数说明类型默认值color颜色string#c9c9c9type类型可选值为spinnerstringcircularsize加载图标大小默认单位为pxnumber | string30pxtext-size文字大小默认单位为pxnumber | string14pxtext-color文字颜色string#c9c9c9vertical是否垂直排列图标和文字内容booleanfalse从源码 loadingProps 可以看到各 Prop 的类型约束size与textSize使用numericProp即[Number, String]联合类型见 props.tstype使用makeStringPropLoadingType(circular)限定为circular | spinner两个合法值color、textColor为普通字符串vertical为布尔值。textSize最终经addUnit处理为带单位的值后再注入文案样式。Slots名称说明default加载文案icon自定义加载图标注意文案渲染是可选的——只有传入default插槽时组件才会渲染.van-loading__text节点见 Loading.tsx因此纯图标场景不会产生多余的 DOM 与默认样式干扰。类型定义组件导出以下类型定义方便在 TypeScript 项目中约束传参import type { LoadingType, LoadingProps } from vant;其中LoadingType即circular | spinnerLoadingProps由loadingProps经ExtractPropTypes推导而来见 Loading.tsx二者均在 index.ts 中对外导出。四、源码级实现原理1. 两种内置图标如何构建spinner线性旋转SpinIcon通过Array(12).fill(null).map(...)生成 12 个i元素每个元素对应一个类名van-loading__line--n。样式层使用 Less 循环.generate-spinner(12)为每一根线生成不同的旋转角度与透明度见 index.less再配合steps(12)的步进动画实现逐格闪烁的经典菊花效果。circular圆形描边CircularIcon是一个viewBox25 25 50 50的内联 SVG圆形描边通过stroke-dasharray/stroke-dashoffset关键帧动画van-circular见 index.less形成不断收放旋转的弧线效果。2. 动画节奏如何控制容器.van-loading__spinner默认执行van-rotate旋转动画时长由 CSS 变量--van-loading-spinner-duration默认0.8s控制而spinner类型额外声明animation-timing-function: steps(12)与 12 根线段一一对应circular类型则将动画时长拉长到2s见 index.less保证两种形态的视觉转速协调。3. 无障碍与语义支持组件根节点内置了aria-livepolite与aria-busy{true}见 Loading.tsx便于读屏软件感知加载状态属于移动端组件中少有的无障碍细节迁移到含文案的场景时值得保留。4. 测试如何覆盖关键行为单元测试 覆盖了四条核心链路size影响 spinner 宽高、text-size影响文案字号、text-color与color对文案颜色的影响及优先级。如果你在业务中封装自定义 Loading 包装组件可参照该测试结构对尺寸单位透传颜色优先级两个高风险点做回归验证。五、主题定制CSS 变量与全局配置组件在 index.less 的:root中声明了以下样式变量可在任意层级覆盖以实现主题定制配合 ConfigProvider 组件 可实现运行时全局换肤名称默认值描述--van-loading-text-colorvar(--van-text-color-2)文案颜色--van-loading-text-font-sizevar(--van-font-size-md)文案字号--van-loading-spinner-colorvar(--van-gray-5)图标颜色--van-loading-spinner-size30px图标尺寸--van-loading-spinner-duration0.8s旋转动画时长例如将图标放大并换成品牌色:root { --van-loading-spinner-size: 40px; --van-loading-spinner-color: #1989fa; }对应 TypeScript 侧组件导出了LoadingThemeVars类型见 types.ts五个字段与上述 CSS 变量一一对应方便在配置类型推导时保持变量名不漂移。由于这些变量依赖--van-text-color-2、--van-font-size-md、--van-gray-5等全局基础变量若要整体更换设计规范建议先通过主题配置文件统一调整基础变量再按需覆盖 Loading 自身的变量。六、适用场景与注意事项何时使用按钮提交中、列表加载更多、下拉刷新、页面首屏初始化等需要表达进行中的过渡场景需要文案时配合默认插槽需要图标替换时使用icon插槽。大小与单位size与text-size均支持数字自动补px与带单位字符串如24px、2rem、50%百分比在容器为块级布局时可能受父级影响建议优先使用固定单位。颜色优先级文案颜色遵循text-color优先、color兜底若两者都未设置文案与图标默认均为#c9c9c9可通过样式变量统一调整。动画性能spinner 类型由 12 个 DOM 节点组成circular 为单个 SVG在低频刷新场景下两者差异可忽略若在滚动容器内高频使用circular 类型节点更少可作为优先选择。至此从引入注册、六类用法、Props/Slots 全参数到源码渲染原理与 CSS 变量主题定制Loading 组件的完整使用链路已经打通。其余如列表下拉刷新等场景的组合用法可结合 List 组件 的loading状态一起接入。【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考