antd Badge：基于语义结构的 classNames 与 styles 样式定制实战指南

本篇指南聚焦 antd Badge 组件（含 Badge.Ribbon）通过 classNames 和 styles 两个 props 定制语义化结构样式的完整能力：从对象与函数两种传值形态，到条件样式、语义节点说明、与 ConfigProvider 全局配置的合并优先级，以及底层 useMergeSemantic 合并机制的源码解析。读完后你能够针对 Badge 的任意语义节点（root / indicator / content）精确注入 class 与行内样式，并理解其在组件内部的生效路径。

功能定位：解决什么样式定制问题

在语义化结构出现之前，若要修改 Badge 数字圆点或 Ribbon 缎带的样式，通常只能借助 :global 覆盖、深层选择器等手段，直接命中 .ant-badge-count、.ant-ribbon 这类内部类名，既脆弱又容易随主题重构失效。

Badge 从 5.7.0 版本起（Ribbon 为 6.0.0 版本起）引入了 classNames 和 styles 两个 props：组件内部把 DOM 拆解为若干具有明确语义的节点，每个节点都可以单独挂 class 或行内样式。官方示例文档（style-class.md）的原始描述即：“通过 classNames 和 styles 传入对象/函数可以自定义 Badge 的语义化结构样式。”

语义化结构一览

在写任何定制代码之前，先要清楚每个组件暴露了哪些语义节点，以及每个节点承载什么职责。

Badge 的语义节点

节点	版本	职责说明
root	5.7.0	根元素，包含相对定位、行内块布局、适应内容宽度等基础布局样式
indicator	5.7.0	指示器元素（即数字圆点/小红点），包含定位、层级、尺寸、颜色、字体、文本对齐、背景、圆角、阴影、过渡动画等完整的徽标样式

Badge.Ribbon 的语义节点

节点	版本	职责说明
root	6.0.0	根元素，设置相对定位和包装容器样式
indicator	6.0.0	指示器元素，设置绝对定位、内边距、背景色、圆角和缎带样式
content	6.0.0	文本元素，设置文本颜色和缎带内容显示样式

以上说明可直接参考语义预览示例：Badge 语义结构 与 Ribbon 语义结构。

实战示例：官方 demo 完整代码

style-class.tsx 演示了四个组合用法：对象形式的 classNames（antd-style 生成）、对象形式的 styles、函数形式的条件 styles，分别作用于 Badge 与 Badge.Ribbon。完整代码如下：

import React from 'react';
import { Avatar, Badge, Card, Flex, Space } from 'antd';
import type { BadgeProps, GetProp } from 'antd';
import { createStaticStyles } from 'antd-style';
import type { RibbonProps } from 'antd/es/badge/Ribbon';

const badgeClassNames = createStaticStyles(({ css }) => ({
  indicator: css`
    font-size: 10px;
  `,
}));

const ribbonClassNames = createStaticStyles(({ css }) => ({
  root: css`
    width: 400px;
    border: 1px solid #d9d9d9;
    border-radius: 10px;
  `,
}));

const badgeStyles: BadgeProps['styles'] = {
  root: {
    borderRadius: 8,
  },
};

const ribbonStyles: RibbonProps['styles'] = {
  indicator: {
    boxShadow: '0 2px 4px rgba(0,0,0,0.1)',
  },
};

const badgeStylesFn: BadgeProps['styles'] = (info): GetProp<RibbonProps, 'styles', 'Return'> => {
  if (info.props.size === 'medium') {
    return {
      indicator: {
        fontSize: 14,
        backgroundColor: '#696FC7',
      },
    };
  }
  return {};
};

const ribbonStylesFn: RibbonProps['styles'] = (info): GetProp<RibbonProps, 'styles', 'Return'> => {
  if (info.props.color === '#696FC7') {
    return {
      content: {
        fontWeight: 'bold',
      },
      indicator: {
        boxShadow: '0 2px 4px rgba(0,0,0,0.1)',
      },
    };
  }
  return {};
};

const App: React.FC = () => {
  return (
    <Space size="large" vertical>
      <Flex gap="medium">
        <Badge size="small" count={5} classNames={badgeClassNames} styles={badgeStyles}>
          <Avatar shape="square" size="large" />
        </Badge>
        <Badge count={5} classNames={badgeClassNames} styles={badgeStylesFn}>
          <Avatar shape="square" size="large" />
        </Badge>
      </Flex>
      <Flex vertical gap="medium">
        <Badge.Ribbon text="Custom Ribbon" classNames={ribbonClassNames} styles={ribbonStyles}>
          <Card title="Card with custom ribbon" size="small">
            This card has a customized ribbon with semantic classNames and styles.
          </Card>
        </Badge.Ribbon>
        <Badge.Ribbon
          text="Custom Ribbon"
          color="#696FC7"
          classNames={ribbonClassNames}
          styles={ribbonStylesFn}
        >
          <Card title="Card with custom ribbon" size="small">
            This card has a customized ribbon with semantic classNames and styles.
          </Card>
        </Badge.Ribbon>
      </Flex>
    </Space>
  );
};

export default App;

示例要点拆解：

1. 对象形式的 classNames：badgeClassNames 通过 antd-style 的 createStaticStyles 生成，只覆盖 indicator 节点的 font-size；ribbonClassNames 则覆盖 root 的宽度、边框与圆角。
2. 对象形式的 styles：badgeStyles 给 root 加 borderRadius: 8；ribbonStyles 给 indicator（缎带本体）加阴影。
3. 函数形式的 styles：badgeStylesFn 依据 info.props.size 判断，只有 size 为 medium 时才放大圆点字体并改色；ribbonStylesFn 依据 info.props.color 判断，特定色值的缎带会加粗文本并附加阴影。
4. 类型推导技巧：示例用 BadgeProps['styles'] 与 GetProp<RibbonProps, 'styles', 'Return'> 约束函数返回类型，保证只允许写入语义节点键，拼写错误会在编译期报错。

属性 API 与版本要求

结合 Badge API 文档，两个组件的 classNames / styles 签名如下：

Badge

参数	类型	默认值	版本
classNames	Record<SemanticDOM, string> | (info: { props }) => Record<SemanticDOM, string>	-	5.7.0
styles	Record<SemanticDOM, CSSProperties> | (info: { props }) => Record<SemanticDOM, CSSProperties>	-	5.7.0

其中 SemanticDOM 对 Badge 而言即 { root, indicator }。

Badge.Ribbon

参数	类型	默认值	版本
classNames	Record<SemanticDOM, string> | (info: { props }) => Record<SemanticDOM, string>	-	6.0.0
styles	Record<SemanticDOM, CSSProperties> | (info: { props }) => Record<SemanticDOM, CSSProperties>	-	6.0.0

Ribbon 的 SemanticDOM 为 { root, indicator, content }。

源码解析：classNames 与 styles 如何生效

类型系统：GenerateSemantic

函数形态的 info: { props } 回调参数，其类型由 semanticType.ts 中的 GenerateSemantic<T, Props> 派生：

export type GenerateSemantic<T extends { classNames?: any; styles?: any }, Props> = {
  classNames: DeepClassNameType<T['classNames']>;
  classNamesAndFn:
    | DeepClassNameType<T['classNames']>
    | ((info: { props: Props }) => DeepClassNameType<T['classNames']>);
  styles: DeepStylesType<T['styles']>;
  stylesAndFn:
    | DeepStylesType<T['styles']>
    | ((info: { props: Props }) => DeepStylesType<T['styles']>);
};

在 Badge.tsx 中，语义结构类型被声明为 { classNames?: { root?; indicator? }, styles?: { root?; indicator? } }，再经 GenerateSemantic<BadgeSemanticType, BadgeProps> 展开——因此函数回调里能拿到完整的 BadgeProps（info.props），且 DeepClassNameType / DeepStylesType 允许每个节点的值在“字符串/CSSProperties”与“嵌套对象”之间二选一。Ribbon.tsx 中同样以 GenerateSemantic<RibbonSemanticType, RibbonProps> 生成 RibbonSemanticAllType，多出一个 content 节点。

合并机制：useMergeSemantic

真正的合并在 useMergeSemantic/index.ts 中完成，核心流程是：

1. 解析函数：resolveStyleOrClass 判断传入值是对象还是函数，是函数则以 { props: mergedProps } 调用求值；
2. 合并 classNames：mergeClassNames 按语义键逐个 clsx 拼接多来源的 class，多个来源的类名会同时保留（叠加而非覆盖）；
3. 合并 styles：mergeStyles 按语义键做对象浅展开（{ ...acc[key], ...cur[key] }），后合并的来源会覆盖先合并来源的同名 CSS 属性。

在 Badge.tsx 中可以看到完整的合并调用：

// 先构造包含默认值回填的 props，供函数回调使用
const mergedProps: BadgeProps = { ...props, overflowCount, size, dot, showZero };

const [mergedClassNames, mergedStyles] = useMergeSemantic<...>(
  [contextClassNames, classNames],          // ConfigProvider 全局 → 组件 props
  [contextStyles, contextLegacyStyle, styles, componentLegacyStyle],
  { props: mergedProps },
);

两个值得注意的实现细节：

• mergedProps 回填默认值：传给回调的 info.props 不是原始 props，而是把 overflowCount（默认 99）、size（默认 'medium'）、dot（默认 false）、showZero（默认 false）补齐后的对象。因此 demo 中 info.props.size === 'medium' 在调用方未显式传 size 时依然成立。
• useSemanticRootStyle 的 legacy 兼容：componentLegacyStyle 把旧的顶层 style prop 包装进 { indicator: style }（状态点徽标场景则包装进 root），使得老写法 style={{ color: 'red' }} 仍然作用在圆点上，且排在语义 styles 之后参与合并。

节点最终挂载位置

• Badge：mergedClassNames.root / mergedStyles.root 挂在最外层 <span className={...ant-badge}> 上；mergedClassNames.indicator / mergedStyles.indicator（再叠加 offset 偏移与非预设 color 背景色）挂在数字圆点的 ScrollNumber 元素上（见 Badge.tsx）。独立状态点模式（<Badge status="success" /> 无 children）下同样区分 root（外层）与 indicator（状态圆点）两个挂载点。
• Ribbon：root 挂在外层包装 <div>（ant-ribbon-wrapper），indicator 挂在缎带本体 <div>（叠加 color 背景色），content 挂在文本 <span> 上（见 Ribbon.tsx）。Ribbon 中旧版 style prop 被映射到 indicator 节点，与 Badge 的状态点场景类似。

全局配置与样式优先级

classNames / styles 不是只作用于单个组件。从 useMergeSemantic 的入参顺序可以确认优先级链条：ConfigProvider 全局配置 →（legacy style 兼容项）→ 组件自身 props，后者覆盖前者。Badge 还可通过 ConfigProvider 的组件级配置下发 badge: { classNames, styles }，Ribbon 则对应 ribbon 配置项（useComponentConfig('badge') / useComponentConfig('ribbon')）。

这一行为在测试中有直接验证。semantic.test.tsx 中：

• should support classNames and styles：验证对象形式下 root class 落在 .ant-badge 根元素、indicator class 落在 sup（圆点）元素，styles 的 backgroundColor 分别生效；
• should support function-based semantic classNames and styles：验证函数形式回调能拿到 props.size 并据此输出 class 与样式；
• should follow indicator style priority / should follow status root style priority：在 ConfigProvider 注入全局 styles 后，断言全局 styles、legacy style、组件 styles、组件 style 四者的覆盖顺序符合 semanticRootStylePriority 定义。

实践建议

1. 优先用语义节点，不要写深层选择器：indicator 就是圆点/缎带本体，root 就是容器，直接命中比覆盖 .ant-badge-count 更抗版本变化。
2. 条件样式用函数形态：需要依据 size、color、placement 等 props 分支返回样式时，用 (info) => ... 形式，info.props 已回填默认值，可放心做等值判断。
3. 利用类型约束：以 BadgeProps['styles']、RibbonProps['classNames'] 或 GetProp 工具函数标注变量类型，可在 IDE 中获得节点键补全，防止把样式挂到不存在的节点上。
4. 注意版本前提：Badge 的 classNames/styles 需要 5.7.0+，Ribbon 的语义结构能力需要 6.0.0+（官方 demo 也标注了 version="6.0.0"），低版本项目应先确认 antd 版本再使用。
5. 全局统一外观走 ConfigProvider：若全站徽标都要加阴影、改圆点尺寸，建议配置在 ConfigProvider 的 badge 组件配置中，单点覆盖交给组件 props，二者的合并行为有上述测试保证。