Ant Design（antd）Message 堆叠（Stack）配置指南：threshold 阈值与折叠展示机制

Message 堆叠（Stack）是 antd 6.4.0 引入的一项全局消息管理能力：默认关闭，当同时弹出的消息数量超过 threshold 阈值后，多余消息会自动收起为堆叠列表，折叠态下仅展示最新一条消息。本文以仓库中的 stack 演示文档 与配套 stack 示例源码 为骨架，结合 useMessage、useStackConfig 等源码实现，完整讲解该特性的配置方式、参数语义与底层原理，帮助你控制高频通知场景下的界面混乱问题。

一、堆叠特性是什么

在 message 组件所处的 components/message/demo/stack.md 中，官方对堆叠特性的描述为：

• 堆叠配置默认关闭（disabled by default）；
• 当消息数量超过 threshold 设定的阈值后，消息会自动被收起（stacked）；
• 折叠状态下仅展示最新的一条消息（Only the latest message is shown in the collapsed stack）。

直观理解：在不开启堆叠时，连续弹出的 message 会从上到下逐条占满屏幕顶部；开启堆叠后，消息区域会被压缩成一个紧凑列表，只有最新到达的那一条完整可见，其余历史消息折叠成计数形态，待其自动消失后逐一补齐展示。

该特性由示例文件 components/message/demo/stack.tsx 提供可交互演示，并同步在 组件主文档 的 API 表格中登记为 stack 配置项，类型为 boolean | { threshold: number }，默认值 false，引入版本为 6.4.0。

二、如何在 Demo 中配置堆叠

示例 Demo 通过 message.useMessage(config) 钩子创建受控的消息实例，并把 stack 作为配置对象传入：

import React from 'react';
import { Button, Divider, InputNumber, message, Space, Switch } from 'antd';

const App: React.FC = () => {
  const [enabled, setEnabled] = React.useState(true);
  const [threshold, setThreshold] = React.useState(3);
  const indexRef = React.useRef(0);
  const [messageApi, contextHolder] = message.useMessage({
    stack: enabled
      ? {
          threshold,
        }
      : false,
  });

  const openMessage = () => {
    indexRef.current += 1;
    const isOdd = indexRef.current % 2 === 1;

    messageApi.open({
      type: 'info',
      content: isOdd
        ? `Message ${indexRef.current}: This is a stacked message.`
        : `Message ${indexRef.current}: This is a slightly longer stacked message.`,
      duration: 0,
    });
  };

  return (
    <>
      {contextHolder}
      <Space size="large">
        {/* ...Enabled Switch / Threshold InputNumber 控件... */}
      </Space>
      <Divider />
      <Space>
        <Button type="primary" onClick={openMessage}>
          Open the message box
        </Button>
        <Button onClick={() => messageApi.destroy()}>Destroy all</Button>
      </Space>
    </>
  );
};

export default App;

要点拆解：

1. 开关与阈值联动：Switch 控制 enabled 状态，当其为 true 时传入 { threshold } 对象，否则直接传 false（等价于关闭堆叠）。这印证了 stack 参数是一个可动态切换的配置项。
2. 阈值范围：InputNumber 的 min 为 1、max 为 10、步长 step={1}，即演示环境建议在 1～10 之间调节触发堆叠的消息数量，Demo 初始阈值为 3。
3. 常驻消息便于观察：每次打开消息时设置 duration: 0，使消息不会自动消失，方便反复点击 Open the message box 按钮观察超过阈值后消息被折叠、只展示最新一条的过程。
4. 内容差异化：偶数/奇数序号消息使用不同长度的文案，用于区分堆叠列表中被折叠的各条历史消息。
5. 提供销毁兜底：Demo 额外提供了 Destroy all 按钮调用 messageApi.destroy()，可将当前全部消息清空（也可按 key 定向销毁指定消息）。

三、stack 参数完整 API 语义

从 components/message/interface.ts 可以看到 ConfigOptions 中的完整定义：

export interface ConfigOptions {
  top?: string | number;
  duration?: number;
  prefixCls?: string;
  getContainer?: () => HTMLElement;
  transitionName?: string;
  maxCount?: number;
  rtl?: boolean;
  stack?: boolean | { threshold?: number };
  pauseOnHover?: boolean;
  classNames?: MessageSemanticAllType['classNamesAndFn'];
  styles?: MessageSemanticAllType['stylesAndFn'];
}

对应官方 API 表格（components/message/index.en-US.md）：

Property	Description	Type	Default	Version	Global Config
stack	Messages will be stacked when amount is over threshold. Only the latest message is shown in the collapsed stack	boolean | { threshold: number }	false	6.4.0	×

参数语义说明：

• stack: false：默认值，关闭堆叠，所有消息按原顺序逐条展示；
• stack: true：开启堆叠，但使用组件内置的默认 threshold；
• stack: { threshold: number }：开启堆叠并自定义阈值——只有当前存活消息数量超过该数值时才触发折叠，等于或低于阈值时消息仍然全部展开显示。

说明：API 表格最后一列 “Global Config” 标记为 ×，表示该配置不通过 ConfigProvider 的组件级 componentConfig 下发，而应作为 message.useMessage() / 静态方法 message.config() 的配置使用（详见下文）。

四、源码视角：配置如何被消费

4.1 默认值由 useMessage 统一收敛

在 components/message/useMessage.tsx 顶部定义了相关默认常量：

const DEFAULT_OFFSET = 8;
const DEFAULT_DURATION = 3;
const DEFAULT_STACK_CONFIG = false;

其中 DEFAULT_STACK_CONFIG = false 即为 stack 的默认关闭值。Holder 组件将外部传入的 stack 交给专门的处理函数：

const stackConfig = useStackConfig(stack, DEFAULT_STACK_CONFIG);

随后作为 stack: stackConfig 传给底层 @rc-component/notification 的 useRcNotification，由它完成真正的折叠渲染。

4.2 useStackConfig 的参数归一化

useStackConfig 实现在 components/notification/hooks/useStackConfig.ts，其核心逻辑可概括为：

1. stackConfig ?? defaultStackConfig——未传值时落到默认的 false；
2. 若结果为 falsy（false / undefined / null），直接返回 false 关闭堆叠；
3. 否则返回一个合并后的对象：先展开默认对象配置，再覆盖展开用户传入的配置，最终把 boolean | StackConfig 统一收敛为对象形态，保证下游处理逻辑一致。

因此无论你传 true 还是 { threshold: 3 }，最终到达渲染层的一定是一个可解析的配置对象，这正是示例中 stack 可被 Switch 动态切成 false 也不会报错的原因。

4.3 三种承载方式

1. Hook 方式（Demo 所用）：message.useMessage({ stack: { threshold } }) 生成的 messageApi 与当前组件的上下文绑定，是官方推荐的现代用法，如 stack.tsx 所示；
2. 静态实例方式：由 components/message/index.tsx 暴露的全局单例 message（message.info / message.open 等）管理。其全局配置同步逻辑 getGlobalContext() 中同样解构并透传了 stack 字段，因此可通过 message.config({ stack: { threshold: 3 } }) 一次性设定全局堆叠策略；
3. 非堆叠兜底：在 components/message/PureList.tsx 中，纯展示列表被固定为 stack={false}，说明折叠属于动态运行时行为，纯面板/纯列表的受控渲染场景保持普通平铺形态。

4.4 折叠态样式由 token 驱动

堆叠折叠态并不是简单地把多余节点隐藏，而是由消息列表样式层专门生成占位与展开样式。在 components/message/style/index.ts 中可以找到相关注释与规则，例如 ant-message-stack（折叠堆叠容器）、ant-message-stack-expanded（展开态）等 class。stackVisibleCount: 1 之类的 token 传递进一步说明：折叠态下视觉层始终按"仅 1 条可见 + 其余折叠"的规则渲染，与文档所述 "Only the latest message is shown in the collapsed stack" 完全对应。

五、真实场景中的应用建议

结合 threshold 触发阈值与 duration 自动消失机制，可以在不同业务场景下给出如下实践参考（以仓库当前配置能力为限）：

• 联调/操作反馈类高频提示：日志上报、批量操作成功/失败等短时间并发消息较多时，可设置 threshold: 3，避免消息区域被多条提示占满，用户只关注最新一条，历史消息待逐条消失后自然补齐；
• 长文案消息：示例中采用了 duration: 0 的常驻消息来做堆叠演示，实际业务中若消息文案较长，建议配合 pauseOnHover 在鼠标悬停时暂停计时，防止用户尚未读完就被自动收起；
• 阈值不宜过小：InputNumber 的 min={1} 意味着即使只同时存在两条消息，若 threshold: 1 也会触发折叠，因此除非业务上确实需要"只显示最新一条"，否则阈值可保持在 2～3 以上以兼顾信息量与整洁度。

六、测试与快照：行为的可验证性

仓库为 message 组件的所有 Demo 维护了自动化快照测试，堆叠示例对应的快照文件位于 components/message/tests/snapshots/demo.test.ts.snap 与 components/message/tests/snapshots/demo-extend.test.ts.snap。如果你需要深入理解该特性的实际 DOM 输出与折叠结构，可以在仓库中搜索这两个快照里与 stack 相关的节点断言，作为自定义样式或二次封装时的重要参考。

小结

Message 的堆叠配置通过单一 stack 参数即可获得"超阈值自动折叠、折叠态仅展示最新消息"的完整行为：Demo 中 Switch + InputNumber 的组合演示了 { threshold } 的动态配置，源码中 useStackConfig 负责把 boolean/对象参数归一化，样式层以 stackVisibleCount 等 token 驱动折叠态的视觉呈现。掌握这一特性后，你可以在消息通知频繁的业务场景中有效收敛视觉噪音，让用户始终聚焦在最新一条系统反馈上。