ant-design-blazor Spin 组件尺寸详解:small、default、large 的适用场景与实现原理

原创2026-10-11 13:32:491,367 阅读
文章标签:前端UI组件设计系统WebAssembly

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 等官方示例文档。

登录后查看全文
ant-design-blazor