企业官网建设流程全解析

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，可选值为spinner：

<van-loading /> <van-loading type="spinner" />

两者的差异在源码中非常直观：Loading.tsx 预定义了两种图标——SpinIcon由 12 根旋转线段组成，CircularIcon则是一个带描边的 SVG 圆环，渲染时根据type二选一：

const DefaultIcon = props.type === 'spinner' ? SpinIcon : CircularIcon;

2. 自定义颜色（color）

通过color属性设置加载图标的颜色：

<van-loading color="#1989fa" /> <van-loading type="spinner" color="#1989fa" />

在源码中，color被直接注入到 spinner 容器的行内样式中，并通过currentColor传递给线条或描边（见 index.less），因此无需操作 SVG 内部即可统一换色。

3. 自定义大小（size）

通过size属性设置加载图标的大小，默认单位为px，可传数字或带单位的字符串：

<van-loading size="24" /> <van-loading type="spinner" size="24px" />

size的数值在运行时经getSizeStyle处理：纯数字自动拼接px，字符串原样透传（支持%、vw、rem等任意合法 CSS 单位），实现逻辑见 format.ts。测试用例也验证了size={20}时最终渲染宽高为20px（见 index.spec.ts）。

4. 加载文案（default 插槽）

使用默认插槽可以在图标的右侧插入加载文案：

<van-loading size="24px">加载中...</van-loading>

5. 垂直排列（vertical）

设置vertical属性后，图标与文案会由水平排列切换为垂直居中排列：

<van-loading size="24px" 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 name="star-o" size="30" /> </template> 加载中... </van-loading>

三、API 参考

Props

从源码 loadingProps 可以看到各 Prop 的类型约束：size与textSize使用numericProp（即[Number, String]联合类型，见 props.ts），type使用makeStringProp<LoadingType>('circular')限定为'circular' | 'spinner'两个合法值；color、textColor为普通字符串，vertical为布尔值。textSize最终经addUnit处理为带单位的值后再注入文案样式。

Slots

注意：文案渲染是可选的——只有传入default插槽时组件才会渲染.van-loading__text节点（见 Loading.tsx），因此纯图标场景不会产生多余的 DOM 与默认样式干扰。

类型定义

组件导出以下类型定义，方便在 TypeScript 项目中约束传参：

import type { LoadingType, LoadingProps } from 'vant';

其中LoadingType即'circular' | 'spinner'，LoadingProps由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是一个viewBox="25 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-live="polite"与aria-busy={true}（见 Loading.tsx），便于读屏软件感知加载状态，属于移动端组件中少有的无障碍细节，迁移到含文案的场景时值得保留。

4. 测试如何覆盖关键行为

单元测试 覆盖了四条核心链路：size影响 spinner 宽高、text-size影响文案字号、text-color与color对文案颜色的影响及优先级。如果你在业务中封装自定义 Loading 包装组件，可参照该测试结构对"尺寸单位透传""颜色优先级"两个高风险点做回归验证。

五、主题定制：CSS 变量与全局配置

组件在 index.less 的:root中声明了以下样式变量，可在任意层级覆盖以实现主题定制，配合 ConfigProvider 组件 可实现运行时全局换肤：

例如，将图标放大并换成品牌色：

: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