ant-design-blazor 组件详解:Spin 加载中组件的用法与实现原理
ant-design-blazor 组件详解:Spin 加载中组件的用法与实现原理
Spin 是 ant-design-blazor 中用于展示"页面或区块加载中"状态的反馈类组件,适用于等待异步数据或渲染过程的场景,通过加载动效有效缓解用户焦虑。本文以官方组件文档为核心,结合本仓库源码(Spin.razor、Spin.razor.cs)与演示示例,系统讲解 Spin 的 API 参数、典型使用场景、延迟防闪烁机制以及样式定制方法,帮助你写出可直接落地的加载状态代码。
何时使用 Spin
当页面局部处于等待异步数据、或某个区块正在渲染时,一个合适的加载动效可以有效缓解用户的焦虑。官方文档(index.en-US.md)给出的适用场景非常明确:
- 页面级:整页等待异步数据时,使用大型加载动画;
- 区块级:卡片、列表、表格等局部区域等待数据时,用 Spin 包裹内容;
- 文本级:按钮、输入框旁的小范围加载,使用小型动画。
快速上手:五种典型用法
本仓库在 site/AntDesign.Docs/Demos/Components/Spin/demo 目录下提供了 7 个可运行示例,覆盖了 Spin 的全部核心能力,可直接参考:
1. 基本用法
最简单的加载状态,直接渲染一个自转的 Spin 指示器:
<Spin />
示例源码见 Basic.razor,对应说明文档 basic.md。此时 Spinning 默认值为 true,组件立即进入旋转状态。
2. 放入容器(Inside a container)
把 Spin 放进一个容器中展示,例如深色背景区块内的居中加载:
<div class="example">
<Spin />
</div>
<style>
.example {
text-align: center;
background: rgba(0, 0, 0, 0.05);
border-radius: 4px;
padding: 30px 50px;
margin: 20px 0;
}
</style>
完整示例见 Inside.razor 与 inside.md。
3. 内嵌内容(Embedded mode / 卡片加载中)
直接把内容内嵌到 Spin 中,将现有容器变为加载状态。加载时容器内容会变暗并不可交互:
<div>
<Spin Spinning="loading">
<Alert
Message="Alert message title"
Description="Further details about the context of this alert."
Type="AlertType.Info" />
</Spin>
<div style="margin-top: 16px">
Loading state:
<Switch Checked="loading" OnChange="toggle" />
</div>
</div>
@code {
bool loading = false;
void toggle(bool value) => loading = value;
}
示例见 Nested.razor 与 nested.md。核心是把业务内容作为 ChildContent 放进 Spin 内部,并通过 Spinning 参数控制加载状态。这也是文档 API 中"当作为包裹元素时"能力的典型用法。
4. 各种大小(Size)
小的用于文本加载,默认用于卡片容器级加载,大的用于页面级加载:
<div>
<Spin Size="SpinSize.Small" />
<Spin />
<Spin Size="SpinSize.Large" />
</div>
示例见 Size.razor 与 size.md。注意 Blazor 版本中 Size 的类型是 SpinSize 枚举(SpinSize.cs),取值为 Small、Default、Large,文档中的字符串写法 small/default/large 对应枚举各成员。
5. 延迟显示(Delay,防闪烁)
当加载状态在延迟时间内就结束时,不显示加载动画,避免快速请求导致界面闪烁:
<div>
<Spin Spinning="loading" Delay="500">
<Alert
Message="Alert message title"
Description="Further details about the context of this alert."
Type="AlertType.Info" />
</Spin>
<div style="margin-top: 16px">
Loading state:
<Switch Checked="loading" OnChange="toggle" />
</div>
</div>
@code {
bool loading = false;
void toggle(bool value) => loading = value;
}
示例见 DelayAndDebounce.razor 与 delayAndDebounce.md。文档明确指出:如果 spinning 状态在 delay 时间内结束,则不会显示 loading 状态——这正是防闪烁(prevent flush)的核心语义。
6. 自定义描述文案(Tip)
当 Spin 作为包裹元素时,通过 Tip 自定义加载说明文字:
<Spin Tip="Loading...">
<Alert
Message="Alert message title"
Description="Further details about the context of this alert."
Type="AlertType.Info" />
</Spin>
示例见 Tip.razor 与 tip.md。渲染时文字会放在 ant-spin-text 容器中,并自动为指示器预留垂直间距(源码与样式均有对应处理)。
7. 自定义指示符(Custom Indicator)
使用 Indicator 参数替换默认的四点旋转动画,例如换成旋转的 Loading 图标:
<Spin Indicator="antIcon" />
@code{
RenderFragment antIcon = @<Icon Type="@IconType.Outline.Loading" Style="font-size: 24px" Spin />;
}
示例见 CustomIndicator.razor 与 custom-indicator.md。其中 Icon 组件的 Spin 参数(Icon.razor.cs)会让图标自转;IconService.cs 中,当 icon.Spin 为 true 或图标类型为 loading 时,会自动追加 anticon-spin 样式类实现旋转动画。
API 参数详解
下表为官方文档(index.en-US.md)中的完整 API,并补充了当前仓库 Spin.razor.cs 中的实际实现细节:
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| Delay | 延迟显示加载效果的时间(毫秒),用于防止闪烁 | int(毫秒) |
0 |
| Indicator | 加载指示符,自定义旋转元素 | RenderFragment |
默认四点动画 |
| Size | 组件大小,可选 SpinSize.Small / SpinSize.Default / SpinSize.Large |
SpinSize |
SpinSize.Default |
| Spinning | 是否为加载中状态 | bool |
true |
| Tip | 当作为包裹元素时,自定义描述文案 | string |
null |
| WrapperClassName | 包装器的类名(有子内容时生效) | string |
无 |
| ChildContent | 被 Spin 包裹的业务内容 | RenderFragment |
无 |
各参数在源码中的实现要点如下:
- Delay(防闪烁):源码通过
System.Timers.Timer实现。OnInitialized中若Delay > 0则创建定时器;OnParametersSet中当Spinning状态发生变化时Stop后重新Start,定时器到期后才把_isLoading同步为Spinning并刷新 UI。也就是说,加载状态是否显示取决于"状态持续是否超过延迟时间"。 - Spinning:初始化时
_isLoading = Spinning;无延迟时参数变化会立即同步并触发StateHasChanged,有延迟时由定时器回调DelayElapsed统一处理。 - Indicator:
RenderFragment类型,渲染时优先使用自定义指示符,否则使用默认的ant-spin-dot ant-spin-dot-spin四点动画模板(Spin.razor)。 - Size:通过
ClassMapper追加ant-spin-sm或ant-spin-lg类,配合样式文件中不同尺寸的 dot 大小实现视觉差异。 - WrapperClassName:仅在
ChildContent非空(Simple == false)时通过ant-spin-nested-loading包裹层生效。
源码实现剖析:Spin 是怎么工作的
组件结构
Spin.razor 将渲染逻辑拆成两层:
- 简单模式:无
ChildContent时只渲染指示器(含可选的 Tip 文本); - 嵌套模式:有
ChildContent时,外层div使用WrapperClassMapper(追加WrapperClassName与ant-spin-nested-loading),内层同时渲染指示器与ant-spin-container容器。加载中时容器追加ant-spin-blur类,内容变暗且不可交互。
状态与类名
Simple => ChildContent == null决定是否进入嵌套模式;ContainerClass => _isLoading ? "ant-spin-blur" : ""控制内容的模糊遮罩;- 类名映射在
SetClass()中完成:ant-spin-spinning(旋转中)、ant-spin-lg/ant-spin-sm(尺寸)、ant-spin-show-text(有 Tip)、ant-spin-rtl(RTL 方向)。
生命周期中的延迟逻辑
OnInitialized 初始化 _isLoading 与定时器,OnParametersSet 对比 _isLoading != Spinning 来启停定时器,DelayElapsed 在到期后同步状态并 InvokeAsync(StateHasChanged),Dispose 中释放定时器。这一流程保证了延迟防闪烁语义的完整闭环。
样式与主题定制
默认四点动画的视觉细节定义在 components/spin/style/index.less:
- 四个
ant-spin-dot-item圆点分别位于四角,通过antSpinMove动画交替改变透明度,外层容器通过antRotate旋转(1.2s 线性无限循环); - 尺寸变量定义在 components/style/themes/default.less:
@spin-dot-size-sm: 14px、@spin-dot-size: 20px、@spin-dot-size-lg: 32px,即小/默认/大三档指示器边长; - 加载中容器
ant-spin-blur将内容透明度降为 0.5 并禁用pointer-events,ant-spin-container::after半透明遮罩叠加,实现"内容变暗且不可点击"的效果; - 组件样式通过 entry.less 引入,并包含 rtl.less 处理 RTL 方向下的反向旋转动画(
antRotateRtl)。
若需全局统一调整,可通过 ant-design-blazor 的主题变量机制修改 @spin-dot-size* 系列变量后重新编译样式。
关于静态方法 setDefaultIndicator 的说明
官方文档 API 部分列出了静态方法 Spin.setDefaultIndicator(indicator: ReactNode),用于全局自定义默认 Spin 元素。需要说明的是:该条目沿袭自上游 Ant Design React 版本文档;在当前仓库的 Blazor 实现中(Spin.razor.cs)并未提供对应的全局静态方法,全局默认指示符的自定义能力暂未实现。Blazor 场景下的等价做法是使用 Indicator 参数按组件指定自定义指示符;若需要全局生效,可自行封装一个包裹 Spin 的公共组件,在内部统一传入 Indicator,以此在应用中形成"全局默认指示符"的使用约定。
小结
Spin 组件以极少的参数覆盖了从文本级到页面级的全部加载场景:Spinning 控制开关,Delay 防闪烁,Size 分级显示,Tip 与 Indicator 负责文案与视觉自定义,嵌套模式下自动对内容做模糊遮罩。理解其定时器驱动的延迟逻辑与 ant-spin-blur 遮罩原理后,你可以在异步数据加载、表单提交、列表刷新等场景中灵活组合这些参数,做出体验顺滑的加载反馈。更多可运行示例与完整说明,可直接查阅 Spin 演示目录 与 官方文档。