ant-design-blazor Spin 组件尺寸详解:small、default、large 的适用场景与实现原理
ant-design-blazor Spin 组件尺寸详解:small、default、large 的适用场景与实现原理
导读
在 Ant Design Blazor 组件库中,Spin(加载中)组件用于页面和区块的加载状态。其 Size 参数提供 small、default、large 三种尺寸,分别面向文本级加载、卡片容器级加载和页面级加载三种典型场景。本文以官方演示文档 size.md 为核心,结合 Spin.razor、Spin.razor.cs 等源码与 index.less 样式实现,完整讲解三种尺寸的选用标准、写法示例以及背后的尺寸计算原理,帮助你为不同粒度的加载场景选择正确的 Spin 规格。
三种尺寸的定位与适用场景
官方演示对三种尺寸给出了非常明确的定位:
small(小号):用于文本加载。当加载动作只影响一小段文字、行内图标或局部小控件时使用,视觉占用最小,避免过度干扰页面。default(默认):用于卡片容器级加载。当一整张卡片、表单区块或内容容器处于异步数据等待时使用,这是最常用的规格。large(大号):用于页面级加载。当整个页面或主要视图区域处于加载状态时使用,视觉权重最高,能清楚传达“整体正在加载”的信息。
这一选型思路与 ant-design-blazor 官方文档索引 index.zh-CN.md 中的描述一致:页面局部处于等待异步数据或正在渲染过程时,合适的加载动效可以有效缓解用户的焦虑。而尺寸正是控制加载动效“视觉分量”最直接的开关。
三种尺寸的完整示例代码
演示文档对应的实际示例代码位于 Size.razor,代码极其简洁:
<div>
<Spin Size="SpinSize.Small" />
<Spin />
<Spin Size="SpinSize.Large" />
</div>
- 第一个
<Spin Size="SpinSize.Small" />渲染小号加载动效; - 第二个
<Spin />不传Size,使用默认值(等价于SpinSize.Default),渲染中号; - 第三个
<Spin Size="SpinSize.Large" />渲染大号。
注意这里 Size 的类型是枚举 SpinSize(而非字符串),其定义位于 SpinSize.cs:
public enum SpinSize
{
Small,
Default,
Large,
}
示例所在页面还附带了一段演示样式,让三个 Spin 在同一行内联排布并拉开间距,便于直观对比三种尺寸:
.ant-spin.ant-spin-spinning {
display: inline-block;
margin-right: 16px;
}
在实际项目里,如果你也想把 Spin 排成一行对比效果,可以复用这段样式;正常使用时,ant-spin-spinning 状态下的内联块布局与间距由组件自带样式负责,无需额外处理。
尺寸选择实战建议
结合三种尺寸的官方定位,在实际开发中可以遵循以下选用逻辑:
| 加载粒度 | 推荐尺寸 | 典型场景 |
|---|---|---|
| 文本/小部件级 | SpinSize.Small |
列表中的行内刷新、按钮附近的状态提示、单条文字的异步加载 |
| 区块/容器级 | SpinSize.Default |
卡片、表格、表单区域的数据加载,是最常用配置 |
| 页面级 | SpinSize.Large |
整页首次加载、路由切换时的主要视图区加载 |
同时要注意,Size 只控制加载动效本身(四个圆点的尺寸与动画),并不会改变 Spin 包裹内容区域的布局。如果需要在整张卡片上叠加遮罩式加载,应使用 Spin 的包裹(嵌套)用法,即把内容放进 <Spin> 的子级,并配合 Spinning 参数控制显隐——这在后文“与包裹式加载的配合”中会具体展开。
从源码看三种尺寸的实现原理
尺寸到 CSS 类名的映射
Size 参数在 Spin.razor.cs 的 SetClass() 方法中被映射为对应 CSS 类名:
ClassMapper
.Add(PrefixCls) // ant-spin
.If($"{PrefixCls}-spinning", () => _isLoading) // ant-spin-spinning
.If($"{PrefixCls}-lg", () => Size == SpinSize.Large) // ant-spin-lg
.If($"{PrefixCls}-sm", () => Size == SpinSize.Small) // ant-spin-sm
.If($"{PrefixCls}-show-text", () => !string.IsNullOrWhiteSpace(Tip))
.If($"{PrefixCls}-rtl", () => RTL);
也就是说:
SpinSize.Small→ 追加ant-spin-sm类;SpinSize.Large→ 追加ant-spin-lg类;SpinSize.Default→ 不追加任何尺寸类名,使用基础ant-spin样式。
Size 的默认值在参数声明处可见:public SpinSize Size { get; set; } = SpinSize.Default;(Spin.razor.cs)。
Less 样式中的尺寸变量
三种尺寸在样式层有对应的 Less 变量定义(default.less):
@spin-dot-size-sm: 14px;
@spin-dot-size: 20px;
@spin-dot-size-lg: 32px;
加载动效由四个圆点组成,默认渲染模板定义在 Spin.razor:
<span class="ant-spin-dot ant-spin-dot-spin">
<i class="ant-spin-dot-item"></i>
<i class="ant-spin-dot-item"></i>
<i class="ant-spin-dot-item"></i>
<i class="ant-spin-dot-item"></i>
</span>
四个圆点分别位于方形容器的四个角,通过 antSpinMove(透明度渐显)与 antRotate(整体旋转)两个关键帧动画形成旋转收缩的加载效果,完整定义见 index.less。
尺寸类名作用于圆点容器与圆点本身(index.less):
// small
&-sm &-dot {
font-size: @spin-dot-size-sm; // 14px
i {
width: 6px;
height: 6px;
}
}
// large
&-lg &-dot {
font-size: @spin-dot-size-lg; // 32px
i {
width: 14px;
height: 14px;
}
}
基础(default)状态下圆点尺寸为 @spin-dot-size: 20px,单个圆点为 9px × 9px。因此从视觉上可以清楚看到:small 为 14px 容器 + 6px 圆点,default 为 20px 容器 + 9px 圆点,large 为 32px 容器 + 14px 圆点——尺寸越大,加载动效越醒目,这正是“文本级 / 容器级 / 页面级”定位的样式基础。
包裹式(nested)加载中的尺寸适配
当 Spin 包裹内容(存在 ChildContent)时,组件会生成 ant-spin-nested-loading 包装容器(见 Spin.razor.cs 与 Spin.razor)。此时加载动效会被绝对定位到容器中央,index.less 针对 ant-spin-sm 与 ant-spin-lg 分别调整了圆点居中偏移量:
> div > .@{spin-prefix-cls}-sm {
.@{spin-prefix-cls}-dot {
margin: -(@spin-dot-size-sm / 2);
}
...
}
> div > .@{spin-prefix-cls}-lg {
.@{spin-prefix-cls}-dot {
margin: -(@spin-dot-size-lg / 2);
}
...
}
这保证了无论选择哪种尺寸,嵌套加载时圆点都能在容器中心精确居中。
与其他参数的配合:让尺寸发挥最佳效果
官方 API(见 index.zh-CN.md)中,除 Size 外还有多个与加载场景强相关的参数,实战中常与尺寸一起组合使用:
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
Size |
组件大小,可选 small、default、large |
SpinSize |
SpinSize.Default |
Spinning |
是否为加载中状态 | bool |
true |
Delay |
延迟显示加载效果的时间(毫秒),防止闪烁 | int |
0 |
Tip |
当作为包裹元素时,自定义描述文案 | string |
- |
Indicator |
自定义加载指示符 | RenderFragment |
- |
WrapperClassName |
包裹器的类属性 | string |
- |
控制显隐:Spinning
独立使用时,Spin 默认处于加载状态(Spinning 默认 true)。在真实业务中通常由异步数据状态驱动,例如 Nested.razor 中包裹一张卡片并用开关控制加载状态:
<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;
}
把 Spinning 绑定到异步加载状态(如 IsLoading 属性),数据到达后自动切换为 false,即可实现页面级(large)或卡片级(default)加载的自然结束。
防止闪烁:Delay
当加载耗时极短(例如几十毫秒)时,一闪而过的动效反而造成视觉闪烁。Delay 参数可以延迟加载效果的显示。其实现位于 Spin.razor.cs:初始化时 Delay > 0 会创建 System.Timers.Timer,参数变化后重启计时器,计时结束才真正切换 _isLoading,从而避免快速刷新的闪烁。官方演示见 DelayAndDebounce.razor:
<Spin Spinning="loading" Delay="500">
<Alert ... />
</Spin>
自定义文案与指示符
Tip:在嵌套加载模式下,在圆点下方显示描述文案(如“Loading...”),演示见 Tip.razor;Indicator:完全替换默认四圆点动效。例如 CustomIndicator.razor 用旋转图标替代默认圆点:
<Spin Indicator="antIcon" />
@code{
RenderFragment antIcon = @<Icon Type="@IconType.Outline.Loading" Style="font-size: 24px" Spin />;
}
在 Spin 渲染模板中(Spin.razor),Indicator 非空时优先渲染自定义内容,否则使用默认的 ant-spin-dot 四圆点模板。需要说明的是,自定义 Indicator 时尺寸类仍会生效,但其实际显示大小由你传入的内容决定。
小结
Spin 的三种尺寸本质上是同一套四圆点动效在不同 Less 尺寸变量(14px / 20px / 32px)下的三种规格,由 SpinSize 枚举映射为 ant-spin-sm / 基础 / ant-spin-lg 类名驱动。选择尺寸时应遵循官方定位:小的用于文本加载,默认用于卡片容器级加载,大的用于页面级加载。配合 Spinning(状态控制)、Delay(防闪烁)、Tip(文案说明)、Indicator(自定义动效)等参数,即可为从单行文字到整页加载的各类异步场景提供恰当的加载反馈。
如需进一步了解 Spin 的完整 API 与更多演示,可继续阅读 index.zh-CN.md 以及同目录下的 basic.md、nested.md、custom-indicator.md 等官方示例文档。