u-skeletonUniApp 骨架屏组件概览什么是骨架屏为什么需要骨架屏组件特性三种模式插槽模式遮罩模式行列模式模式决策流程子组件skeleton-itemskeleton-textskeleton-avatarskeleton-image参考容器 Props子组件 Props动画说明常见问题u-skeleton 骨架屏组件为 UniApp 打造的高性能骨架屏方案 —— 三种模式、四种子组件、一个配置搞定一切加载态。什么是骨架屏骨架屏Skeleton Screen是一种在页面数据加载期间用灰色占位块模拟真实内容布局的加载反馈模式。相比传统的 Loading Spinner它能让用户提前感知页面结构降低等待焦虑。研究表明骨架屏比 Spinner 让用户感觉加载速度快 15%~20%。因为骨架屏提供了空间参照用户的大脑会「预渲染」页面产生「即将完成」的心理暗示。组件特性01三种模式插槽 / 遮罩 / 行列覆盖全部使用场景02四种子组件矩形、多行文本、头像、图片自由组合03主题继承provide/inject CSS 变量双通道04三种动画Shimmer 流光 / Pulse 脉冲 / Blink 闪烁05交错动画每个骨架块依次延迟波浪式扫过06渐隐过渡骨架消失时平滑淡出不闪烁跳变模式一插槽模式 推荐⚙原理说明通过 #skeleton 命名插槽声明骨架布局通过默认插槽声明真实内容。组件根据 show 属性在两者之间切换。替换模式coverfalse骨架消失时真实内容才 mounted避免重复渲染覆盖模式covertrue真实内容始终挂载骨架作为浮层覆盖在其上方替换模式用法vue u-skeleton :showloading animationshimmer :stagger60 !-- 骨架声明 -- template #skeleton view styledisplay:flex; padding:32rpx; u-skeleton-avatar size96 / view styleflex:1; margin-left:20rpx; u-skeleton-item width40% height32 :index0 / u-skeleton-item width70% height24 :index1 stylemargin-top:12rpx / /view /view view stylepadding:0 32rpx; u-skeleton-text :lines4 :index2 / /view view stylepadding:24rpx 32rpx; u-skeleton-image height360 radius16rpx / /view /template !-- 真实内容骨架消失后才 mounted -- article-page :dataarticle / /u-skeleton覆盖模式用法vue !-- covertrue: 真实内容始终挂载骨架浮于其上 -- u-skeleton :showloading cover template #skeleton view stylepadding:40rpx u-skeleton-avatar size128 stylemargin:0 auto 32rpx / u-skeleton-text :lines3 / /view /template profile-page / !-- mounted 立即执行 -- /u-skeleton**为什么插槽模式是推荐方案**它完全不依赖 createSelectorQuery在 H5、小程序、App 三端表现一致。同时消除了时序问题 —— 骨架布局由你声明不需要查询 DOM。模式二遮罩模式 兼容原理说明使用 createSelectorQuery 查询页面中带有.skeleton或自定义选择器类名的元素获取其尺寸和位置然后在 position: fixed 的遮罩层上用骨架块覆盖。自动检测用法vue template view u-skeleton :showloading selector.sk animationshimmer loadedonLoaded emptyonEmpty / !-- 这些元素会被骨架屏自动检测并覆盖 -- image classsk :srcavatar stylewidth:120rpx; height:120rpx; / text classsk styledisplay:block; width:60%; height:36rpx; 标题 /text /view /template手动声明用法vue u-skeleton :showloading :blocks[ { width: 120, height: 120, top: 40, left: 32, shape: circle }, { width: 50%, height: 36, top: 56, left: 172 }, { width: 80%, height: 24, top: 104, left: 172 }, { width: 100%, height: 300, top: 160, left: 32, radius: 16rpx } ] /**注意**遮罩模式依赖 createSelectorQuery在部分平台如 H5 的某些情况可能存在查询延迟。组件内置了最多 5 次自动重试机制但如果父组件渲染较慢建议使用插槽模式。模式三行列模式 快捷▦原理说明传入 rows 属性自动生成列表骨架布局。支持头像占位、文本行数控制、最后一行宽度设置。适合快速生成列表页骨架。vue u-skeleton :showloading :rows6 :lineCount2 :showAvatartrue avatarSize96 rowHeight28 rowGap36 lastLineWidth40% animationpulse /行列模式演示模式决策流程选择哪种模式按以下流程判断是否使用了 #skeleton 插槽是插槽模式否有 selector 或 blocks是遮罩模式否rows 0 ?是行列模式否空骨架子组件skeleton-item通用骨架块用于模拟矩形 UI 元素按钮、标签、输入框、分割线等。效果预览vue !-- 基础用法 -- u-skeleton-item width60% height32 / !-- 圆形 -- u-skeleton-item width80 height80 circle / !-- 胶囊按钮 -- u-skeleton-item width160 height64 round / !-- 自定义颜色 -- u-skeleton-item width100% height200 color#e0e0e0 highlight#f0f0f0 / !-- 交错动画配合容器 stagger -- u-skeleton-item width50% height28 :index0 / u-skeleton-item width80% height28 :index1 / u-skeleton-item width65% height28 :index2 /子组件skeleton-text多行文本占位自动将最后一行缩短以模拟真实段落。内置行间距和交错动画支持。3 行文本 / 最后一行 60%vue u-skeleton-text :lines4 height24 gap14 lastWidth45% :index0 /子组件skeleton-avatar头像占位。支持圆形和方形两种形状。circle / squarevue !-- 圆形头像 -- u-skeleton-avatar size96 shapecircle / !-- 方形头像 -- u-skeleton-avatar size96 shapesquare /子组件skeleton-image图片占位中央显示 emoji 图标作为视觉提示。图片占位vue u-skeleton-image width100% height400 radius16rpx /容器 Props 速查控制Prop类型默认值说明showBooleantrue是否显示骨架屏coverBooleanfalse插槽模式下内容是否常驻不销毁遮罩模式Prop类型默认值说明selectorString‘’自动检测的 CSS 选择器blocksArray[]手动骨架块声明数组queryDelayNumber100首次查询延迟 (ms)maxRetryNumber5查询最大重试次数retryIntervalNumber150重试间隔 (ms)行列模式Prop类型默认值说明rowsNumber0行数0 激活行列模式lineCountNumber2每行文本线数量lastLineWidthString/Number‘50%’最后一行宽度rowHeightNumber/String28行高rowGapNumber/String24行间距showAvatarBooleanfalse是否显示头像占位avatarSizeNumber/String80头像尺寸avatarShapeString‘circle’circle / squareavatarGapNumber/String20头像与文本间距外观 行为Prop类型默认值说明animationString‘shimmer’动画类型shimmer / pulse / blinkbgColorString‘#ebedf0’骨架底色highlightColorString‘#f5f6f8’Shimmer 高亮色borderRadiusString‘8rpx’默认圆角zIndexNumber9999遮罩层 z-indexfadeDurationNumber300渐隐过渡时长 (ms)staggerNumber60骨架块间交错动画延迟 (ms)事件事件参数说明loadedrects[]遮罩模式查询成功empty—重试耗尽仍未找到节点子组件 Props 速查skeleton-itemProp类型默认值说明widthString/Number‘100%’宽度heightString/Number‘32’高度radiusString‘’圆角空则继承容器circleBooleanfalse圆形radius: 50%roundBooleanfalse胶囊radius: 999pxblockBooleanfalse强制 display:blockanimString‘’动画类型空则继承容器indexNumber-1交错动画索引colorString‘’覆盖骨架底色highlightString‘’覆盖高亮色skeleton-textProp类型默认值说明linesNumber3文本行数heightString/Number‘28’行高gapString/Number‘16’行间距lastWidthString/Number‘60%’最后一行宽度animString‘’动画类型indexNumber0交错基准索引skeleton-avatarProp类型默认值说明sizeString/Number‘80’尺寸正方形shapeString‘circle’circle / squareanimString‘’动画类型skeleton-imageProp类型默认值说明widthString/Number‘100%’宽度heightString/Number‘360’高度radiusString‘’圆角animString‘’动画类型动画说明Shimmer推荐渐变光带从左向右扫过视觉效果最接近真实内容加载Pulsepulse整体明暗交替呼吸效果适合大面积色块Blinkblink简单透明度闪烁经典样式性能最优交错动画stagger通过 stagger 属性设置每个骨架块之间的动画延迟产生波浪式流光效果stagger: 80ms常见问题Q: 为什么遮罩模式获取不到节点父组件的异步数据可能还未渲染到 DOM。组件内置了最多5 次自动重试间隔 150ms你也可以调大 maxRetry 和 retryInterval。如果问题持续建议改用插槽模式。Q: 骨架屏和真实页面布局不一致骨架屏的布局应与真实内容保持相同的尺寸和间距。建议使用插槽模式在 #skeleton 插槽中用子组件精确复刻真实内容的布局结构。Q: H5 端 scrollTo 位置不正确遮罩模式使用 position: fixed 定位其坐标基准是视口。如果页面有滚动偏移骨架块的位置会自动与 boundingClientRect 返回的视口坐标对齐。如果出现偏差请检查页面是否有额外的 transform 或 will-change 属性影响了定位上下文。Q: 如何自定义颜色主题两种方式**容器级**通过 bgColor 和 highlightColor 设置所有子组件自动继承**组件级**通过子组件的 color 和 highlight 属性覆盖vue !-- 深色主题 -- u-skeleton bgColor#2a2a2a highlightColor#3a3a3a template #skeleton u-skeleton-text :lines3 / /template /u-skeletonQ: provide/inject 和 CSS 变量有什么区别两者是双通道主题传递机制provide/inject子组件通过 JS 访问容器的 animation、borderRadius、stagger 等配置CSS 变量–sk-bg、–sk-hl、–sk-r 让动画样式无需 JS 即可读取主题色两者协同工作确保无论是通过 props 还是 CSS 都能正确应用主题。u-skeleton v3.0 · UniApp 骨架屏组件 · 插槽 / 遮罩 / 行列 三种模式