antd Alert 语义结构样式定制：classNames 与 styles 两种形式从实操到源码解析

本文围绕 ant-design 6.x 中 Alert 组件的语义化结构样式定制展开，基于官方示例 style-class.tsx 讲解如何通过 classNames 和 styles 两个属性（支持对象或函数两种形式）精准控制 Alert 内部各结构节点的类名与内联样式，并结合 Alert.tsx 与 useMergeSemantic 的源码实现，说明这些配置在组件内部是如何被解析、合并并挂载到真实 DOM 上的。读完后你可以独立完成：按 type 等属性动态切换样式、区分"类名方案"与"内联样式方案"的适用场景，以及理解全局配置（ConfigProvider）与组件级配置的合并优先级。

为什么需要语义化结构样式

Alert 的默认样式由 Design Token 生成，覆盖的是"整块告警"粒度：背景色、边框色、内边距等写在根容器上。但在实际业务中，经常需要只改某个局部节点——比如只放大图标、只调整标题字重、只给关闭按钮换位置。为此 antd 6.0.0 起为 Alert 引入了 Semantic DOM（语义化 DOM）：把组件内部结构拆分为 7 个可寻址节点，并允许通过 classNames（类名）和 styles（内联样式）两个属性分别定制。

官方文档的 API 表中对这两个属性的定义如下（均为 6.0.0 版本引入，且支持全局配置）：

参数	说明	类型	默认值	版本
classNames	自定义组件内部各语义化结构的类名，支持对象或函数	Record<SemanticDOM, string> | (info: { props }) => Record<SemanticDOM, string>	-	6.0.0
styles	自定义组件内部各语义化结构的内联样式，支持对象或函数	Record<SemanticDOM, CSSProperties> | (info: { props }) => Record<SemanticDOM, CSSProperties>	-	6.0.0

7 个语义节点及其职责（来源：Semantic DOM 示例）：

节点	对应 DOM	职责说明	引入版本
root	根 <div>	边框、背景色、内边距、圆角、位置布局等基础样式	6.0.0
icon	.ant-alert-icon	图标颜色、行高、外边距，支持四种状态图标	6.0.0
section	.ant-alert-section	内容区 flex 布局、排版与最小宽度	6.0.0
title	.ant-alert-title	标题文字颜色、字体样式	6.0.0
description	.ant-alert-description	描述文字字体大小、行高等排版样式	6.0.0
actions	.ant-alert-actions	操作按钮组的布局与间距	6.0.0
close	.ant-alert-close-icon	关闭按钮基础样式	6.1.0

对应的 TypeScript 类型定义在 Alert.tsx 中：AlertSemanticType 明确列出了 classNames 与 styles 各自可写的 7 个键，AlertProps['classNames'] / AlertProps['styles'] 则由 GenerateSemantic 泛型推导为"对象或函数"联合类型。

官方示例：对象样式 + 函数样式两种形式

关联文档对应的完整演示代码见 style-class.tsx，它在一个页面里同时演示了两种写法。完整代码如下：

import React from 'react';
import { Alert, Button, Flex } from 'antd';
import type { AlertProps, GetProp } from 'antd';
import { createStaticStyles } from 'antd-style';

// 形式一：用 antd-style 生成静态类名，传给 classNames
const classNames = createStaticStyles(({ css }) => ({
  root: css`
    border: 2px dashed #ccc;
    border-radius: 8px;
    padding: 12px;
  `,
}));

// 形式二：函数形式的 styles，根据合并后的 props 动态返回样式
const styleFn: AlertProps['styles'] = ({
  props: { type },
}): GetProp<AlertProps, 'styles', 'Return'> => {
  if (type === 'success') {
    return {
      root: {
        backgroundColor: 'rgba(82, 196, 26, 0.1)',
        borderColor: '#b7eb8f',
      },
      icon: {
        color: '#52c41a',
      },
    };
  }

  if (type === 'warning') {
    return {
      root: {
        backgroundColor: 'rgba(250, 173, 20, 0.1)',
        borderColor: '#ffe58f',
      },
      icon: {
        color: '#faad14',
      },
    };
  }

  return {};
};

const App: React.FC = () => {
  const alertSharedProps: AlertProps = {
    showIcon: true,
    classNames: {
      root: classNames.root,
    },
  };

  return (
    <Flex vertical gap="medium">
      <Alert
        {...alertSharedProps}
        title="Object styles"
        type="info"
        styles={{
          icon: {
            fontSize: 18,
          },
          section: {
            fontWeight: 500,
          },
        }}
        action={<Button size="small">Action</Button>}
      />
      <Alert {...alertSharedProps} title="Function styles" type="success" styles={styleFn} />
    </Flex>
  );
};

export default App;

两个 <Alert> 分别验证了四种能力：

1. classNames 传对象：classNames.root 挂到一个由 antd-style 的 createStaticStyles 生成的静态类名上，覆盖根节点的边框、圆角和内边距。类名方案的优势是样式可缓存、可复用（示例中 alertSharedProps 被两个 Alert 共享），适合静态、可复用的规则。
2. styles 传对象：第一个 Alert 直接传 { icon: { fontSize: 18 }, section: { fontWeight: 500 } }，以 React 内联样式对象的形式生效，适合少量、即时的属性调整。
3. styles 传函数：第二个 Alert 传 styleFn，函数签名是 ({ props }) => Record<SemanticDOM, CSSProperties>。注意这里解构到的 props.type 不是原始属性，而是组件内部合并后的值（下文源码部分会解释），因此即使不显式传 type，在 banner 模式下也能正确拿到默认值 warning。
4. GetProp<AlertProps, 'styles', 'Return'>：借助 antd 导出的 GetProp 工具类型推导函数形式的返回类型，保证返回的对象键名只能是 7 个语义节点之一，获得完整的类型提示。

源码解析：配置如何被解析与合并

classNames / styles 进入组件后并不直接落 DOM，而是经过 Alert.tsx 中的一套"语义合并"流程。关键代码如下：

// =========== Merged Props for Semantic ==========
const mergedProps: AlertProps = {
  ...props,
  prefixCls,
  variant: mergedVariant,
  type,               // 已处理 banner 默认 'warning' 的逻辑
  showIcon: isShowIcon,
  closable: isClosable,
};

const contextStyleRoot = useSemanticRootStyle(contextStyle);
const styleRoot = useSemanticRootStyle(style);

const [mergedClassNames, mergedStyles] = useMergeSemantic<
  AlertSemanticAllType['classNames'],
  AlertSemanticAllType['styles'],
  AlertProps
>([contextClassNames, classNames], [contextStyles, contextStyleRoot, styles, styleRoot], {
  props: mergedProps,
});

这段代码揭示了三个重要机制：

1. 函数形式的入参是"合并后"的 props。 useMergeSemantic 的第三个参数 info.props 被传入的是 mergedProps——它已经补全了 prefixCls、variant、type、showIcon、closable 的默认值（其中 type 的默认逻辑见 Alert.tsx：banner 模式下默认 warning，否则 info）。这就是示例中函数能直接读 type 并正确区分 success/warning 的原因。

2. 合并优先级是"全局配置在前、组件属性在后"。 classNamesList 的顺序是 [contextClassNames, classNames]，stylesList 是 [contextStyles, contextStyleRoot, styles, styleRoot]。这里 contextClassNames / contextStyles 来自 useComponentConfig('alert')，即 ConfigProvider 的 theme.components.Alert 全局配置；styleRoot 则是把传统 style 属性"升级"到 root 语义节点上的映射。

3. 具体合并规则由 useMergeSemantic 实现。 在 useMergeSemantic/index.ts 中：

• 函数解析（resolveStyleOrClass）：对列表中每一项，isFunction(value) ? value(info) : value，即对象直接用、函数则以 { props } 求值；
• 类名合并（mergeClassNames）：多个来源中同一节点键用 clsx 拼接，因此全局配置和组件级的类名会同时生效而非互相覆盖；
• 样式合并（mergeStyles）：同一节点键按 { ...acc[key], ...cur[key] } 逐键浅合并，列表中靠后者的同名 CSS 属性会覆盖靠前者——即组件级 styles 优先于全局 styles，组件级 style 属性优先于组件级 styles.root。

合并完成后，结果被挂载到 Alert.tsx 的真实 DOM 上：根节点 className 中拼接 mergedClassNames.root、style 展开 mergedStyles.root；icon、section、title、description、actions 五个内部 <div>/<span> 以及 CloseIconNode（close 节点）也各自取用对应的 mergedClassNames.* 与 mergedStyles.*。需要注意 root 节点的内联样式顺序是 { ...mergedStyles.root, ...motionStyle }，关闭动画（CSSMotion）的过渡样式在动画期间会覆盖语义样式，这属于有意设计。

与基础样式、Token 的配合关系

语义样式是叠加在 Token 生成样式之上的"最后一公里"定制，而不是替代它们。Alert 的默认视觉规则在 style/index.ts 中定义：

• genBaseStyle 负责根节点的 flex 布局、defaultPadding 内边距、borderRadius 圆角，以及 -section（flex: 1; minWidth: 0）、-icon、-title、-description 等各语义类的基础规则；
• genTypeStyle 按 type 映射四种状态色（colorSuccessBg / colorInfoBg / colorWarningBg / colorErrorBg 等），这正是函数形式 styles 中常见的使用动机——按 type 动态微调背景与图标色；
• 组件 Token（如 borderRadius、defaultPadding、withDescriptionIconSize）可通过 ConfigProvider 的 theme.components.Alert 统一调整，适合"改设计语言"；而 classNames / styles 适合"改单个实例"。

版本要求与注意事项

• classNames / styles 属性要求 antd 6.0.0+（当前仓库 package.json 版本为 6.6.2，满足要求）；其中 close 语义节点在 6.1.0 才引入，6.0.x 中写 close 键不会命中任何节点；
• variant（outlined / filled 样式变体）是 6.4.0 引入的新属性，函数形式的 styles 入参中也能读到合并后的 variant，可用于按变体做样式分支；
• 官方文档中 message、onClose 等旧属性已标记废弃，分别请用 title、closable.onClose 替代；
• 类名方案与内联样式方案可以混用（示例即如此），但注意二者作用于不同挂载点：类名拼接到 className，内联样式写入 style 属性，同一 CSS 属性的最终表现由 CSS 层叠规则与内联样式优先级共同决定。

参考文件：

• 演示说明：components/alert/demo/style-class.md
• 演示代码：components/alert/demo/style-class.tsx
• 语义节点定义：components/alert/demo/_semantic.tsx
• 组件实现：components/alert/Alert.tsx
• 语义合并机制：components/_util/hooks/useMergeSemantic/index.ts
• 基础样式与 Token：components/alert/style/index.ts
• API 文档：components/alert/index.zh-CN.md