Ant Design Skeleton 列表加载占位：在 List 组件中实现骨架屏的完整实战指南

Ant Design Skeleton 列表加载占位在 List 组件中实现骨架屏的完整实战指南【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design导读本文围绕 Ant Design 官方示例 列表加载占位list demo 展开讲解如何在 List 组件中集成 Skeleton 骨架屏用一个Switch开关模拟数据加载状态通过Skeleton的loading模式包裹列表项在加载中展示占位图形、加载完成后无缝切换真实内容。读完本文你将掌握 Skeleton 的loading容器模式、avatar/title/paragraph组合策略、列表项actions与extra的条件渲染技巧以及骨架屏背后的源码实现与主题定制方法可直接复用到真实的中后台列表页。一、适用场景为什么列表页需要 SkeletonAnt Design 官方文档components/skeleton/index.zh-CN.md给出了 Skeleton 的使用时机网络较慢需要长时间等待加载处理的情况下图文信息内容较多的列表 / 卡片中只在第一次加载数据的时候使用可以被Spin完全代替但在可用场景下能提供更好的视觉效果和用户体验。列表页是典型的高信息密度场景每条数据包含头像、标题、描述、正文与操作按钮如果整页空白等待用户无法预判内容结构而骨架屏在最终布局确定后用与真实内容同构的灰色占位块勾勒出内容即将到来的轮廓能显著降低感知等待时间。这正是 list demo 要演示的核心能力。二、示例全景在 List 中使用 Skeleton 的完整代码官方示例的完整源码位于 components/skeleton/demo/list.tsx这是可复制运行的完整实现import React, { useState } from react; import type Icon from ant-design/icons; import { LikeOutlined, MessageOutlined, StarOutlined } from ant-design/icons; import { Avatar, List, Skeleton, Switch } from antd; interface IconTextProps { icon: typeof Icon; text: React.ReactNode; } const IconText: React.FCIconTextProps ({ icon, text }) ( {React.createElement(icon, { style: { marginInlineEnd: 8 } })} {text} / ); const listData Array.from({ length: 3 }).map((_, i) ({ href: https://ant.design, title: ant design part ${i 1}, avatar: https://api.dicebear.com/7.x/miniavs/svg?seed${i}, description: Ant Design, a design language for background applications, is refined by Ant UED Team., content: We supply a series of design principles, practical patterns and high quality design resources (Sketch and Axure), to help people create their product prototypes beautifully and efficiently., })); const App: React.FC () { const [loading, setLoading] useState(true); const onChange (checked: boolean) { setLoading(!checked); }; return ( Switch checked{!loading} onChange{onChange} style{{ marginBottom: 16 }} / List itemLayoutvertical sizelarge dataSource{listData} renderItem{(item) ( List.Item key{item.title} actions{ !loading ? [ IconText icon{StarOutlined} text156 keylist-vertical-star-o /, IconText icon{LikeOutlined} text156 keylist-vertical-like-o /, IconText icon{MessageOutlined} text2 keylist-vertical-message /, ] : undefined } extra{ !loading ( img width{272} altlogo srchttps://gw.alipayobjects.com/zos/rmsportal/mqaQswcyDLcXyDKnZfES.png / ) } Skeleton loading{loading} active avatar List.Item.Meta avatar{Avatar src{item.avatar} /} title{a href{item.href}{item.title}/a} description{item.description} / {item.content} /Skeleton /List.Item )} / / ); }; export default App;代码结构一目了然组成作用useState(true)初始为加载态列表首屏渲染骨架屏Switch模拟数据请求完成/开始的开关切换loading状态ListList.Item外层列表容器保持最终布局稳定Skeleton loading{loading} active avatar核心占位容器加载中渲染骨架、加载完成渲染真实子内容actions/extra仅在非加载态渲染的操作区与附图骨架态自动隐藏三、核心机制Skeleton 的 loading 容器模式本示例最值得学习的一点是Skeleton 不是与 List 并排的另一套 UI而是包裹在List.Item内容外层的容器。其开关逻辑在源码 components/skeleton/Skeleton.tsx 中清晰可见if (loading || !(loading in props)) { // ...渲染骨架占位结构avatar header title/paragraph content return wrapCSSVar( div className{cls} style{{ ...skeleton?.style, ...style }} {avatarNode} {contentNode} /div, ); } return children ?? null;理解这一段的两个关键点未传loading时默认渲染骨架!(loading in props)保证Skeleton /如 basic demo 中的裸用默认就是占位态显式传入loading后变成三态容器为true渲染占位为false直接透传children。这正是列表场景的正确用法——List.Item的布局、actions、extra始终由真实数据驱动骨架屏只负责内容区的替换加载完成后无需重建整个列表。配套测试 components/skeleton/tests/index.test.tsx 验证了这一行为loading{false}时直接显示子内容包括0这样的空值也能正确渲染expect(container.textContent).toBe(0)说明 children 透传是严格的原样输出。3.1 与 Switch 的联动逻辑示例中Switch的checked是!loadingonChange里执行setLoading(!checked)开关打开checkedtrue时loadingfalse列表显示真实内容关闭时回到骨架态。真实项目中把这个Switch替换为接口请求即可const [loading, setLoading] useState(true); useEffect(() { fetchList().finally(() setLoading(false)); }, []);Switch的存在让这个 demo 可以反复演示加载中 → 加载完成的完整周期也天然符合只在第一次加载数据的时候使用的官方建议。四、列表骨架的内部结构avatar title paragraph 的自动组合在列表场景中Skeleton active avatar只显式开启了avatar与动画title默认true和paragraph默认true由源码自动补全。从 Skeleton.tsx 可以看到占位结构由两部分组成${prefixCls}-header渲染头像占位Element${prefixCls}-content渲染标题占位Title /与段落占位Paragraph /。占位尺寸并非写死而是根据是否有头像/标题/段落自动推导getAvatarBasicProps/getTitleBasicProps/getParagraphBasicProps组合情况头像标题宽度段落行数段落宽度有标题、无段落方形sizelarge默认2 行61%无头像、有段落圆形sizelarge38%3 行61%最后一行有头像 有段落列表场景圆形sizelarge50%2 行最后一行 61%其余圆形sizelarge100%2 行—之所以能自动适配是因为getComponentProps会把布尔值统一展开为对象再与默认值合并Skeleton.tsxavatar{true}时透传{}avatar{{ size: 20 }}时透传完整配置最终通过{...defaults, ...props}合并。列表 demo 中头像为圆形大尺寸、标题占位宽度 50%、段落两行——正是这套默认推导的产物与List.Item.Meta的头像 标题 描述结构一一对应视觉上几乎以假乱真。4.1 段落占位的宽度细节段落的最后一行缩短效果来自 Paragraph.tsx 的getWidth逻辑当width传入数组时按索引逐行设置宽度传单个值如61%时只作用于最后一行其余行占满容器。同时 style/index.ts 中还有一条兜底规则多于两行时最后一行固定61%宽度。列表场景若希望模拟更真实的正文折行效果可以这样微调Skeleton loading{loading} active avatar paragraph{{ rows: 3, width: [100%, 100%, 70%] }}五、列表项 actions 与 extra 的条件渲染示例中加载态与非加载态不仅由 Skeleton 内部切换List.Item自身的两部分内容也做了条件渲染actions非加载时渲染星标 156 / 点赞 156 / 消息 2三个图标操作加载时传undefined不渲染操作区extra非加载时渲染 272px 宽的配图加载时整段表达式为false不渲染。这里体现了列表骨架屏实践中的一条重要经验骨架态要尽量空——只保留结构性占位头像、标题、段落把装饰性内容操作按钮、附图在加载期一并隐藏避免占位块与真实交互元素混排造成的视觉噪音。切换瞬间列表高度会发生变化真实项目中若在意布局稳定性可给List.Item预留extra区域的固定高度或使用minHeight约束。六、active 动画与样式实现示例中的active让占位块产生流动的加载动画。该动画由 components/skeleton/style/index.ts 定义的Keyframes驱动const skeletonClsLoading new Keyframes(ant-skeleton-loading, { 0%: { backgroundPosition: 100% 50% }, 100%: { backgroundPosition: 0 50% }, });配合skeletonLoadingBackground一个 90° 方向的三段渐变linear-gradient(90deg, 起始色 25%, 结束色 37%, 起始色 63%)与backgroundSize: 400% 100%让背景色块沿 X 轴反复扫过占位块形成流畅的光泽流动效果style/index.ts。动画时长由 tokenskeletonLoadingMotionDuration控制默认1.4s、infinite循环。active动画的生效范围覆盖所有占位元素——标题、段落行、头像、按钮、输入框与图片style/index.ts因此列表里每个Skeleton的头像和段落会同步呼吸整体观感统一。七、Skeleton 完整 API 参数速查以下 API 来自 components/skeleton/index.en-US.md在列表场景中同样适用Skeleton属性说明类型默认值active是否展示动画效果booleanfalseavatar是否显示头像占位图boolean | SkeletonAvatarPropsfalseloading为 true 时显示占位图反之直接展示子组件boolean-paragraph是否显示段落占位图boolean | SkeletonParagraphPropstrueround为 true 时段落和标题显示圆角booleanfalsetitle是否显示标题占位图boolean | SkeletonTitlePropstrueSkeletonAvatarProps属性说明类型默认值active是否展示动画效果仅在单独使用头像骨架时生效booleanfalseshape指定头像的形状circle|square-size设置头像占位图的大小number |large|small|default-SkeletonTitleProps属性说明类型默认值width设置标题占位图的宽度number | string-SkeletonParagraphProps属性说明类型默认值rows设置段落占位图的行数number-width设置段落占位图的宽度若为数组时则对应每行宽度否则为最后一行的宽度number | string | Arraynumber | string-SkeletonButtonProps / SkeletonInputProps属性说明类型默认值版本activeButton/Input是否展示动画效果booleanfalse-blockButton将按钮宽度调整为其父宽度booleanfalse4.17.0shapeButton指定按钮形状circle|round|square|default--sizeButton/Input设置尺寸large|small|default--数值型size如avatar{{ size: 20 }}在 Element.tsx 中会转换为等宽的width/height/lineHeight实现像素级精确的占位尺寸适合对齐真实头像的固定尺寸。测试 index.test.tsx 对size的三种枚举与数字类型均有快照覆盖。八、主题定制让骨架屏贴合你的品牌色骨架屏默认的灰色渐变来自全局 tokencolorFillContent→colorFill。若想在列表中定制占位颜色、圆角与行高可使用ConfigProvider的组件级 token官方示例见 components/skeleton/demo/componentToken.tsxConfigProvider theme{{ components: { Skeleton: { blockRadius: 30, titleHeight: 50, gradientFromColor: #222, gradientToColor: #444, paragraphMarginTop: 30, paragraphLiHeight: 30, }, }, }} Skeleton loading active / /ConfigProviderSkeleton 支持的 Component Token 定义在 components/skeleton/style/index.tsToken说明gradientFromColor渐变色起点颜色替代已废弃的colorgradientToColor渐变色终点颜色替代已废弃的colorGradientEndtitleHeight标题骨架屏高度默认controlHeight / 2blockRadius骨架屏圆角默认borderRadiusSMparagraphMarginTop段落骨架屏上间距paragraphLiHeight段落骨架屏单行高度从源码可见color与colorGradientEnd已标记为废弃deprecatedTokens映射到新 token新项目应直接使用gradientFromColor/gradientToColor。深色模式下把起点与终点设为#222/#444这类配色能让骨架屏在暗色主题下同样自然。九、列表骨架的其他扩展形态Skeleton 还支持独立的元素级占位Skeleton.Button、Skeleton.Avatar、Skeleton.Input、Skeleton.Image、Skeleton.Node挂在Skeleton上的复合组件见 Skeleton.tsx完整演示见 components/skeleton/demo/element.tsx。如果列表页存在加载前无数据、甚至不确定是否展示列表的场景可以把加载态拆成更细的占位列表整体为空、等待首屏接口时用整页Skeleton active avatar /铺满操作区如新建按钮单独占位用Skeleton.Button active block /搜索框加载用Skeleton.Input active /纯图文卡片复用 complex demo 的Skeleton avatar paragraph{{ rows: 4 }} /组合需要真实内容与骨架瞬时切换时参考 children demo 的loading三态容器模式内部实现即为本文第三节分析的loading判断逻辑。结语列表 骨架屏是后台管理系统最常见的加载体验组合。通过本文对 list demo 的拆解可以看到Ant Design 的 Skeleton 用loading容器模式把占位与真实内容封装在同一个组件树中配合active动画、avatar/title/paragraph自动组合以及List.Item的actions/extra条件渲染即可低成本实现高品质的首屏加载反馈。在正式项目中只需把示例中的Switch换成真实的数据请求钩子把listData换成接口返回结构就能直接落地这套方案。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考