Ant Design Spin 组件尺寸详解:small / default / large 三种加载状态的应用实践

原创2026-09-17 19:27:131,685 阅读
文章标签:前端UI组件设计系统

Ant Design Spin 组件尺寸详解:small / default / large 三种加载状态的应用实践

Spin 是 Ant Design(antd)中用于表示页面或区块"加载中"状态的反馈组件,通过一个动态旋转的三点动效缓解用户等待异步数据或渲染过程时的焦虑。本篇技术指南以仓库 size.md 演示为核心,完整讲解 Spin 的三种尺寸(small / default / large)语义、正确使用场景,并结合 index.jsx 与 spin.less 源码剖析其尺寸控制的底层实现。读完你将掌握如何按加载粒度为文本、卡片容器、页面级加载选择合适的 Spin 尺寸,并理解其样式定制原理。

一、三种尺寸与使用场景

Ant Design 的 Spin 组件提供三档预设尺寸,官方演示文档给出了明确的场景划分:

尺寸取值 使用场景
small 小的用于文本加载,适合按钮、表格局部单元格等细粒度区域的加载提示
default(默认,不传 size) 默认用于卡片容器级加载,适合卡片、面板、区块内部的整块内容加载
large 大的用于页面级加载,适合整页刷新、路由切换、首屏数据拉取等重量级等待场景

size 是 Spin 组件公开 API 中的核心参数之一。根据组件文档 index.md 中的 API 表格,其完整定义如下:

参数 类型 默认值 说明
size enum default spin 组件中点的大小,可选值为 small、default、large
spining boolean true 用于内嵌其他组件的模式,可以关闭 loading 效果

其中 size 控制的是旋转点(dot)的物理尺寸,三档之间呈倍数关系(详见后文样式解析);而 spining 控制的是加载态的显示与否,与尺寸相互独立。

二、完整演示代码

size.md 演示了在同一页面内依次渲染三种尺寸的 Spin,是最直观的对比示例:

import { Spin } from 'antd';

ReactDOM.render(
  <div>
    <Spin size="small" />
    <br />
    <Spin />
    <br />
    <Spin size="large" />
  </div>
, mountNode);

要点说明:

  • <Spin size="small" />:文本级加载,如行内、按钮中的等待提示;
  • <Spin />:不传 size 即为默认值 default,对应卡片容器级加载;
  • <Spin size="large" />:页面级加载;
  • 示例通过 <br /> 分行展示,实际使用时三个尺寸的 Spin 均为行内块级元素,可自由布局。

该演示与同一目录下的 basic.md(<Spin /> 基础用法)、inside.md(放入容器中)、nested.md(内嵌内容实现卡片加载中)共同构成 Spin 组件的基础用法族谱,建议配合阅读。

三、源码实现:size 是如何生效的

3.1 propTypes 声明与 class 生成

在组件实现 index.jsx 中,size 通过 React.PropTypes.oneOf 做取值校验:

propTypes: {
  className: React.PropTypes.string,
  size: React.PropTypes.oneOf(['small', 'default', 'large'])
},

渲染时根据 size 值拼接对应的样式前缀类名:

let spinClassName = classNames({
  [prefixCls]: true,
  [`${prefixCls}-sm`]: size === 'small',
  [`${prefixCls}-lg`]: size === 'large',
  [className]: !!className,
  [`${prefixCls}-spining`]: this.props.spining,
});

可以看到:

  • size === 'small' 时追加 ant-spin-sm;
  • size === 'large' 时追加 ant-spin-lg;
  • default 不追加任何尺寸类名,仅保留基础类 ant-spin,这也解释了为什么默认尺寸无需显式声明;
  • 默认属性 prefixCls: 'ant-spin'、spining: true 在 getDefaultProps 中定义。

从源码结构可以推断:Spin 默认渲染三个 span 元素(ant-spin-dot-first、ant-spin-dot-second、ant-spin-dot-third),通过 CSS 动画形成旋转脉冲效果;在不支持 CSS 动画的旧环境下则退化为纯文本"加载中..."。

3.2 尺寸的样式实现

尺寸的视觉差异完全由样式层控制。在 spin.less 中,三个尺寸共用一个基础 dot 尺寸变量,再按比例缩放:

@spin-dot-default            : #999;
@spin-dot-size               : 8px;
@spin-dot-size-sm            : @spin-dot-size / 2;   // 4px
@spin-dot-size-lg            : @spin-dot-size * 2;   // 16px

对应的尺寸规则:

// small
&-sm &-dot {
  .square(@spin-dot-size-sm);
  + & {
    margin-left: @spin-dot-size-sm;
  }
}

// large
&-lg &-dot {
  .square(@spin-dot-size-lg);
  + & {
    margin-left: @spin-dot-size-lg;
  }
}

其中 .square(@size) 来自 size.less 工具混入,用于将宽高同时设为同一值。结合基础规则:

  • 默认 dot 直径为 8px,点间距同为 8px;
  • small 档 dot 直径为 4px(8 ÷ 2),间距同步缩小为 4px;
  • large 档 dot 直径为 16px(8 × 2),间距同步放大为 16px;
  • 三个 dot 之间通过 animation-delay 依次延迟 0ms / 200ms / 400ms,配合 antSpinPulse 关键帧(40% 时 opacity 为 1,其余为 0)形成循环闪烁的加载动效;
  • dot 的背景色与 Spin 文字颜色均取自主色变量 @primary-color。

因此,如果你需要在主题层面统一调整 Spin 的尺寸基数,只需在主题文件中覆盖 @spin-dot-size 变量(默认主题入口见 themes/default/index.less),三档尺寸会随之等比缩放。

四、结合嵌套模式选择正确尺寸

Spin 支持内嵌子元素形成"容器级加载",相关实现同样位于 index.jsx:

  • 当 Spin 传入 children 时进入嵌套模式,渲染结构变为 ant-spin-nested-loading > (ant-spin + ant-spin-container);
  • 加载中时,容器内容通过 blur(1px) 模糊并降低透明度至 0.7,同时禁用 pointer-events,防止用户在加载期间误操作;
  • 嵌套模式下的 Spin 会被绝对定位到容器垂直居中位置。

结合 nested.md 演示,典型用法是用 spining 状态配合 Switch 切换加载:

import { Spin, Switch, Alert } from 'antd';

const Card = React.createClass({
  getInitialState() {
    return { loading: false };
  },
  toggle(value) {
    this.setState({ loading: value });
  },
  render() {
    const container = (
      <Alert message="消息提示的文案"
        description="消息提示的辅助性文字介绍"
        type="info" />
    );
    return (
      <div>
        <Spin spining={this.state.loading}>{container}</Spin>
        切换加载状态:<Switch checked={this.state.loading} onChange={this.toggle} />
      </div>
    );
  }
});

ReactDOM.render(<Card />, mountNode);

实践中可遵循以下组合原则:

  • 页面级整页加载:<Spin size="large" />,配合 spining 控制显示,避免页面空白;
  • 卡片 / 区块内容加载:嵌套模式 <Spin size="large" spining={loading}>卡片内容</Spin>,用大号点保证在容器中视觉平衡;
  • 按钮 / 文本行内加载:<Spin size="small" />,避免挤占行高与布局;
  • 关闭加载:spining={false} 时 Spin 处于 opacity: 0 且 visibility: hidden 状态,仅保留占位,不阻塞内容展示。

五、使用建议与注意事项

  1. 尺寸语义优先:官方明确给出了"小—文本、默认—卡片容器、大—页面级"的映射关系,不要为视觉效果随意混用,保持页面内加载反馈的层级一致性;
  2. 嵌套模式务必结合 spining 控制:嵌套容器加载时需要主动切换 spining,否则子内容不会进入模糊与禁交互状态;
  3. 自定义尺寸:若内置三档无法满足需求,可通过覆盖 Less 变量 @spin-dot-size 等比调整基数,或在 size 之外结合 className 自行追加样式规则(className 为公开 API);
  4. 浏览器兼容:样式层为 IE10+ 提供了 -ms-high-contrast 下的白色背景降级方案(见 spin.less),旧浏览器下动画不可用时组件会自动退化为文字提示,无需额外处理。

通过合理运用 small / default / large 三档尺寸与 spining 状态控制,即可在不同粒度的加载场景中提供一致、克制的等待反馈,这是 Ant Design 加载体验设计的基本功之一。

登录后查看全文
ant-design