antd Spin 语义化样式定制指南使用 classNames 与 styles 精确控制加载中状态的每个部分【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-designSpin加载中是 antd 反馈类组件中最常被二次定制的组件之一——业务侧往往需要微调指示器颜色、描述文案的间距、嵌套内容在加载时的遮罩过渡等。antd v6 起Spin 通过classNames与styles两个属性开放了基于**语义化结构Semantic DOM**的样式入口你可以传入普通对象也可以传入({ props }) ...形式的函数从而在运行时根据组件实际状态如尺寸动态下发样式。本文将以仓库中的 style-class 演示 与对应 说明文档 为核心结合 Spin 源码讲解这两套 API 的完整用法、语义节点清单以及底层合并原理。为什么 Spin 需要语义化样式 APISpin 的 DOM 结构会随使用形态而变化单独使用时渲染指示器 可选描述作为包裹元素有 children或使用fullscreen时则会多出承载加载区域的section与承载内容层的container。若只用传统的className/style只能改到根元素无法精准命中某一层。因此 v6 为 Spin 引入了对齐 antd语义化 DOM体系的classNames与styles版本标注见 Spin API 文档classNames以对象或函数形式为各语义节点提供自定义 classstyles以对象或函数形式为各语义节点提供行内CSSProperties两者自6.0.0起可用传入对象或函数均可函数收到的参数为{ props }。语义化结构一览Spin 的五个节点依据 源码类型定义 与 语义预览演示Spin 的语义节点包括五个各自的职责与最小可用版本如下语义节点对应 DOM/职责可用版本root根元素负责绝对定位、显示控制、颜色、字号、对齐、透明度与过渡动画6.0.0section加载元素所在区域嵌套/fullscreen 形态下的加载层负责相对定位、flex 布局与对齐6.3.0indicator指示器元素负责宽高、字号、inline-block、过渡动画与 line-height6.0.0description描述文案元素6.3.0container承载被包裹子元素的内容容器负责透明度与过渡动画6.3.0其中tip、mask两个旧字段已废弃tip请改用descriptionmask请改用root源码中通过devUseWarning在开发环境给出 deprecation 提示。用法一以对象形式传入 classNames 与 styles对象形式最直接直接给出节点名到样式值的映射。对于styles值就是标准React.CSSProperties对于classNames值是样式类名。仓库 style-class.tsx 中演示了三种叠加用法import React from react; import { Flex, Spin } from antd; import type { GetProp, SpinProps } from antd; import { createStaticStyles } from antd-style; // 1) 通过 antd-style 生成静态类再注入 classNames.root const classNames createStaticStyles(({ css }) ({ root: css padding: 8px; , })); // 2) styles 的对象形式直接命中 indicator 节点 const stylesObject: SpinProps[styles] { indicator: { color: #00d4ff, }, }; const App: React.FC () { const sharedProps: SpinProps { spinning: true, percent: 0, classNames: { root: classNames.root }, }; return ( Flex aligncenter gapmedium Spin {...sharedProps} styles{stylesObject} / /Flex ); };示例要点classNames与styles可以同时使用一个负责挂 class便于写 hover、动画等 CSS 能力一个负责行内样式这里的静态类由文档站开发依赖antd-style^4.1.0见 package.json生成实际业务中你完全可以直接使用自己的 CSS Module、styled 产物或任何普通字符串类名indicator样式直接作用于旋转图标所在元素因此仅用一行color即可改变指示器颜色。用法二以函数形式按组件状态动态返回样式classNames/styles的函数签名统一为type StylesFn (info: { props: SpinProps }) RecordSemanticNode, React.CSSProperties;函数体接收{ props }其props是组件经过合并后的最终属性。从 Spin 实现 看它至少包含当前生效的size、spinning、fullscreen、percent以及合并后的description。这意味着你可以在函数里做基于状态的条件样式。演示中的stylesFn根据尺寸切换指示器颜色const stylesFn: SpinProps[styles] ({ props }): GetPropSpinProps, styles, Return { if (props.size small) { return { indicator: { color: #722ed1, }, }; } return {}; }; // 使用同一函数因 sizesmall 走紫色分支 Spin {...sharedProps} styles{stylesFn} sizesmall /GetPropSpinProps, styles, Return是 antd 导出的类型工具可取出styles的返回值类型让函数返回值获得完整类型检查。返回{}表示该状态不下发任何样式这是函数形式的常见写法。完整可运行示例综合对象与函数两种形态一个自包含的演示如下语义结构与 style-class.tsx 一致import React from react; import { Flex, Spin } from antd; import type { SpinProps } from antd; const stylesBySize: SpinProps[styles] ({ props }) { const colorMap: Recordstring, string { small: #722ed1, medium: #1677ff, large: #52c41a, }; return { indicator: { color: colorMap[props.size ?? medium] } }; }; const App: React.FC () ( Flex aligncenter gapmiddle Spin sizesmall styles{stylesBySize} / Spin sizemedium styles{stylesBySize} / Spin sizelarge styles{stylesBySize} / /Flex ); export default App;提示size默认值为medium历史值default已被废弃并将在 v7 移除见 SpinProps 定义。源码原理函数如何被解析、class 如何合并理解底层实现能帮你判断函数调用时机与 class 拼接行为。相关逻辑集中在两个文件1. 函数/对象解析与多来源合并useMergeSemanticSpin 渲染前会先构造mergedProps随后调用useMergeSemanticindex.tsxconst [mergedClassNames, mergedStyles] useMergeSemantic( [contextClassNames, classNames], // 全局配置层 组件层 classNames [contextStyles, contextStyleRoot, styles], // 全局配置层 组件层 styles { props: mergedProps }, );useMergeSemantic内部对每个来源依次执行resolveStyleOrClassexport const resolveStyleOrClass (value, info) isFunction(value) ? value(info) : value;即每次渲染都会判断值是否为函数是则用当前mergedProps调用它——这正是函数形式能感知props.size的原因然后 class 通过clsx逐层拼接contextClassNames在前、组件classNames在后style 通过浅合并逐层覆盖。因此 Spin 的全局配置ConfigProvider 的classNames/styles与实例上的值会自然叠加。2. 合并结果如何落到语义节点Spin 渲染层从渲染 JSX 可看到每个节点对应的目标最外层div接收mergedClassNames.root与mergedStyles.root有 children 或fullscreen时加载指示区域放入独立的${prefixCls}-section容器挂section语义子内容放入${prefixCls}-container容器挂container语义非嵌套形态下根节点会同时并入section的 class 与样式因此单用时无需担心section配置丢失描述文案div同时兼容旧字段tip与新字段description的 class/styleindex.tsx源码用合并写法保证两代 API 过渡期行为一致。3. 开发期废弃提示在非生产环境Spin 会对以下写法输出devUseWarning警告index.tsxsizedefault→ 改用sizemediumtipprop → 改用descriptionwrapperClassName→ 改用classNames.rootclassNames.tip/styles.tip→ 改用description对应字段classNames.mask/styles.mask→ 改用root对应字段。实践建议与常见坑函数形式避免内联副作用函数每次渲染都会执行内部只应做纯计算与样式返回不要在此发起网络请求或写 DOM。全屏/嵌套与单独形态差异section、container只在嵌套或fullscreen形态出现若你的样式仅针对单加载形态请优先落在root/indicator上以保证两种形态都生效。样式优先级行内样式按contextStyles→contextStyle(root)→styles顺序合并实例上的styles优先生效class 则是全局层与实例层经clsx拼接后共同作用于元素自定义 class 的具体视觉表现取决于其 CSS 特异性与书写顺序。与 ConfigProvider 协同想统一全站 Spin 的指示器颜色可在 ConfigProvider 的组件级classNames/stylesuseComponentConfig(spin)读取见 index.tsx中配置实例属性会在此基础上进一步覆盖。小结classNames/styles让 Spin 的自定义从整体一个根 class进化到按root/section/indicator/description/container精准施力。对象形式适合静态定制函数形式适合根据props.size、spinning等状态动态响应。配合 ConfigProvider 的全局注入与源码级的多源合并机制你既能得到统一默认外观也能在单个实例上无损覆盖——这正是 antd v6 语义化样式体系的通用心智模型也适用于仓库中其他已支持 Semantic DOM 的组件。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
antd Spin 语义化样式定制指南使用 classNames 与 styles 精确控制加载中状态的每个部分【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-designSpin加载中是 antd 反馈类组件中最常被二次定制的组件之一——业务侧往往需要微调指示器颜色、描述文案的间距、嵌套内容在加载时的遮罩过渡等。antd v6 起Spin 通过classNames与styles两个属性开放了基于**语义化结构Semantic DOM**的样式入口你可以传入普通对象也可以传入({ props }) ...形式的函数从而在运行时根据组件实际状态如尺寸动态下发样式。本文将以仓库中的 style-class 演示 与对应 说明文档 为核心结合 Spin 源码讲解这两套 API 的完整用法、语义节点清单以及底层合并原理。为什么 Spin 需要语义化样式 APISpin 的 DOM 结构会随使用形态而变化单独使用时渲染指示器 可选描述作为包裹元素有 children或使用fullscreen时则会多出承载加载区域的section与承载内容层的container。若只用传统的className/style只能改到根元素无法精准命中某一层。因此 v6 为 Spin 引入了对齐 antd语义化 DOM体系的classNames与styles版本标注见 Spin API 文档classNames以对象或函数形式为各语义节点提供自定义 classstyles以对象或函数形式为各语义节点提供行内CSSProperties两者自6.0.0起可用传入对象或函数均可函数收到的参数为{ props }。语义化结构一览Spin 的五个节点依据 源码类型定义 与 语义预览演示Spin 的语义节点包括五个各自的职责与最小可用版本如下语义节点对应 DOM/职责可用版本root根元素负责绝对定位、显示控制、颜色、字号、对齐、透明度与过渡动画6.0.0section加载元素所在区域嵌套/fullscreen 形态下的加载层负责相对定位、flex 布局与对齐6.3.0indicator指示器元素负责宽高、字号、inline-block、过渡动画与 line-height6.0.0description描述文案元素6.3.0container承载被包裹子元素的内容容器负责透明度与过渡动画6.3.0其中tip、mask两个旧字段已废弃tip请改用descriptionmask请改用root源码中通过devUseWarning在开发环境给出 deprecation 提示。用法一以对象形式传入 classNames 与 styles对象形式最直接直接给出节点名到样式值的映射。对于styles值就是标准React.CSSProperties对于classNames值是样式类名。仓库 style-class.tsx 中演示了三种叠加用法import React from react; import { Flex, Spin } from antd; import type { GetProp, SpinProps } from antd; import { createStaticStyles } from antd-style; // 1) 通过 antd-style 生成静态类再注入 classNames.root const classNames createStaticStyles(({ css }) ({ root: css padding: 8px; , })); // 2) styles 的对象形式直接命中 indicator 节点 const stylesObject: SpinProps[styles] { indicator: { color: #00d4ff, }, }; const App: React.FC () { const sharedProps: SpinProps { spinning: true, percent: 0, classNames: { root: classNames.root }, }; return ( Flex aligncenter gapmedium Spin {...sharedProps} styles{stylesObject} / /Flex ); };示例要点classNames与styles可以同时使用一个负责挂 class便于写 hover、动画等 CSS 能力一个负责行内样式这里的静态类由文档站开发依赖antd-style^4.1.0见 package.json生成实际业务中你完全可以直接使用自己的 CSS Module、styled 产物或任何普通字符串类名indicator样式直接作用于旋转图标所在元素因此仅用一行color即可改变指示器颜色。用法二以函数形式按组件状态动态返回样式classNames/styles的函数签名统一为type StylesFn (info: { props: SpinProps }) RecordSemanticNode, React.CSSProperties;函数体接收{ props }其props是组件经过合并后的最终属性。从 Spin 实现 看它至少包含当前生效的size、spinning、fullscreen、percent以及合并后的description。这意味着你可以在函数里做基于状态的条件样式。演示中的stylesFn根据尺寸切换指示器颜色const stylesFn: SpinProps[styles] ({ props }): GetPropSpinProps, styles, Return { if (props.size small) { return { indicator: { color: #722ed1, }, }; } return {}; }; // 使用同一函数因 sizesmall 走紫色分支 Spin {...sharedProps} styles{stylesFn} sizesmall /GetPropSpinProps, styles, Return是 antd 导出的类型工具可取出styles的返回值类型让函数返回值获得完整类型检查。返回{}表示该状态不下发任何样式这是函数形式的常见写法。完整可运行示例综合对象与函数两种形态一个自包含的演示如下语义结构与 style-class.tsx 一致import React from react; import { Flex, Spin } from antd; import type { SpinProps } from antd; const stylesBySize: SpinProps[styles] ({ props }) { const colorMap: Recordstring, string { small: #722ed1, medium: #1677ff, large: #52c41a, }; return { indicator: { color: colorMap[props.size ?? medium] } }; }; const App: React.FC () ( Flex aligncenter gapmiddle Spin sizesmall styles{stylesBySize} / Spin sizemedium styles{stylesBySize} / Spin sizelarge styles{stylesBySize} / /Flex ); export default App;提示size默认值为medium历史值default已被废弃并将在 v7 移除见 SpinProps 定义。源码原理函数如何被解析、class 如何合并理解底层实现能帮你判断函数调用时机与 class 拼接行为。相关逻辑集中在两个文件1. 函数/对象解析与多来源合并useMergeSemanticSpin 渲染前会先构造mergedProps随后调用useMergeSemanticindex.tsxconst [mergedClassNames, mergedStyles] useMergeSemantic( [contextClassNames, classNames], // 全局配置层 组件层 classNames [contextStyles, contextStyleRoot, styles], // 全局配置层 组件层 styles { props: mergedProps }, );useMergeSemantic内部对每个来源依次执行resolveStyleOrClassexport const resolveStyleOrClass (value, info) isFunction(value) ? value(info) : value;即每次渲染都会判断值是否为函数是则用当前mergedProps调用它——这正是函数形式能感知props.size的原因然后 class 通过clsx逐层拼接contextClassNames在前、组件classNames在后style 通过浅合并逐层覆盖。因此 Spin 的全局配置ConfigProvider 的classNames/styles与实例上的值会自然叠加。2. 合并结果如何落到语义节点Spin 渲染层从渲染 JSX 可看到每个节点对应的目标最外层div接收mergedClassNames.root与mergedStyles.root有 children 或fullscreen时加载指示区域放入独立的${prefixCls}-section容器挂section语义子内容放入${prefixCls}-container容器挂container语义非嵌套形态下根节点会同时并入section的 class 与样式因此单用时无需担心section配置丢失描述文案div同时兼容旧字段tip与新字段description的 class/styleindex.tsx源码用合并写法保证两代 API 过渡期行为一致。3. 开发期废弃提示在非生产环境Spin 会对以下写法输出devUseWarning警告index.tsxsizedefault→ 改用sizemediumtipprop → 改用descriptionwrapperClassName→ 改用classNames.rootclassNames.tip/styles.tip→ 改用description对应字段classNames.mask/styles.mask→ 改用root对应字段。实践建议与常见坑函数形式避免内联副作用函数每次渲染都会执行内部只应做纯计算与样式返回不要在此发起网络请求或写 DOM。全屏/嵌套与单独形态差异section、container只在嵌套或fullscreen形态出现若你的样式仅针对单加载形态请优先落在root/indicator上以保证两种形态都生效。样式优先级行内样式按contextStyles→contextStyle(root)→styles顺序合并实例上的styles优先生效class 则是全局层与实例层经clsx拼接后共同作用于元素自定义 class 的具体视觉表现取决于其 CSS 特异性与书写顺序。与 ConfigProvider 协同想统一全站 Spin 的指示器颜色可在 ConfigProvider 的组件级classNames/stylesuseComponentConfig(spin)读取见 index.tsx中配置实例属性会在此基础上进一步覆盖。小结classNames/styles让 Spin 的自定义从整体一个根 class进化到按root/section/indicator/description/container精准施力。对象形式适合静态定制函数形式适合根据props.size、spinning等状态动态响应。配合 ConfigProvider 的全局注入与源码级的多源合并机制你既能得到统一默认外观也能在单个实例上无损覆盖——这正是 antd v6 语义化样式体系的通用心智模型也适用于仓库中其他已支持 Semantic DOM 的组件。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
