loading.md

title	atomId	group
Loading 加载	Loading	title order 对话流 3

Loading 加载

一套优雅的加载动画组件集合，提供多种加载动画效果，适用于各种加载场景。

代码演示

基础用法

API

Loading

Loading 组件是主要的加载组件，支持多种使用模式。

参数	说明	类型	默认值	必填
size	动画尺寸（宽度和高度），支持数字（px）或字符串（如 '1em', '2rem'）。未设置时，嵌套模式默认为 32px，非嵌套模式默认为 '1em'	number | string	-	否
tip	加载提示文本，支持 ReactNode。设置为 false 或 null 时不显示提示	React.ReactNode | false | null	-	否
indicator	自定义加载指示器，支持 ReactNode	React.ReactNode	-	否
percent	加载进度百分比（0-100），设置后会显示进度条	number	-	否
children	子元素，传入后会启用嵌套模式（覆盖在内容上方显示加载状态）	React.ReactNode	-	否
className	自定义类名	string	-	否
wrapperClassName	最外层容器的自定义类名	string	-	否
style	自定义样式	React.CSSProperties	-	否
styles	语义化样式配置，可分别设置 root、wrapper、indicator、tip 的样式	Partial<Record<'root' | 'wrapper' | 'indicator' | 'tip', React.CSSProperties>>	-	否
spinning	是否显示加载状态，仅在嵌套模式下生效，控制是否显示加载指示器和背景动画效果	boolean	true	否

组件概览

Loading 组件库提供了三种不同风格的加载动画组件：

组件	描述	使用方式	适用场景
Loading	标准的加载动画，包含两个旋转的椭圆形	可直接使用，支持多种模式	通用的数据加载、页面加载等场景
CreativeSparkLoading	创意生成中火花动画（基于 Lottie）	可独立使用或作为 Loading 的 indicator	创意生成、灵感激发、内容创作等场景
CreativeRecommendationLoading	创意推荐闪动动画（基于 Effect）	可独立使用或作为 Loading 的 indicator	推荐系统、建议生成、智能推荐等场景

注意：

• CreativeSparkLoading 基于 Lottie 动画实现
• CreativeRecommendationLoading 基于 Effect 动画实现

参数	说明	类型	默认值	必填
autoplay	是否自动播放动画	boolean	true	否
loop	是否循环播放动画	boolean	true	否
className	动画容器类名	string	-	否
style	动画容器样式	React.CSSProperties	-	否
size	动画尺寸（宽度和高度），支持数字（px）或字符串（如 '1em', '2rem'）	number | string	'1em'	否

特性

• 🎨 多种类型: 提供三种不同风格的动画组件，适应不同的使用场景
• ⚡ 高性能: 基于 Lottie 和 Effect 动画实现，确保动画流畅且性能优异
• 📏 灵活尺寸: 支持通过 size 属性或 style 中的 fontSize 控制整体大小
• 🎯 易于集成: 默认尺寸为 1em，可以很好地与文本内容对齐
• 📊 进度显示: 支持显示加载进度百分比，带有渐变色进度条
• 🎭 嵌套模式: 支持覆盖在内容上方显示加载状态，带有优雅的渐变背景和闪光动画效果，可通过 spinning 属性控制显示/隐藏
• 🎨 自定义指示器: 支持使用任何 React 组件作为加载指示器

使用说明

尺寸控制

• 默认尺寸: 当未设置 size 时，组件会根据模式自动选择默认尺寸
  • 非嵌套模式：默认尺寸为 '1em'，可以很好地与文本内容对齐
  • 嵌套模式：默认尺寸为 32px
• 尺寸设置: 可以通过 size 属性直接设置动画的宽度和高度，支持数字（px）或字符串（如 '1em', '2rem'），也可以通过 style 属性传递 fontSize 来控制大小

提示文本

• 显示提示: 通过 tip 属性设置提示文本，支持字符串或 ReactNode
• 隐藏提示: 设置 tip={false} 或 tip={null} 可以隐藏提示文本
• 自动百分比: 当设置了 percent 但未设置 tip 时，会自动显示百分比文本

进度显示

• 进度条: 当设置了 percent 属性时，会自动显示圆形进度条，带有渐变色效果
• 优先级: 当同时设置了 percent 和 indicator 时，indicator 优先，percent 会被忽略
• 提示优先级: 当同时设置了 percent 和 tip 时，优先显示 tip 的内容

自定义指示器

• 使用方式: 通过 indicator 属性传入任何 React 组件作为加载指示器
• 优先级: indicator 的优先级高于 percent，当同时设置时，会使用 indicator 而不是进度条

加载状态控制

• spinning 属性: 控制是否显示加载状态，默认值为 true
• 作用范围: 仅在嵌套模式下生效，在非嵌套模式下此属性无效
• 嵌套模式: 当 spinning={false} 时，会隐藏加载指示器和背景动画效果，但子内容仍然可见

样式定制

• 语义化样式: 使用 styles 属性可以分别定制 root、wrapper、indicator、tip 的样式
• 样式合并: styles.root 会与 style 属性合并，style 的优先级高于 styles.root
• wrapperClassName: 在嵌套模式下，可以通过 wrapperClassName 为最外层容器添加自定义类名