2026/9/20 2:30:06
FEATURED · 精选文章 
Ant Design Spin 组件三种尺寸small / default / large的使用与源码解析【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design本文围绕 ant-design 仓库中 Spin 各种大小演示 这一演示文档展开系统讲解Spin加载组件的三档尺寸设计规范、完整可运行的示例代码并结合组件源码、样式 Token 与测试快照深入剖析size属性在底层是如何映射为不同尺寸与 CSS 类名的。读完本文你将掌握在文本加载、卡片容器级加载、页面级加载三种场景下正确选用 Spin 尺寸的方法并理解其背后的设计 Token 体系。一、三种尺寸的设计语义先选场景再写代码官方演示文档 size.md 给出的设计指引非常精炼一句话概括了三种尺寸的使用场景small小号用于文本加载场景。例如表单按钮内、行内文字旁的轻量等待反馈尺寸小、不抢视觉焦点。default默认用于卡片容器级加载。这是最常见的场景——一个卡片、一个区块内部正在请求数据时在区块中央显示加载动效。large大号用于页面级加载。整页数据尚未就绪时用大尺寸的加载图标占据视觉中心传递整个页面都在加载的强反馈。这一尺寸对应场景的约定与组件文档 index.zh-CN.md 中用于页面和区块的加载中状态的描述相互印证Spin 天然被设计为覆盖区块级与页面级两类加载需求而size正是用来在两者及其更细粒度场景之间切换的开关。二、完整示例代码一行切换三种尺寸演示文档对应的可运行源码位于 size.tsx核心代码极其简洁import React from react; import { Flex, Spin } from antd; const App: React.FC () ( Flex aligncenter gapmiddle Spin sizesmall / Spin / Spin sizelarge / /Flex ); export default App;三个要点值得注意size是唯一区别三个Spin /的唯一差异就是size属性第二个Spin /不传size即使用默认值default。这印证了演示的主题——通过size一个属性即可完成三档尺寸切换。外层使用Flex布局Flex aligncenter gapmiddle让三个加载图标水平排列、垂直居中、间距适中方便开发者直观对比三档尺寸的视觉差异。Flex组件来自同一仓库的components/flex模块在 antd v5 中用于替代手写display: flex样式。独立使用形态这里的Spin没有包裹任何子元素属于独立加载图标形态。与之相对的包裹形态嵌套加载可见 nested.tsx那里用Spin spinning{loading}包裹Alert实现卡片加载中效果——该场景正是default尺寸的典型应用。三、源码实现size 属性如何映射为尺寸与类名从源码看size属性的定义与处理位于 index.tsx可以拆成三层来看。3.1 类型定义三档取值被收窄为联合类型// components/spin/index.tsx const SpinSizes [small, default, large] as const; export type SpinSize (typeof SpinSizes)[number];SpinProps中对应声明为size?: SpinSize。也就是说size的合法取值在类型层面被严格限制为small | default | large三者之一传入其他值会直接触发 TypeScript 编译错误——这是三档尺寸这一设计约束在类型系统上的落地。3.2 默认值不传即 defaultsize default,在组件函数解构 props 时size被赋予默认值default因此Spin /与Spin sizedefault /完全等价这也解释了演示代码中第二个 Spin 不写size的原因。3.3 类名映射sm / lg 前缀约定组件内部通过classNames将尺寸映射为对应的 CSS 类const spinClassName classNames( prefixCls, spin?.className, { [${prefixCls}-sm]: size small, [${prefixCls}-lg]: size large, [${prefixCls}-spinning]: spinning, // ... }, className, // ... );在默认前缀ant下最终渲染出的类名分别是sizesmall→ant-spin ant-spin-sm ant-spin-spinning不传 /sizedefault→ant-spin ant-spin-spinning不带尺寸后缀sizelarge→ant-spin ant-spin-lg ant-spin-spinning这一映射结果已被测试快照直接验证在 demo.test.ts.snap 中可以看到classant-spin ant-spin-sm ant-spin-spinning与classant-spin ant-spin-lg ant-spin-spinning等实际渲染输出。快照测试由 demo.test.ts 驱动确保演示代码的渲染结果长期稳定。四、底层尺寸从哪来设计 Token 与 dotSize 计算ant-spin-sm/ant-spin-lg这些类最终通过 style/index.ts 中的 CSS-in-JS 样式生成函数转化为真实样式。决定到底多大的核心是三个 Component Token// components/spin/style/index.ts export const prepareComponentToken: GetDefaultTokenSpin (token) { const { controlHeightLG, controlHeight } token; return { contentHeight: 400, dotSize: controlHeightLG / 2, dotSizeSM: controlHeightLG * 0.35, dotSizeLG: controlHeight, }; };其中dotSizeSM控制small尺寸的图标大小约为大控件高度的 0.35 倍dotSize是默认尺寸的图标大小取大控件高度的一半dotSizeLG控制large尺寸的图标大小直接等于标准控件高度controlHeightcontentHeight: 400是嵌套加载时内容区域的参考高度上限。而controlHeight/controlHeightLG这些基础尺寸来自全局主题种子 Token在 theme/themes/seed.ts 中定义了controlHeight: 32。也就是说三档 Spin 的实际像素尺寸并不是写死的魔法数字而是从主题系统计算派生而来——这意味着开发者可以通过 ConfigProvider 或主题 Token 整体调整控件尺寸体系Spin 的各档尺寸会自动跟随缩放而不需要针对 Spin 单独写覆盖样式。在样式生成时尺寸类名与 Token 的对应关系如下style/index.ts[-sm ${componentCls}-dot]: { , -holder: { fontSize: token.dotSizeSM }, }, [-lg ${componentCls}-dot]: { , -holder: { fontSize: token.dotSizeLG }, },由于加载指示符的圆点dot整体通过fontSize驱动dot-holder 的宽高为1em因此只要切换dotSizeSM/dotSizeLG四个圆点的尺寸、间距与布局会自动按比例变化无需逐条重写定位样式。这解释了为什么只改一个size属性就能获得整体协调的三档视觉。五、实战建议三种尺寸的典型组合用法把演示文档的尺寸规范放到真实业务中常见组合如下场景推荐 size典型写法文本/按钮内加载smallButton loading /或Spin sizesmall /卡片、表格、区块加载default默认Spin spinning{loading}Card.../Card/Spin整页路由切换加载largeSpin sizelarge fullscreen /或页面级容器内使用其中两个值得展开的点与tip配合当size较大且需要文字说明时可配合tip属性。源码中提示tip仅在嵌套模式有 children或fullscreen模式下生效index.tsx 中对应isNestedPattern判断否则会在开发环境发出 warning。嵌套模式下文本的paddingTop也会按dotSizeSM/dotSizeLG分别计算保证文字与图标的垂直间距在不同尺寸下同样协调。与fullscreen配合页面级加载推荐使用fullscreen属性v5.11.0它会让 Spin 以position: fixed覆盖整个视口style/index.ts 中.ant-spin-fullscreen的width: 100vw; height: 100vh此时配合sizelarge正是文档所说的大的用于页面级加载的标准实现。自定义指示符如果三档尺寸的内置四圆点指示器不满足需求可通过indicator属性传入自定义 ReactNode此时指示符的根节点会被追加ant-spin-dot类见 Indicator/index.tsx 的cloneElement逻辑从而同样受到sm/lg尺寸类的约束保证自定义指示符也能正确适配三档尺寸。六、总结Ant Design 的 Spin 通过size属性将加载动效划分为small/default/large三档对应文本加载 → 卡片容器级加载 → 页面级加载三种由轻到重的反馈场景。这一看似简单的属性背后是类型系统联合类型约束、类名映射-sm/-lg前缀、设计 TokendotSizeSM/dotSize/dotSizeLG从controlHeight系派生三层机制的协同。掌握这一机制后你不仅能在业务中快速选择合适的尺寸还能通过主题 Token 实现全站尺寸体系的统一调节。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Ant Design Spin 组件三种尺寸（small / default / large）的使用与源码解析
Ant Design Spin 组件三种尺寸small / default / large的使用与源码解析【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design本文围绕 ant-design 仓库中 Spin 各种大小演示 这一演示文档展开系统讲解Spin加载组件的三档尺寸设计规范、完整可运行的示例代码并结合组件源码、样式 Token 与测试快照深入剖析size属性在底层是如何映射为不同尺寸与 CSS 类名的。读完本文你将掌握在文本加载、卡片容器级加载、页面级加载三种场景下正确选用 Spin 尺寸的方法并理解其背后的设计 Token 体系。一、三种尺寸的设计语义先选场景再写代码官方演示文档 size.md 给出的设计指引非常精炼一句话概括了三种尺寸的使用场景small小号用于文本加载场景。例如表单按钮内、行内文字旁的轻量等待反馈尺寸小、不抢视觉焦点。default默认用于卡片容器级加载。这是最常见的场景——一个卡片、一个区块内部正在请求数据时在区块中央显示加载动效。large大号用于页面级加载。整页数据尚未就绪时用大尺寸的加载图标占据视觉中心传递整个页面都在加载的强反馈。这一尺寸对应场景的约定与组件文档 index.zh-CN.md 中用于页面和区块的加载中状态的描述相互印证Spin 天然被设计为覆盖区块级与页面级两类加载需求而size正是用来在两者及其更细粒度场景之间切换的开关。二、完整示例代码一行切换三种尺寸演示文档对应的可运行源码位于 size.tsx核心代码极其简洁import React from react; import { Flex, Spin } from antd; const App: React.FC () ( Flex aligncenter gapmiddle Spin sizesmall / Spin / Spin sizelarge / /Flex ); export default App;三个要点值得注意size是唯一区别三个Spin /的唯一差异就是size属性第二个Spin /不传size即使用默认值default。这印证了演示的主题——通过size一个属性即可完成三档尺寸切换。外层使用Flex布局Flex aligncenter gapmiddle让三个加载图标水平排列、垂直居中、间距适中方便开发者直观对比三档尺寸的视觉差异。Flex组件来自同一仓库的components/flex模块在 antd v5 中用于替代手写display: flex样式。独立使用形态这里的Spin没有包裹任何子元素属于独立加载图标形态。与之相对的包裹形态嵌套加载可见 nested.tsx那里用Spin spinning{loading}包裹Alert实现卡片加载中效果——该场景正是default尺寸的典型应用。三、源码实现size 属性如何映射为尺寸与类名从源码看size属性的定义与处理位于 index.tsx可以拆成三层来看。3.1 类型定义三档取值被收窄为联合类型// components/spin/index.tsx const SpinSizes [small, default, large] as const; export type SpinSize (typeof SpinSizes)[number];SpinProps中对应声明为size?: SpinSize。也就是说size的合法取值在类型层面被严格限制为small | default | large三者之一传入其他值会直接触发 TypeScript 编译错误——这是三档尺寸这一设计约束在类型系统上的落地。3.2 默认值不传即 defaultsize default,在组件函数解构 props 时size被赋予默认值default因此Spin /与Spin sizedefault /完全等价这也解释了演示代码中第二个 Spin 不写size的原因。3.3 类名映射sm / lg 前缀约定组件内部通过classNames将尺寸映射为对应的 CSS 类const spinClassName classNames( prefixCls, spin?.className, { [${prefixCls}-sm]: size small, [${prefixCls}-lg]: size large, [${prefixCls}-spinning]: spinning, // ... }, className, // ... );在默认前缀ant下最终渲染出的类名分别是sizesmall→ant-spin ant-spin-sm ant-spin-spinning不传 /sizedefault→ant-spin ant-spin-spinning不带尺寸后缀sizelarge→ant-spin ant-spin-lg ant-spin-spinning这一映射结果已被测试快照直接验证在 demo.test.ts.snap 中可以看到classant-spin ant-spin-sm ant-spin-spinning与classant-spin ant-spin-lg ant-spin-spinning等实际渲染输出。快照测试由 demo.test.ts 驱动确保演示代码的渲染结果长期稳定。四、底层尺寸从哪来设计 Token 与 dotSize 计算ant-spin-sm/ant-spin-lg这些类最终通过 style/index.ts 中的 CSS-in-JS 样式生成函数转化为真实样式。决定到底多大的核心是三个 Component Token// components/spin/style/index.ts export const prepareComponentToken: GetDefaultTokenSpin (token) { const { controlHeightLG, controlHeight } token; return { contentHeight: 400, dotSize: controlHeightLG / 2, dotSizeSM: controlHeightLG * 0.35, dotSizeLG: controlHeight, }; };其中dotSizeSM控制small尺寸的图标大小约为大控件高度的 0.35 倍dotSize是默认尺寸的图标大小取大控件高度的一半dotSizeLG控制large尺寸的图标大小直接等于标准控件高度controlHeightcontentHeight: 400是嵌套加载时内容区域的参考高度上限。而controlHeight/controlHeightLG这些基础尺寸来自全局主题种子 Token在 theme/themes/seed.ts 中定义了controlHeight: 32。也就是说三档 Spin 的实际像素尺寸并不是写死的魔法数字而是从主题系统计算派生而来——这意味着开发者可以通过 ConfigProvider 或主题 Token 整体调整控件尺寸体系Spin 的各档尺寸会自动跟随缩放而不需要针对 Spin 单独写覆盖样式。在样式生成时尺寸类名与 Token 的对应关系如下style/index.ts[-sm ${componentCls}-dot]: { , -holder: { fontSize: token.dotSizeSM }, }, [-lg ${componentCls}-dot]: { , -holder: { fontSize: token.dotSizeLG }, },由于加载指示符的圆点dot整体通过fontSize驱动dot-holder 的宽高为1em因此只要切换dotSizeSM/dotSizeLG四个圆点的尺寸、间距与布局会自动按比例变化无需逐条重写定位样式。这解释了为什么只改一个size属性就能获得整体协调的三档视觉。五、实战建议三种尺寸的典型组合用法把演示文档的尺寸规范放到真实业务中常见组合如下场景推荐 size典型写法文本/按钮内加载smallButton loading /或Spin sizesmall /卡片、表格、区块加载default默认Spin spinning{loading}Card.../Card/Spin整页路由切换加载largeSpin sizelarge fullscreen /或页面级容器内使用其中两个值得展开的点与tip配合当size较大且需要文字说明时可配合tip属性。源码中提示tip仅在嵌套模式有 children或fullscreen模式下生效index.tsx 中对应isNestedPattern判断否则会在开发环境发出 warning。嵌套模式下文本的paddingTop也会按dotSizeSM/dotSizeLG分别计算保证文字与图标的垂直间距在不同尺寸下同样协调。与fullscreen配合页面级加载推荐使用fullscreen属性v5.11.0它会让 Spin 以position: fixed覆盖整个视口style/index.ts 中.ant-spin-fullscreen的width: 100vw; height: 100vh此时配合sizelarge正是文档所说的大的用于页面级加载的标准实现。自定义指示符如果三档尺寸的内置四圆点指示器不满足需求可通过indicator属性传入自定义 ReactNode此时指示符的根节点会被追加ant-spin-dot类见 Indicator/index.tsx 的cloneElement逻辑从而同样受到sm/lg尺寸类的约束保证自定义指示符也能正确适配三档尺寸。六、总结Ant Design 的 Spin 通过size属性将加载动效划分为small/default/large三档对应文本加载 → 卡片容器级加载 → 页面级加载三种由轻到重的反馈场景。这一看似简单的属性背后是类型系统联合类型约束、类名映射-sm/-lg前缀、设计 TokendotSizeSM/dotSize/dotSizeLG从controlHeight系派生三层机制的协同。掌握这一机制后你不仅能在业务中快速选择合适的尺寸还能通过主题 Token 实现全站尺寸体系的统一调节。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
