Ant Design Notification 通知提醒框完全指南API、Hooks 调用、全局配置与源码原理【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-designNotification 是 Ant Designantd反馈类组件中的全局通知提醒框用于在系统界面的四个角展示通知信息适合承载复杂内容、交互操作与系统主动推送。本文基于 ant-design 仓库中的 Notification 官方文档 与其源码实现系统讲解静态方法、useNotificationHooks 调用、全局配置、进度条/堆叠等高级能力并深入剖析 context 丢失问题的根源与 FAQ 中常见疑问的底层原理帮助你在实际项目中正确地选用和配置 Notification。何时使用 Notification官方文档明确指出Notification 适合在系统四个角显示通知提醒信息经常用于以下场景较为复杂的通知内容内容包含标题、多行描述甚至自定义 ReactNode单纯用轻量级提示如 message无法承载带有交互的通知需要给出用户下一步的行动点例如附带动作按钮btn、可点击跳转等系统主动推送由系统后台或业务逻辑主动触发而非用户操作直接产生。与同为反馈类的 Message 组件 相比Notification 更强调“通知详情 可操作”而 message 更偏向轻量瞬时反馈。从源码结构看components/notificationNotification 内部基于rc-notification构建并在其之上封装了 antd 的样式系统cssinjs、主题 Token 与图标体系。快速上手两种调用方式antd 提供两种调用 Notification 的方式静态方法notification.open(config)、notification.success(config)等可在任意位置直接调用最便捷Hooks 方法notification.useNotification()官方推荐返回[api, contextHolder]能够正确获取 React context。方式一静态方法不推荐在需要 context 的场景使用notification.success({ message: 提交成功, description: 您的订单已提交请耐心等待审核。, placement: topRight, duration: 3, });静态方法支持以下 API详见 interface.ts 中NotificationInstance的定义notification.success(config)notification.error(config)notification.info(config)notification.warning(config)notification.open(config)notification.destroy(key?: String)从 index.tsx 源码可以看到success / info / warning / error本质是对open的封装内部通过methods.forEach为每个类型生成(config) open({ ...config, type })type会决定默认的图标与样式。方式二useNotification Hooks推荐import { notification, Button } from antd; const App: React.FC () { const [api, contextHolder] notification.useNotification(); const openNotification () { api.open({ message: Notification Title, description: This is the content of the notification. This is the content of the notification., }); }; return ( {contextHolder} Button typeprimary onClick{openNotification} Open the notification box /Button / ); };完整可运行示例见仓库演示文件 demo/hooks.tsx该示例展示了如何结合Context.Provider在通知内容中消费上下文并通过四个方向的按钮切换弹出位置。从 useNotification.tsx 的实现来看useNotification(config)内部调用useInternalNotification它持有holderRef返回的api对象通过React.useMemo构建open方法将传入的message / description / icon / btn等参数包装进PureContent再透传给rc-notification的opendestroy(key)在无 key 时销毁全部有 key 时仅关闭指定项。返回的第二个元素contextHolder即Holder /必须挂载到 JSX 树中才会生效。API 详解单条通知参数config以下参数适用于notification.success(config)等方法以及api.open(config)参数说明类型默认值版本btn自定义关闭按钮ReactNode--className自定义 CSS classstring--closeIcon自定义关闭图标5.7.0 起设置为null或false可隐藏关闭按钮ReactNodetrue5.7.0description通知提醒内容必选ReactNode--duration默认 4.5 秒后自动关闭配置为null则不自动关闭number4.5-showProgress显示自动关闭通知框的进度条booleanfalse5.18.0pauseOnHover悬停时是否暂停计时器booleantrue5.18.0icon自定义图标ReactNode--key当前通知唯一标志可用于更新或定向关闭string--message通知提醒标题必选ReactNode--placement弹出位置toptopLefttopRightbottombottomLeftbottomRightstringtopRight-style自定义内联样式CSSProperties--role供屏幕阅读器识别的通知内容语义默认alert此时屏幕阅读器会立即打断当前阅读内容转而朗读通知alert \| statusalert5.6.0onClick点击通知时触发的回调函数function--onClose当通知关闭时触发function--props透传至通知div的 props 对象支持data-*aria-*或role。注意虽然 TypeScript 类型声明支持传入data-*但目前运行时只允许data-testid受 TypeScript 类型系统限制 影响此链接为类型声明参考Object--以上参数与 interface.ts 中ArgsProps接口一一对应。几个值得注意的实现细节duration与pauseOnHover在 useNotification.tsx 中duration默认值由常量DEFAULT_DURATION 4.5兜底pauseOnHover默认true这两个参数连同showProgress会一并传入rc-notification由底层负责计时与进度条渲染。closeIcon与closable通过 PurePanel.tsx 中的getCloseIcon(prefixCls, closeIcon)处理——传入null或false返回null即隐藏关闭按钮否则返回自定义图标或默认的CloseOutlined随后closable: closable ?? !!realCloseIcon决定关闭按钮是否可用。placement的底层实现见 util.ts 的getPlacementStyle六种位置分别对应不同的 CSS 定位top/bottom为水平居中left: 50%transform: translateX(-50%)topLeft/bottomLeft靠左topRight/bottomRight靠右。默认图标映射success / info / error / warning分别对应CheckCircleFilled / InfoCircleFilled / CloseCircleFilled / ExclamationCircleFilled见 PurePanel.tsx 中TypeIcon传入自定义icon或type时通过PureContent渲染。useNotification 的全局配置参数notification.useNotification(config)的 config 参数如下参数说明类型默认值版本bottom消息从底部弹出时距离底部的位置像素number24-closeIcon自定义关闭图标5.7.0 起设为null或false隐藏关闭按钮ReactNodetrue5.7.0getContainer配置渲染节点的输出位置() HTMLNode() document.body-placement弹出位置toptopLefttopRightbottombottomLeftbottomRightstringtopRight-showProgress显示自动关闭通知框的进度条booleanfalse5.18.0pauseOnHover悬停时是否暂停计时器booleantrue5.18.0rtl是否开启 RTL 模式booleanfalse-stack堆叠模式超过阈值时将所有消息收起boolean |{ threshold: number }{ threshold: 3 }5.10.0top消息从顶部弹出时距离顶部的位置像素number24-maxCount最大显示数超过限制时最早的消息会被自动关闭number-4.17.0对应的 TypeScript 定义见 interface.ts 中NotificationConfig与 useNotification.tsx 中的常量DEFAULT_OFFSET 24、DEFAULT_PLACEMENT topRight。其中stack的默认行为在源码中体现为threshold默认为 3堆叠间距offset: 8、gap: token.margin即主题 Token 中的 margin当启用的通知条数超过阈值时其余通知会折叠为一个计数摘要。全局配置 notification.config还提供了一个全局配置方法可在调用前提前配置、全局一次生效notification.config({ placement: bottomRight, bottom: 50, duration: 3, rtl: true, });注意当使用ConfigProvider进行全局化配置时系统会默认自动开启 RTL 模式4.3.0。如需单独使用可通过上述rtl: true开启。notification.config 参数表参数说明类型默认值版本bottom消息从底部弹出时距离底部的位置像素number24-closeIcon自定义关闭图标5.7.0 起设为null或false隐藏关闭按钮ReactNodetrue5.7.0duration默认自动关闭延时秒number4.5-showProgress显示自动关闭通知框的进度条booleanfalse5.18.0pauseOnHover悬停时是否暂停计时器booleantrue5.18.0getContainer配置渲染节点的输出位置但依旧为全屏展示() HTMLNode() document.body-placement弹出位置toptopLefttopRightbottombottomLeftbottomRightstringtopRight-rtl是否开启 RTL 模式booleanfalse-top消息从顶部弹出时距离顶部的位置像素number24-maxCount最大显示数超过限制时最早的消息会被自动关闭number-4.17.0从源码看notification.config(options)对应 index.tsx 中的setNotificationGlobalConfig它将配置合并进defaultGlobalConfig后调用notification.sync()触发全局实例同步刷新因此后续所有通过静态方法弹出的通知都会继承该配置。进阶能力实战1. 自动关闭延时duration默认 4.5 秒后自动关闭设置为null则通知常驻需要用户手动关闭api.open({ message: Notification Title, description: 我会在 3 秒后自动关闭。, duration: 3, });2. 进度条与悬停暂停5.18.0showProgress: true会在通知底部展示一条随自动关闭倒计时递减的进度条配合pauseOnHover默认true可在鼠标悬停时暂停计时避免用户还没读完内容通知就消失了。示例见 demo/show-with-progress.tsxapi.open({ message: Notification Title, description: This is the content of the notification., showProgress: true, pauseOnHover: true, });3. 堆叠模式5.10.0stack开启后当通知数量超过threshold默认 3时所有消息会收拢折叠。可通过布尔值或对象精确控制const [api, contextHolder] notification.useNotification({ stack: { threshold: 3, // 超过 3 条即折叠 }, });完整交互示例含开关与阈值调节见 demo/stack.tsx。其底层实现在 useNotification.tsx 中stack false时完全关闭否则传入{ threshold, offset: 8, gap: token.margin }交给rc-notification处理。4. 自定义图标、按钮与样式api.open({ message: Notification Title, description: This is the content of the notification., icon: SmileOutlined style{{ color: #108ee9 }} /, btn: ( Space Button typelink sizesmall onClick{() api.destroy()} 知道了 /Button /Space ), });相关演示参见 demo/with-icon.tsx、demo/custom-icon.tsx、demo/with-btn.tsx 与 demo/custom-style.tsx。5. 更新消息内容通过key唯一标识通知再次以相同key调用即可原地更新内容避免重复弹窗api.open({ key: unique-key, message: 加载中..., duration: null }); // 稍后更新同一条通知 api.open({ key: unique-key, message: 加载完成, description: 数据已就绪, duration: 4.5, });对应演示见 demo/update.tsx定向关闭某一条通知则调用api.destroy(key)。6. 位置placement六种位置为top、topLeft、topRight、bottom、bottomLeft、bottomRight既可在单条配置中指定也可在useNotification或notification.config中全局指定。其定位样式由 util.ts 的getPlacementStyle生成配合top/bottom偏移量默认 24px确定最终位置。主题变量Design TokenNotification 支持通过主题 Token 定制样式官方文档中通过ComponentTokenTable componentNotification /自动渲染全部可配置 Token如colorBgElevated、colorText、borderRadiusLG、boxShadowSecondary、marginSM等。主题样式定义见 style/index.ts位置相关样式见 style/placement.ts堆叠样式见 style/stack.ts。你可以通过ConfigProvider的theme配置统一定制例如ConfigProvider theme{{ components: { Notification: { colorBgElevated: #fffbe6, colorText: #614700, }, }, }} App / /ConfigProviderFAQ常见问题的底层原理为什么静态方法拿不到 context、redux 和 ConfigProvider 的locale/prefixCls/theme配置直接调用notification.xxx()时antd 会通过动态渲染在文档根部创建一个全新的 React 实体其 context 与当前代码所在的 context 并不相同因此无法获取 context 信息。这一点在 index.tsx 中体现得十分清晰静态方法使用document.createDocumentFragment()创建独立的挂载碎片并通过render(GlobalHolderWrapper /, holderFragment)渲染全局实例调用方后续调用通过内部taskQueue任务队列转发open与destroy分别入队后由flushNotice统一执行所以它运行在与业务组件完全隔离的 React 树中。当你需要 context 信息例如 ConfigProvider 配置的内容时使用notification.useNotification()返回的api实体与contextHolder节点将其插入到需要获取 context 的位置即可const [api, contextHolder] notification.useNotification(); return ( Context1.Provider valueAnt {/* contextHolder 在 Context1 内它可以获得 Context1 的 context */} {contextHolder} Context2.Provider valueDesign {/* contextHolder 在 Context2 外因而不会获得 Context2 的 context */} /Context2.Provider /Context1.Provider );异同点通过 Hooks 创建的contextHolder必须插入到子元素节点中才会生效当你不需要上下文信息时直接调用静态方法即可。另外可通过 App 包裹组件 简化useNotification等方法需要手动植入contextHolder的问题。静态方法如何设置 prefixCls可以通过ConfigProvider.config进行设置该全局配置方法作用于静态渲染的根节点使静态方法弹出的通知也能使用自定义的类名前缀。总结简单场景用静态方法notification.success / error / info / warning / open开箱即用但拿不到业务 context需要 context 或 ConfigProvider 配置时用 HooksuseNotification()返回的contextHolder必须挂载进组件树全局默认行为用notification.config一次配置位置、偏移、延时、RTL、maxCount 等全局生效精细控制用单条参数duration、placement、icon、btn、key、role等可按条覆盖新特性按需开启5.10.0 的stack堆叠、5.18.0 的showProgress/pauseOnHover进度条能力均可在 Hooks 与全局配置中组合使用。如需深入源码可继续阅读 useNotification.tsxHooks 封装与默认值、index.tsx静态方法任务队列与全局实例、PurePanel.tsx内容渲染与图标体系、interface.ts全部类型定义以及tests目录 下的测试用例如 hooks.test.tsx、placement.test.tsx从而完整理解其行为约定与边界条件。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考