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的条件渲染技巧，以及骨架屏背后的源码实现与主题定制方法，可直接复用到真实的中后台列表页。

一、适用场景：为什么列表页需要 Skeleton

Ant 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.FC<IconTextProps> = ({ 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 itemLayout="vertical" size="large" dataSource={listData} renderItem={(item) => ( <List.Item key={item.title} actions={ !loading ? [ <IconText icon={StarOutlined} text="156" key="list-vertical-star-o" />, <IconText icon={LikeOutlined} text="156" key="list-vertical-like-o" />, <IconText icon={MessageOutlined} text="2" key="list-vertical-message" />, ] : undefined } extra={ !loading && ( <img width={272} alt="logo" src="https://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;

代码结构一目了然：

三、核心机制：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;

理解这一段的两个关键点：

1. 未传loading时默认渲染骨架：!('loading' in props)保证<Skeleton />（如 basic demo 中的裸用）默认就是占位态；
2. 显式传入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是!loading，onChange里执行setLoading(!checked)：开关打开（checked=true）时loading=false，列表显示真实内容；关闭时回到骨架态。真实项目中，把这个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）：

之所以能"自动适配"，是因为getComponentProps会把布尔值统一展开为对象再与默认值合并（Skeleton.tsx）：avatar={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

SkeletonAvatarProps

SkeletonTitleProps

SkeletonParagraphProps

SkeletonButtonProps / SkeletonInputProps

数值型size（如avatar={{ size: 20 }}）在 Element.tsx 中会转换为等宽的width/height/lineHeight，实现像素级精确的占位尺寸，适合对齐真实头像的固定尺寸。测试 index.test.tsx 对size的三种枚举与数字类型均有快照覆盖。

八、主题定制：让骨架屏贴合你的品牌色

骨架屏默认的灰色渐变来自全局 tokencolorFillContent→colorFill。若想在列表中定制占位颜色、圆角与行高，可使用ConfigProvider的组件级 token，官方示例见 components/skeleton/demo/componentToken.tsx：

<ConfigProvider theme={{ components: { Skeleton: { blockRadius: 30, titleHeight: 50, gradientFromColor: '#222', gradientToColor: '#444', paragraphMarginTop: 30, paragraphLiHeight: 30, }, }, }} > <Skeleton loading active /> </ConfigProvider>

Skeleton 支持的 Component Token 定义在 components/skeleton/style/index.ts：

从源码可见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