Vant Loading 加载组件完全指南类型、尺寸、颜色与自定义图标实战【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant导读Loading 是 Vant 移动端组件库中用于展示加载中过渡状态的轻量级组件在数据请求、页面初始化、按钮提交等场景中广泛使用。本文基于 Vant 仓库中的 Loading 官方文档结合 Loading.tsx 源码、样式实现、测试用例 与 演示代码系统讲解组件的安装方式、全部 Props 参数、两个内置加载图标类型、文字排版与自定义图标插槽的完整用法并深入剖析 CSS 变量主题定制机制。读完本文你将能够在实际项目中熟练、规范地使用与定制 Loading 组件。组件简介Loading 组件用于在页面或局部区域加载数据时向用户提示正在加载的过渡状态。它默认渲染为一个旋转的圆环circular 类型也可切换为 12 段式菊花 spinner 风格并支持任意颜色、尺寸调整以及通过插槽完全替换加载图标。从源码结构看该组件由以下文件构成文件职责Loading.tsx组件核心实现定义 Props 与渲染逻辑index.less样式与 CSS 变量定义、旋转动画index.ts组件注册导出与 TS 类型导出types.tsLoadingThemeVars主题变量类型demo/index.vue官方演示页test/index.spec.ts单元测试安装与注册组件注册Loading 组件可以通过app.use进行全局注册import { createApp } from vue; import { Loading } from vant; const app createApp(); app.use(Loading);更多注册方式如局部注册、按需自动导入可参考 组件注册文档。从 index.ts 源码 可以看到组件通过withInstall包装后导出同时挂载了loadingProps以及LoadingType、LoadingProps、LoadingThemeVars等类型并声明了全局组件VanLoading因此注册后可直接在模板中使用van-loading。按需导入类型组件额外导出以下类型定义供 TypeScript 项目按需引入import type { LoadingType, LoadingProps } from vant;基础用法加载类型typeLoading 内置两种加载图标circular默认圆环样式与spinner菊花样式van-loading / van-loading typespinner /从 Loading.tsx 源码 可以看出两种图标的内置实现方式circular一个带van-loading__circular类名的svg圆环配合van-circular关键帧动画通过stroke-dasharray的变化呈现转圈效果spinner由 12 个i classvan-loading__line元素构成通过van-rotate动画 steps(12)的步进动画函数每一段线条依次旋转并淡出形成菊花旋转效果。对应的LoadingType联合类型定义为circular | spinner见 Loading.tsx。自定义颜色color通过color属性可同时改变图标与文字的默认颜色van-loading color#1989fa / van-loading typespinner color#1989fa /该属性在源码中会作用于 spinner 容器的内联color样式而图标线条、圆环均使用currentColor继承因此一处设置即可整体换色见 index.less 与 Loading.tsx。自定义大小size通过size属性控制图标大小支持数字自动补px或带单位的字符串van-loading size24 / van-loading typespinner size24px /源码中size与textSize均使用numericProp[Number, String]见 utils/props.ts最终由getSizeStyle统一转换为带px单位的宽高样式见 utils/format.ts。测试用例验证了size: 20时 spinner 的宽高均为20px见 test/index.spec.ts。加载文案default 插槽在标签内写入内容即可展示加载文字van-loading size24pxLoading.../van-loading垂直排列vertical默认情况下图标与文字水平排列设置vertical属性后改为垂直居中排列适合按钮下方或页面底部居中的加载场景van-loading size24px verticalLoading.../van-loading垂直模式下组件根节点使用flex-direction: column布局文字与图标间距由--van-padding-xs控制见 index.less。文字颜色text-color默认情况下color同时作用于图标与文字。若只想单独修改文字颜色可使用text-color属性!-- 图标和文字颜色都会改变 -- van-loading color#0094ff / !-- 只改变文字颜色 -- van-loading text-color#0094ff /从 Loading.tsx 源码 可以看到文字颜色的优先级逻辑text-color存在时优先使用它否则回退到color。测试用例对此有明确覆盖同时传入color与textColor时文字颜色取textColor见 test/index.spec.ts。自定义图标icon 插槽当内置的两种图标无法满足需求时可通过icon插槽完全替换加载图标例如结合 Vant 的 Icon 组件使用任意图标van-loading vertical template #icon van-icon namestar-o size30 / /template Loading... /van-loading源码中渲染图标时会优先判断是否存在icon插槽存在则渲染插槽内容否则回退到内置默认图标见 Loading.tsx。API 参考Props参数说明类型默认值color加载图标的颜色string#c9c9c9type类型可设置为spinnerstringcircularsize图标大小number | string30pxtext-size文字字号number | string14pxtext-color文字颜色string#c9c9c9vertical是否垂直排列图标与文字booleanfalse补充说明依据 loadingProps 定义size、text-size传数字时内部通过addUnit自动补充px单位见 utils/format.ts若不传color图标颜色取自 CSS 变量--van-loading-spinner-color默认var(--van-gray-5)即视觉上为浅灰色text-color的默认回退值为color两者均未设置时文字使用--van-loading-text-color。Slots名称说明default加载文案icon自定义加载图标Types组件导出LoadingType与LoadingProps两个类型定义见 index.ts其中LoadingProps由loadingProps通过ExtractPropTypes推导而来保证了运行时 Props 与类型定义的单一来源一致性。主题定制CSS 变量Loading 组件提供以下 CSS 变量用于自定义样式配合 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旋转动画时长样式实现原理这些变量定义于 index.less并贯穿整个组件样式根节点.van-loading的颜色继承自--van-loading-spinner-color同时设置font-size: 0以消除图标与文字之间内联元素换行带来的空隙.van-loading__spinner的宽高取--van-loading-spinner-size并执行van-rotate无限旋转动画其中spinner类型使用steps(12)步进动画实现逐格跳动效果circular类型的动画时长固定为2s见 index.lesscircular圆环本身通过van-circular关键帧动画改变stroke-dasharray与stroke-dashoffset营造出圆环滚动的视觉效果见 index.less12 条 spinner 线条由 Less 递归generate-spinner(12)生成每条线旋转i * 30deg透明度按1 - (0.75 / 12) * (i - 1)递减形成渐变淡出的菊花形态见 index.less。对应的LoadingThemeVars类型定义在 types.tsTS 项目可借助该类型获得主题变量的强类型提示。使用示例van-loading size36px text-size16px color#1989fa style--van-loading-spinner-duration: 1.2s 加载中... /van-loading无障碍与可访问性组件根节点默认带有aria-livepolite与aria-busy{true}属性见 Loading.tsx可向屏幕阅读器等辅助技术声明区域正处于加载状态在移动端体验设计中是一个值得留意的细节。源码实现要点与测试验证渲染逻辑Loading.tsx 的核心渲染流程如下通过createNamespace(loading)生成 BEM 风格的类名前缀van-loading根据type选择SpinIcon12 条线或CircularIconSVG 圆环作为默认图标若提供icon插槽优先渲染插槽内容替换默认图标若提供default插槽渲染文字节点文字样式取textSize与textColor ?? color根节点根据type与vertical组合类名van-loading--spinner/circular及van-loading--vertical。测试覆盖test/index.spec.ts 中的单元测试验证了以下行为size属性正确改变 spinner 的宽高数字自动补pxtext-size属性正确改变文字字号text-color属性正确改变文字颜色color属性在未传text-color时同样作用于文字颜色color与text-color同时传入时文字颜色以text-color为准。此外demo.spec.ts 与 demo-ssr.spec.ts 分别对演示页做了常规渲染与 SSR 场景的快照测试保证组件在服务端渲染环境下同样稳定可用。常见问题1.size传数字与字符串有什么区别两者等价。数字会被自动补全为px单位如24→24px字符串需自行携带单位如1rem、24px。2. 为什么设置了color但文字颜色没变color会同时作用于图标与文字。如果文字颜色没有变化请检查是否同时设置了text-color——该属性优先级更高会覆盖color对文字的作用。3. 如何让加载图标更小或更大直接使用size属性即可同时注意样式中max-width: 100%/max-height: 100%的限制见 index.less若容器过小图标会被等比约束。4. 动画太快或太慢通过 CSS 变量--van-loading-spinner-duration调整旋转动画时长默认0.8scircular类型的动画时长固定为2s。总结Loading 组件虽然小但在 Loading.tsx 与 index.less 的实现中体现了清晰的层次type决定图标形态color/text-color控制色彩优先级size/text-size统一由addUnit规范化单位icon插槽提供完全的自定义能力CSS 变量则为主题化定制留出标准入口。在实际开发中推荐优先使用官方 Props 与 CSS 变量完成大部分定制需求仅在特殊场景下通过icon插槽替换图标这样既能保持组件行为的可预期性也能获得测试用例与类型定义的双重保障。【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Vant Loading 加载组件完全指南：类型、尺寸、颜色与自定义图标实战
Vant Loading 加载组件完全指南类型、尺寸、颜色与自定义图标实战【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant导读Loading 是 Vant 移动端组件库中用于展示加载中过渡状态的轻量级组件在数据请求、页面初始化、按钮提交等场景中广泛使用。本文基于 Vant 仓库中的 Loading 官方文档结合 Loading.tsx 源码、样式实现、测试用例 与 演示代码系统讲解组件的安装方式、全部 Props 参数、两个内置加载图标类型、文字排版与自定义图标插槽的完整用法并深入剖析 CSS 变量主题定制机制。读完本文你将能够在实际项目中熟练、规范地使用与定制 Loading 组件。组件简介Loading 组件用于在页面或局部区域加载数据时向用户提示正在加载的过渡状态。它默认渲染为一个旋转的圆环circular 类型也可切换为 12 段式菊花 spinner 风格并支持任意颜色、尺寸调整以及通过插槽完全替换加载图标。从源码结构看该组件由以下文件构成文件职责Loading.tsx组件核心实现定义 Props 与渲染逻辑index.less样式与 CSS 变量定义、旋转动画index.ts组件注册导出与 TS 类型导出types.tsLoadingThemeVars主题变量类型demo/index.vue官方演示页test/index.spec.ts单元测试安装与注册组件注册Loading 组件可以通过app.use进行全局注册import { createApp } from vue; import { Loading } from vant; const app createApp(); app.use(Loading);更多注册方式如局部注册、按需自动导入可参考 组件注册文档。从 index.ts 源码 可以看到组件通过withInstall包装后导出同时挂载了loadingProps以及LoadingType、LoadingProps、LoadingThemeVars等类型并声明了全局组件VanLoading因此注册后可直接在模板中使用van-loading。按需导入类型组件额外导出以下类型定义供 TypeScript 项目按需引入import type { LoadingType, LoadingProps } from vant;基础用法加载类型typeLoading 内置两种加载图标circular默认圆环样式与spinner菊花样式van-loading / van-loading typespinner /从 Loading.tsx 源码 可以看出两种图标的内置实现方式circular一个带van-loading__circular类名的svg圆环配合van-circular关键帧动画通过stroke-dasharray的变化呈现转圈效果spinner由 12 个i classvan-loading__line元素构成通过van-rotate动画 steps(12)的步进动画函数每一段线条依次旋转并淡出形成菊花旋转效果。对应的LoadingType联合类型定义为circular | spinner见 Loading.tsx。自定义颜色color通过color属性可同时改变图标与文字的默认颜色van-loading color#1989fa / van-loading typespinner color#1989fa /该属性在源码中会作用于 spinner 容器的内联color样式而图标线条、圆环均使用currentColor继承因此一处设置即可整体换色见 index.less 与 Loading.tsx。自定义大小size通过size属性控制图标大小支持数字自动补px或带单位的字符串van-loading size24 / van-loading typespinner size24px /源码中size与textSize均使用numericProp[Number, String]见 utils/props.ts最终由getSizeStyle统一转换为带px单位的宽高样式见 utils/format.ts。测试用例验证了size: 20时 spinner 的宽高均为20px见 test/index.spec.ts。加载文案default 插槽在标签内写入内容即可展示加载文字van-loading size24pxLoading.../van-loading垂直排列vertical默认情况下图标与文字水平排列设置vertical属性后改为垂直居中排列适合按钮下方或页面底部居中的加载场景van-loading size24px verticalLoading.../van-loading垂直模式下组件根节点使用flex-direction: column布局文字与图标间距由--van-padding-xs控制见 index.less。文字颜色text-color默认情况下color同时作用于图标与文字。若只想单独修改文字颜色可使用text-color属性!-- 图标和文字颜色都会改变 -- van-loading color#0094ff / !-- 只改变文字颜色 -- van-loading text-color#0094ff /从 Loading.tsx 源码 可以看到文字颜色的优先级逻辑text-color存在时优先使用它否则回退到color。测试用例对此有明确覆盖同时传入color与textColor时文字颜色取textColor见 test/index.spec.ts。自定义图标icon 插槽当内置的两种图标无法满足需求时可通过icon插槽完全替换加载图标例如结合 Vant 的 Icon 组件使用任意图标van-loading vertical template #icon van-icon namestar-o size30 / /template Loading... /van-loading源码中渲染图标时会优先判断是否存在icon插槽存在则渲染插槽内容否则回退到内置默认图标见 Loading.tsx。API 参考Props参数说明类型默认值color加载图标的颜色string#c9c9c9type类型可设置为spinnerstringcircularsize图标大小number | string30pxtext-size文字字号number | string14pxtext-color文字颜色string#c9c9c9vertical是否垂直排列图标与文字booleanfalse补充说明依据 loadingProps 定义size、text-size传数字时内部通过addUnit自动补充px单位见 utils/format.ts若不传color图标颜色取自 CSS 变量--van-loading-spinner-color默认var(--van-gray-5)即视觉上为浅灰色text-color的默认回退值为color两者均未设置时文字使用--van-loading-text-color。Slots名称说明default加载文案icon自定义加载图标Types组件导出LoadingType与LoadingProps两个类型定义见 index.ts其中LoadingProps由loadingProps通过ExtractPropTypes推导而来保证了运行时 Props 与类型定义的单一来源一致性。主题定制CSS 变量Loading 组件提供以下 CSS 变量用于自定义样式配合 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旋转动画时长样式实现原理这些变量定义于 index.less并贯穿整个组件样式根节点.van-loading的颜色继承自--van-loading-spinner-color同时设置font-size: 0以消除图标与文字之间内联元素换行带来的空隙.van-loading__spinner的宽高取--van-loading-spinner-size并执行van-rotate无限旋转动画其中spinner类型使用steps(12)步进动画实现逐格跳动效果circular类型的动画时长固定为2s见 index.lesscircular圆环本身通过van-circular关键帧动画改变stroke-dasharray与stroke-dashoffset营造出圆环滚动的视觉效果见 index.less12 条 spinner 线条由 Less 递归generate-spinner(12)生成每条线旋转i * 30deg透明度按1 - (0.75 / 12) * (i - 1)递减形成渐变淡出的菊花形态见 index.less。对应的LoadingThemeVars类型定义在 types.tsTS 项目可借助该类型获得主题变量的强类型提示。使用示例van-loading size36px text-size16px color#1989fa style--van-loading-spinner-duration: 1.2s 加载中... /van-loading无障碍与可访问性组件根节点默认带有aria-livepolite与aria-busy{true}属性见 Loading.tsx可向屏幕阅读器等辅助技术声明区域正处于加载状态在移动端体验设计中是一个值得留意的细节。源码实现要点与测试验证渲染逻辑Loading.tsx 的核心渲染流程如下通过createNamespace(loading)生成 BEM 风格的类名前缀van-loading根据type选择SpinIcon12 条线或CircularIconSVG 圆环作为默认图标若提供icon插槽优先渲染插槽内容替换默认图标若提供default插槽渲染文字节点文字样式取textSize与textColor ?? color根节点根据type与vertical组合类名van-loading--spinner/circular及van-loading--vertical。测试覆盖test/index.spec.ts 中的单元测试验证了以下行为size属性正确改变 spinner 的宽高数字自动补pxtext-size属性正确改变文字字号text-color属性正确改变文字颜色color属性在未传text-color时同样作用于文字颜色color与text-color同时传入时文字颜色以text-color为准。此外demo.spec.ts 与 demo-ssr.spec.ts 分别对演示页做了常规渲染与 SSR 场景的快照测试保证组件在服务端渲染环境下同样稳定可用。常见问题1.size传数字与字符串有什么区别两者等价。数字会被自动补全为px单位如24→24px字符串需自行携带单位如1rem、24px。2. 为什么设置了color但文字颜色没变color会同时作用于图标与文字。如果文字颜色没有变化请检查是否同时设置了text-color——该属性优先级更高会覆盖color对文字的作用。3. 如何让加载图标更小或更大直接使用size属性即可同时注意样式中max-width: 100%/max-height: 100%的限制见 index.less若容器过小图标会被等比约束。4. 动画太快或太慢通过 CSS 变量--van-loading-spinner-duration调整旋转动画时长默认0.8scircular类型的动画时长固定为2s。总结Loading 组件虽然小但在 Loading.tsx 与 index.less 的实现中体现了清晰的层次type决定图标形态color/text-color控制色彩优先级size/text-size统一由addUnit规范化单位icon插槽提供完全的自定义能力CSS 变量则为主题化定制留出标准入口。在实际开发中推荐优先使用官方 Props 与 CSS 变量完成大部分定制需求仅在特殊场景下通过icon插槽替换图标这样既能保持组件行为的可预期性也能获得测试用例与类型定义的双重保障。【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
