Vant 4 Skeleton 骨架屏组件完全指南从占位占位到加载完成的实战用法与源码原理【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vantSkeleton骨架屏是 Vant 4 中用于在内容加载过程中展示占位图形的轻量组件它通过一系列灰块模拟页面真实结构避免用户面对空白页面。本文以 Vant 仓库中 Skeleton 官方文档 为核心骨架结合组件源码、样式文件与测试用例系统讲解 Skeleton 的引入方式、五种基础用法、全部 Props 与插槽 API、主题定制方案并深入剖析其底层渲染逻辑与动画实现原理帮助你既能快速上手也能理解其设计思想。组件定位与适用场景Skeleton 骨架屏用于在内容加载过程中展示一组占位图形。它的核心价值在于当页面数据尚未就绪时先用与真实内容轮廓相近的灰色区块占据版面让用户感知到页面正在加载显著缓解等待焦虑。在 Vant 中Skeleton 采用「组合式」设计除了Skeleton主组件外还拆分了四个可独立使用的原子组件SkeletonTitle标题占位图SkeletonParagraph段落占位图SkeletonAvatar头像占位图SkeletonImage图片占位图这种设计允许你像搭积木一样自由拼装自定义的骨架屏结构详见后文「自定义展示内容」与「原子组件」。安装与注册Skeleton 系列组件属于 Vant 组件库的一部分安装 Vant 后即可使用。以全局注册为例需要将主组件与四个原子组件全部注册import { createApp } from vue; import { Skeleton, SkeletonTitle, SkeletonImage, SkeletonAvatar, SkeletonParagraph, } from vant; const app createApp(); app.use(Skeleton); app.use(SkeletonTitle); app.use(SkeletonImage); app.use(SkeletonAvatar); app.use(SkeletonParagraph);从源码看组件通过withInstall包装后默认导出同时 index.ts 中通过declare module vue声明了VanSkeleton的全局组件类型因此全局注册后即可在模板中直接使用van-skeleton标签并获得完整的类型提示。更多注册方式按需引入、unplugin-vue-components 自动导入等可参考 组件注册。代码演示五种核心用法基础用法通过title属性显示标题占位图通过row属性配置占位段落行数van-skeleton title :row3 /row默认为0即不渲染段落占位图title默认为false。因此只写van-skeleton /时组件内部几乎为空实际使用中通常至少指定title或row之一。显示头像通过avatar属性显示头像占位图van-skeleton title avatar :row3 /此时会渲染一个默认32px的圆形头像占位块位于标题与段落占位图的左侧。展示子组件加载完成切换将loading属性设置成false表示内容加载完成此时会隐藏占位图并显示Skeleton的默认插槽子组件内容van-skeleton title avatar :row3 :loadingloading div实际内容/div /van-skeletonimport { ref, onMounted } from vue; export default { setup() { const loading ref(true); onMounted(() { loading.value false; }); return { loading, }; }, };loading默认值为true。这也是骨架屏最常见的落地方式初始化时为true展示占位图数据请求完成后置为false占位图被移除并平滑过渡到真实内容。demo 演示代码 中用一个 Switch 开关来模拟这一加载过程你可以打开官方站点体验实际效果。自定义展示内容通过template插槽完成自定义内容的展示插槽内可以自由组合四个原子组件构造出与页面真实布局一致的骨架结构van-skeleton template #template div :style{ display: flex, width: 100% } van-skeleton-image / div :style{ flex: 1, marginLeft: 16px } van-skeleton-paragraph row-width60% / van-skeleton-paragraph / van-skeleton-paragraph / van-skeleton-paragraph / /div /div /template /van-skeleton上面的例子模拟了一个「左侧图片 右侧多行文字」的典型列表项布局。注意一旦提供了template插槽组件将完全忽略title、avatar、row等占位属性直接渲染插槽内容见下文源码分析。原子组件详解除了直接使用van-skeleton-title、van-skeleton-paragraph、van-skeleton-avatar、van-skeleton-image组合出自定义骨架也可以在其他场景单独使用它们。SkeletonParagraph 段落参数说明类型默认值round是否将段落显示为圆角风格booleanfalserow-width段落占位图宽度string100%SkeletonTitle 标题参数说明类型默认值round是否将标题显示为圆角风格booleanfalsetitle-width标题占位图宽度number | string40%SkeletonAvatar 头像参数说明类型默认值avatar-size头像占位图大小number | string32pxavatar-shape头像占位图形状可选值为squarestringroundSkeletonImage 图片参数说明类型默认值image-size图片占位图大小number | string32pximage-shape图片占位图形状可选值为squarestringsquare说明官方 README 表格中image-shape的默认值标注为round但源码实现中imageShape实际默认为square同时其样式默认值--van-skeleton-image-radius: 24px也为方形圆角设计。实际使用时请以源码行为为准。SkeletonImage内部还会渲染一个photo图标的van-icon源码图标大小与颜色分别由--van-skeleton-image-size和--van-gray-5控制让图片占位图更有辨识度。完整 APISkeleton Props参数说明类型默认值row段落占位图行数number | string0row-width段落占位图宽度可传数组来设置每一行的宽度number | string |(number | string)[]100%title是否显示标题占位图booleanfalseavatar是否显示头像占位图booleanfalseloading是否显示骨架屏传false时会展示子组件内容booleantrueanimate是否开启动画booleantrueround是否将标题和段落显示为圆角风格booleanfalsetitle-width标题占位图宽度number | string40%avatar-size头像占位图大小number | string32pxavatar-shape头像占位图形状可选值为squarestringroundSkeleton Slots名称说明default骨架屏内容template自定义内容default内容加载完成后loading为false展示的真实内容template完全自定义的骨架占位内容优先级高于所有内置占位属性。类型定义组件导出以下类型定义便于在 TypeScript 项目中精确约束 Propsimport type { SkeletonProps, SkeletonImageProps, SkeletonTitleProps, SkeletonImageShape, SkeletonAvatarShape, SkeletonParagraphProps, } from vant;这些类型定义分别来自 Skeleton.tsx、skeleton-paragraph、skeleton-title、skeleton-avatar、skeleton-image 等源文件。主题定制样式变量组件提供了下列 CSS 变量可用于自定义样式使用方法请参考 ConfigProvider 组件。名称默认值描述--van-skeleton-paragraph-height16px---van-skeleton-paragraph-backgroundvar(--van-active-color)---van-skeleton-paragraph-margin-topvar(--van-padding-sm)---van-skeleton-title-width40%---van-skeleton-avatar-size32px---van-skeleton-avatar-backgroundvar(--van-active-color)---van-skeleton-duration1.2s---van-skeleton-image-size96px---van-skeleton-image-radius24px-这些 CSS 变量在各原子组件的 Less 文件中统一定义于:root, :host选择器下方便通过 ConfigProvider 或顶层样式覆盖。例如:root { --van-skeleton-paragraph-height: 20px; --van-skeleton-duration: 0.8s; --van-skeleton-avatar-size: 48px; }从类型定义看types.ts 中的SkeletonThemeVars完整对应了上述变量注意其中SkeletonImageSize、SkeletonImageRadius两个字段名首字母为大写可用于类型安全的主题配置。源码级原理解析渲染分支loading 与插槽的优先级Skeleton.tsx 的主渲染逻辑清晰展示了组件的分支决策当loading为false时直接渲染slots.default真实内容骨架占位图完全卸载当loading为true时先检查是否提供了template插槽——有则直接渲染自定义内容忽略内置属性否则渲染默认结构avatar可选content内含title与row行段落。段落行宽的自动收窄设计一个容易忽略的细节是最后一行段落的宽度。在 getRowWidth 中当rowWidth未显式指定保持默认100%且当前为最后一行index row - 1时宽度自动变为DEFAULT_LAST_ROW_WIDTH即60%当rowWidth传入数组时按行索引取对应值数组元素支持number会被addUnit自动追加单位与带单位的字符串混用例如测试用例中的[100%, 30, 5rem]传入单个值时所有行共用该宽度。这一「最后一行收窄」的视觉设计符合真实段落排版的阅读习惯也是骨架屏看起来更真实的关键细节之一。动画闪烁效果的实现动画由 index.less 中的van-skeleton-blinkkeyframes 实现.van-skeleton { --animate { animation: van-skeleton-blink var(--van-skeleton-duration) ease-in-out infinite; } } keyframes van-skeleton-blink { 50% { opacity: 0.6; } }即在--van-skeleton-duration默认1.2s的一个周期内占位块透明度从1渐变到0.6再恢复形成经典的「呼吸闪烁」效果。设置animate为false即可关闭动画移除van-skeleton--animate类名适合减少低频变化场景或弱网下的动画开销。原子组件的样式实现头像skeleton-avatar/index.less 中round形状通过border-radius: var(--van-radius-max)实现尺寸由getSizeStyle(props.avatarSize)统一设置宽高flex-shrink: 0保证在弹性布局中不被压缩段落skeleton-paragraph/index.less 中非首行段落通过:not(:first-child)加上margin-top: var(--van-skeleton-paragraph-margin-top)自动产生行间距标题SkeletonTitle.tsx 使用h3语义化标签渲染宽度通过内联style.width传入图片skeleton-image/index.less 中内嵌 icon 的尺寸动态取image-size的一半保证图标始终居中且按比例缩放。测试用例验证测试文件 覆盖了组件的核心行为可作为理解语义的参考rowWidth数组渲染验证[100%, 30, 5rem]混合类型的逐行宽度loadingfalse时渲染默认插槽avatarSize传入20rem时宽高均生效avatarShapesquare时头像形状类名切换round属性生成van-skeleton--round类名template插槽渲染自定义内容切换animate属性可动态增删van-skeleton--animate动画类名。实践建议优先复用官方原子组件自定义骨架时组合van-skeleton-title、van-skeleton-avatar、van-skeleton-paragraph、van-skeleton-image即可覆盖绝大多数列表、卡片、详情页布局记住最后一行自动收窄未传row-width时末行固定为60%若需要所有行等宽请显式传入row-width100%用loading统一控制切换将真实内容放在默认插槽配合请求完成回调切换loading即可零成本获得「占位 → 内容」的过渡按需调整动画与圆角弱网或低端设备可将animate置为false并可通过 CSS 变量微调段落高度、头像尺寸与动画时长使骨架屏与设计稿完全对齐。至此你已经掌握了 Vant Skeleton 从 API 使用到源码实现的完整链路可以灵活地在自己的移动端项目中落地骨架屏加载体验。【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/12 13:24:08 · 阅读 1.2k Vant 4 Skeleton 骨架屏组件完全指南：从占位占位到加载完成的实战用法与源码原理
Vant 4 Skeleton 骨架屏组件完全指南从占位占位到加载完成的实战用法与源码原理【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vantSkeleton骨架屏是 Vant 4 中用于在内容加载过程中展示占位图形的轻量组件它通过一系列灰块模拟页面真实结构避免用户面对空白页面。本文以 Vant 仓库中 Skeleton 官方文档 为核心骨架结合组件源码、样式文件与测试用例系统讲解 Skeleton 的引入方式、五种基础用法、全部 Props 与插槽 API、主题定制方案并深入剖析其底层渲染逻辑与动画实现原理帮助你既能快速上手也能理解其设计思想。组件定位与适用场景Skeleton 骨架屏用于在内容加载过程中展示一组占位图形。它的核心价值在于当页面数据尚未就绪时先用与真实内容轮廓相近的灰色区块占据版面让用户感知到页面正在加载显著缓解等待焦虑。在 Vant 中Skeleton 采用「组合式」设计除了Skeleton主组件外还拆分了四个可独立使用的原子组件SkeletonTitle标题占位图SkeletonParagraph段落占位图SkeletonAvatar头像占位图SkeletonImage图片占位图这种设计允许你像搭积木一样自由拼装自定义的骨架屏结构详见后文「自定义展示内容」与「原子组件」。安装与注册Skeleton 系列组件属于 Vant 组件库的一部分安装 Vant 后即可使用。以全局注册为例需要将主组件与四个原子组件全部注册import { createApp } from vue; import { Skeleton, SkeletonTitle, SkeletonImage, SkeletonAvatar, SkeletonParagraph, } from vant; const app createApp(); app.use(Skeleton); app.use(SkeletonTitle); app.use(SkeletonImage); app.use(SkeletonAvatar); app.use(SkeletonParagraph);从源码看组件通过withInstall包装后默认导出同时 index.ts 中通过declare module vue声明了VanSkeleton的全局组件类型因此全局注册后即可在模板中直接使用van-skeleton标签并获得完整的类型提示。更多注册方式按需引入、unplugin-vue-components 自动导入等可参考 组件注册。代码演示五种核心用法基础用法通过title属性显示标题占位图通过row属性配置占位段落行数van-skeleton title :row3 /row默认为0即不渲染段落占位图title默认为false。因此只写van-skeleton /时组件内部几乎为空实际使用中通常至少指定title或row之一。显示头像通过avatar属性显示头像占位图van-skeleton title avatar :row3 /此时会渲染一个默认32px的圆形头像占位块位于标题与段落占位图的左侧。展示子组件加载完成切换将loading属性设置成false表示内容加载完成此时会隐藏占位图并显示Skeleton的默认插槽子组件内容van-skeleton title avatar :row3 :loadingloading div实际内容/div /van-skeletonimport { ref, onMounted } from vue; export default { setup() { const loading ref(true); onMounted(() { loading.value false; }); return { loading, }; }, };loading默认值为true。这也是骨架屏最常见的落地方式初始化时为true展示占位图数据请求完成后置为false占位图被移除并平滑过渡到真实内容。demo 演示代码 中用一个 Switch 开关来模拟这一加载过程你可以打开官方站点体验实际效果。自定义展示内容通过template插槽完成自定义内容的展示插槽内可以自由组合四个原子组件构造出与页面真实布局一致的骨架结构van-skeleton template #template div :style{ display: flex, width: 100% } van-skeleton-image / div :style{ flex: 1, marginLeft: 16px } van-skeleton-paragraph row-width60% / van-skeleton-paragraph / van-skeleton-paragraph / van-skeleton-paragraph / /div /div /template /van-skeleton上面的例子模拟了一个「左侧图片 右侧多行文字」的典型列表项布局。注意一旦提供了template插槽组件将完全忽略title、avatar、row等占位属性直接渲染插槽内容见下文源码分析。原子组件详解除了直接使用van-skeleton-title、van-skeleton-paragraph、van-skeleton-avatar、van-skeleton-image组合出自定义骨架也可以在其他场景单独使用它们。SkeletonParagraph 段落参数说明类型默认值round是否将段落显示为圆角风格booleanfalserow-width段落占位图宽度string100%SkeletonTitle 标题参数说明类型默认值round是否将标题显示为圆角风格booleanfalsetitle-width标题占位图宽度number | string40%SkeletonAvatar 头像参数说明类型默认值avatar-size头像占位图大小number | string32pxavatar-shape头像占位图形状可选值为squarestringroundSkeletonImage 图片参数说明类型默认值image-size图片占位图大小number | string32pximage-shape图片占位图形状可选值为squarestringsquare说明官方 README 表格中image-shape的默认值标注为round但源码实现中imageShape实际默认为square同时其样式默认值--van-skeleton-image-radius: 24px也为方形圆角设计。实际使用时请以源码行为为准。SkeletonImage内部还会渲染一个photo图标的van-icon源码图标大小与颜色分别由--van-skeleton-image-size和--van-gray-5控制让图片占位图更有辨识度。完整 APISkeleton Props参数说明类型默认值row段落占位图行数number | string0row-width段落占位图宽度可传数组来设置每一行的宽度number | string |(number | string)[]100%title是否显示标题占位图booleanfalseavatar是否显示头像占位图booleanfalseloading是否显示骨架屏传false时会展示子组件内容booleantrueanimate是否开启动画booleantrueround是否将标题和段落显示为圆角风格booleanfalsetitle-width标题占位图宽度number | string40%avatar-size头像占位图大小number | string32pxavatar-shape头像占位图形状可选值为squarestringroundSkeleton Slots名称说明default骨架屏内容template自定义内容default内容加载完成后loading为false展示的真实内容template完全自定义的骨架占位内容优先级高于所有内置占位属性。类型定义组件导出以下类型定义便于在 TypeScript 项目中精确约束 Propsimport type { SkeletonProps, SkeletonImageProps, SkeletonTitleProps, SkeletonImageShape, SkeletonAvatarShape, SkeletonParagraphProps, } from vant;这些类型定义分别来自 Skeleton.tsx、skeleton-paragraph、skeleton-title、skeleton-avatar、skeleton-image 等源文件。主题定制样式变量组件提供了下列 CSS 变量可用于自定义样式使用方法请参考 ConfigProvider 组件。名称默认值描述--van-skeleton-paragraph-height16px---van-skeleton-paragraph-backgroundvar(--van-active-color)---van-skeleton-paragraph-margin-topvar(--van-padding-sm)---van-skeleton-title-width40%---van-skeleton-avatar-size32px---van-skeleton-avatar-backgroundvar(--van-active-color)---van-skeleton-duration1.2s---van-skeleton-image-size96px---van-skeleton-image-radius24px-这些 CSS 变量在各原子组件的 Less 文件中统一定义于:root, :host选择器下方便通过 ConfigProvider 或顶层样式覆盖。例如:root { --van-skeleton-paragraph-height: 20px; --van-skeleton-duration: 0.8s; --van-skeleton-avatar-size: 48px; }从类型定义看types.ts 中的SkeletonThemeVars完整对应了上述变量注意其中SkeletonImageSize、SkeletonImageRadius两个字段名首字母为大写可用于类型安全的主题配置。源码级原理解析渲染分支loading 与插槽的优先级Skeleton.tsx 的主渲染逻辑清晰展示了组件的分支决策当loading为false时直接渲染slots.default真实内容骨架占位图完全卸载当loading为true时先检查是否提供了template插槽——有则直接渲染自定义内容忽略内置属性否则渲染默认结构avatar可选content内含title与row行段落。段落行宽的自动收窄设计一个容易忽略的细节是最后一行段落的宽度。在 getRowWidth 中当rowWidth未显式指定保持默认100%且当前为最后一行index row - 1时宽度自动变为DEFAULT_LAST_ROW_WIDTH即60%当rowWidth传入数组时按行索引取对应值数组元素支持number会被addUnit自动追加单位与带单位的字符串混用例如测试用例中的[100%, 30, 5rem]传入单个值时所有行共用该宽度。这一「最后一行收窄」的视觉设计符合真实段落排版的阅读习惯也是骨架屏看起来更真实的关键细节之一。动画闪烁效果的实现动画由 index.less 中的van-skeleton-blinkkeyframes 实现.van-skeleton { --animate { animation: van-skeleton-blink var(--van-skeleton-duration) ease-in-out infinite; } } keyframes van-skeleton-blink { 50% { opacity: 0.6; } }即在--van-skeleton-duration默认1.2s的一个周期内占位块透明度从1渐变到0.6再恢复形成经典的「呼吸闪烁」效果。设置animate为false即可关闭动画移除van-skeleton--animate类名适合减少低频变化场景或弱网下的动画开销。原子组件的样式实现头像skeleton-avatar/index.less 中round形状通过border-radius: var(--van-radius-max)实现尺寸由getSizeStyle(props.avatarSize)统一设置宽高flex-shrink: 0保证在弹性布局中不被压缩段落skeleton-paragraph/index.less 中非首行段落通过:not(:first-child)加上margin-top: var(--van-skeleton-paragraph-margin-top)自动产生行间距标题SkeletonTitle.tsx 使用h3语义化标签渲染宽度通过内联style.width传入图片skeleton-image/index.less 中内嵌 icon 的尺寸动态取image-size的一半保证图标始终居中且按比例缩放。测试用例验证测试文件 覆盖了组件的核心行为可作为理解语义的参考rowWidth数组渲染验证[100%, 30, 5rem]混合类型的逐行宽度loadingfalse时渲染默认插槽avatarSize传入20rem时宽高均生效avatarShapesquare时头像形状类名切换round属性生成van-skeleton--round类名template插槽渲染自定义内容切换animate属性可动态增删van-skeleton--animate动画类名。实践建议优先复用官方原子组件自定义骨架时组合van-skeleton-title、van-skeleton-avatar、van-skeleton-paragraph、van-skeleton-image即可覆盖绝大多数列表、卡片、详情页布局记住最后一行自动收窄未传row-width时末行固定为60%若需要所有行等宽请显式传入row-width100%用loading统一控制切换将真实内容放在默认插槽配合请求完成回调切换loading即可零成本获得「占位 → 内容」的过渡按需调整动画与圆角弱网或低端设备可将animate置为false并可通过 CSS 变量微调段落高度、头像尺寸与动画时长使骨架屏与设计稿完全对齐。至此你已经掌握了 Vant Skeleton 从 API 使用到源码实现的完整链路可以灵活地在自己的移动端项目中落地骨架屏加载体验。【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考