ng-zorro-antd Message 结束事件（onClose）：RxJS 驱动下的消息关闭回调与链式操作实战

UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载导读在 ng-zorro-antd 的 Message 全局提示组件中除了常规的弹出一条消息、自动消失用法外还存在一类更高级的交互模式通过订阅onClose事件在消息关闭时执行后续操作。本文以仓库中的 close 演示用例 为核心讲解NzMessageRef.onClose的类型定义、触发时机与底层实现并结合 RxJS 的concatMap演示依次打开多条消息的链式编排方案。读完本文你将能够订阅消息关闭事件完成回调、串联多个消息实现严格有序的提示队列并理解onClose与自动关闭、手动移除、动画结束之间的精确时序关系。一、需求场景为什么需要结束事件默认情况下Message 提示在顶部居中显示后会自动消失调用方通常只需要弹出即走无需关心它何时被关闭。但在以下场景中消息何时关闭恰恰是关键信息一条loading消息代表一个异步任务正在进行任务结束后需要立即弹出 success/error 结果提示二者必须严格先后衔接需要在一系列步骤完成时依次弹出多条提示且要求上一条关闭后才出现下一条消息关闭时需要同步清理外部状态、发送埋点或触发某个业务动作。close 演示用例 正是针对这类场景点击按钮后先弹出一条 loading 提示待其关闭后再弹出 success再关闭后再弹出 info全部完成后在控制台输出日志。二、onClose 的类型定义与事件语义2.1 NzMessageRef 的完整结构在 typings.ts 中可以看到所有NzMessageService方法success、error、info、warning、loading返回的对象类型为NzMessageRefexport type NzMessageRef PickRequiredNzMessageData, onClose | messageId;展开后即 官方 API 文档 中所描述的结构export interface NzMessageRef { messageId: string; onClose: Subjectboolean; // 当 message 关闭时它会派发一个事件 }messageId该消息实例的唯一标识可用于NzMessageService.remove(id)定向移除onClose一个 RxJSSubjectboolean当消息被关闭时会派发一次事件并自动完成complete。2.2 onClose 的载荷boolean 的含义Subjectboolean中的布尔值表示该消息是否由用户操作触发关闭true用户主动触发的关闭例如点击了提示上的关闭按钮false超时自动关闭或通过remove()移除。这一语义在 base.ts 的onRemove方法中得到印证protected onRemove(instance: RequiredD, userAction: boolean): void { instance.onClose!.next(userAction); instance.onClose!.complete(); }也就是说无论消息以何种方式消失onClose都会恰好发射一次next一次后立即complete随后订阅者不会再收到任何值也不会产生泄漏。这与消息只会被关闭一次的生命周期完全对应。2.3 创建时即注册 onClose在base.ts的onCreate中每个消息实例在被创建时就预置了独立的onCloseSubjectprotected onCreate(instance: D): RequiredD { instance.options this.mergeOptions(instance.options); instance.onClose new Subjectboolean(); return instance as RequiredD; }因此调用方可以在弹出消息后立即访问.onClose进行订阅而不必担心竞态问题。三、官方演示用 concatMap 串联三个消息3.1 完整示例代码close.ts 是仓库中该主题的官方演示完整代码如下import { Component, inject } from angular/core; import { concatMap } from rxjs/operators; import { NzButtonModule } from ng-zorro-antd/button; import { NzMessageService } from ng-zorro-antd/message; Component({ selector: nz-demo-message-close, imports: [NzButtonModule], template: button nz-button nzTypedefault (click)startShowMessages()Display a sequence of messages/button }) export class NzDemoMessageCloseComponent { private readonly message inject(NzMessageService); startShowMessages(): void { this.message .loading(Action in progress, { nzDuration: 2500 }) .onClose!.pipe( concatMap(() this.message.success(Loading finished, { nzDuration: 2500 }).onClose!), concatMap(() this.message.info(Loading finished is finished, { nzDuration: 2500 }).onClose!) ) .subscribe(() { console.log(All completed!); }); } }3.2 执行流程逐行拆解this.message.loading(Action in progress, { nzDuration: 2500 })弹出第一条loading消息2.5 秒后自动关闭访问其返回值NzMessageRef的.onClose开始构建 RxJS 链第一个concatMap监听 loading 的关闭事件一旦 loading 关闭就调用this.message.success(...)弹出第二条消息并返回其onClose继续等待第二个concatMap监听 success 的关闭事件一旦 success 关闭再调用this.message.info(...)弹出第三条消息最终subscribe(() console.log(All completed!))在 info 也关闭后输出日志表示整个队列执行完毕。由于onClose在complete之前只next一次concatMap恰好会在每一条消息关闭这一时刻被触发一次从而实现了严格串行、上一条关闭才弹出下一条的效果——这正是官方文档所描述的以上用例将依次打开三个 message。3.3 为什么选择 concatMapconcatMap的特性是每个源值按顺序处理前一个内部 Observable 完成后才开始下一个。在这里源source是 loading 的onClose它只会发射一次因此concatMap的回调只会执行一次弹出 success返回的 success.onClose成为新的内部 Observable其完成complete会驱动第二个concatMap整条链的节奏完全由各消息的关闭事件驱动不依赖外部定时器天然与 Message 的实际生命周期同步。这种以关闭事件为节拍的写法也适用于switchMap取消前序、mergeMap并行弹出等其他 RxJS 组合算子可按业务需要灵活替换。四、onClose 的触发时序关闭到底发生在哪一刻理解onClose的准确触发时机是正确使用它的前提。结合 base.ts 与 message.component.ts 的实现关闭流程分为两种情况4.1 自动关闭nzDuration 到期在NzMNComponent.ngOnInit中this.autoClose this.options.nzDuration 0; if (this.autoClose) { this.initErase(); this.startEraseTimeout(); }startEraseTimeout内部使用setTimeout(() this.destroy(), this.eraseTTL)启动倒计时。当计时到期调用destroy()时protected destroy(userAction: boolean false): void { this.userAction userAction; if (this.options.nzAnimate) { this._startLeaveAnimation(() this.destroyed.next({ id: this.instance.messageId, userAction })); } else { this.destroyed.next({ id: this.instance.messageId, userAction }); } }若nzAnimate: true默认会先播放MessageMoveOut离场动画动画结束后才发出destroyed事件若nzAnimate: false则立即发出destroyed事件。destroyed事件被容器捕获后调用remove($event.id, $event.userAction)进而触发上文onRemove中的onClose.next(userAction)与onClose.complete()。结论onClose的触发点位于消息完全从界面移除含离场动画播放完毕之后而不是倒计时结束的那一刻。如果你在onClose回调中紧接着弹出下一条消息视觉上两条消息不会重叠。4.2 手动移除调用NzMessageService.remove(id)定向或remove()清空时同样走NzMNContainerComponent.remove→onRemove的路径onClose同样只发射一次。该行为由 message.spec.ts 中的测试用例直接验证it(should emit event when message close, async () { const closeSpy vi.fn(); const msg messageService.create(loading, CLOSE); const messageId msg.messageId; msg.onClose.subscribe(closeSpy); messageService.remove(messageId); await stabilize(); expect(closeSpy).toHaveBeenCalledTimes(1); });该用例确认了手动 remove 一次onClose 恰好派发一次的语义。4.3 鼠标悬停暂停nzPauseOnHover对时序的影响当配置nzPauseOnHover: true默认值时鼠标移入消息会暂停倒计时onEnter(): void { if (this.autoClose this.options.nzPauseOnHover) { this.clearEraseTimeout(); this.updateTTL(); } } onLeave(): void { if (this.autoClose this.options.nzPauseOnHover) { this.startEraseTimeout(); } }这意味着实际关闭时间可能晚于nzDuration设定值onClose的派发也会相应延后。如果你的业务对消息必须在 X 毫秒后关闭有硬性要求请将nzPauseOnHover设为false。五、onClose 的实战配套duration、options 与全局配置5.1 单条消息的 options 参数onClose通常与 duration 演示用例 中的nzDuration配合使用控制每条消息的展示时长createBasicMessage(): void { this.message.success(This is a prompt message for success, and it will disappear in 10 seconds, { nzDuration: 10000 }); }NzMessageDataOptions见 typings.ts支持的完整参数如下参数说明类型nzDuration持续时间毫秒设置为 0 时不自动消失numbernzAnimate开关动画效果影响 onClose 触发时刻booleannzPauseOnHover鼠标移上时禁止自动移除booleannzData传递给自定义模板的数据NzSafeAnynzStyle自定义内联样式NgStyleInterface \| stringnzClass自定义 CSS classNgClassInterface \| string注意nzDuration: 0时消息不会自动关闭autoClose为false此时只能通过remove()手动关闭onClose也只会因手动移除而触发。5.2 全局配置与默认值默认配置定义在 message-container.component.ts 的NZ_MESSAGE_DEFAULT_CONFIG中const NZ_MESSAGE_DEFAULT_CONFIG: RequiredMessageConfig { nzAnimate: true, nzDuration: 3000, nzMaxStack: 7, nzPauseOnHover: true, nzTop: 24, nzDirection: ltr };可通过provideNzConfig({ message: { ... } })或NzConfigService覆盖全局默认值详见 全局配置项。上述 close 演示中三条消息都显式传入了nzDuration: 2500以此覆盖全局的 3000 毫秒默认值。5.3 服务方法速览NzMessageService 提供的方法均返回NzMessageRef因此每个方法的返回值都可直接访问.onClosesuccess(content, options?)error(content, options?)info(content, options?)warning(content, options?)loading(content, options?)create(type, content, options?)此外还有remove(id?)传入messageId时定向移除某条消息此时其onClose触发并携带userAction: false不传参数时移除全部消息。六、实现原理从调用到 onClose 派发的完整链路综合 message.service.ts 与 base.ts一次弹出消息 → 订阅 onClose的完整调用链如下NzMessageService.success(...)调用createInstance生成messageId格式为message-自增计数与createdAt通过withContainer在全局 overlay 中创建或复用NzMessageContainerComponent容器create()内部调用onCreate为实例创建独立的onCloseSubject并将单条 options 与全局配置合并mergeOptions消息组件NzMessageComponent挂载渲染nzDuration 0时启动倒计时message.component.ts到期或手动remove→destroy()→ 可选离场动画 → 容器remove()→onRemove()→onClose.next(userAction)onClose.complete()订阅者在此时收到一次值并在流结束后执行链式回调。整个过程中NzMessageService以单例形式注入providedIn: root并通过NzSingletonService与 overlay 机制保证全局只有一个消息容器任何位置调用服务方法都能弹出提示。相关单测覆盖了五种消息类型、模板内容、自动关闭、悬停暂停、手动移除、最大堆叠、自定义样式与 RTL 等场景见 message.spec.ts可作为行为契约参考。七、常见误区与最佳实践误区/疑问澄清认为 onClose 在倒计时结束瞬间触发实际上在消息完全移除含离场动画之后才触发关闭nzAnimate可取消动画延迟担心订阅泄漏onClose在消息关闭时complete()RxJS 会自动清理无需手动退订把 onClose 当作可多次触发的事件它恰好发射一次适合concatMap/switchMap这类单发编排需要严格定时关闭默认nzPauseOnHover: true会在悬停时暂停倒计时需关闭该选项在模板中直接用 onCloseonClose是服务返回对象NzMessageRef上的属性只能在调用方 TS 代码中访问推荐做法在组件中使用 Angular 17 的inject(NzMessageService)如 demo 所示获取服务实例将消息关闭后的后续动作统一放进onClose的 RxJS 链中保持时序一致性若需要并行弹出多条消息后统一处理可将多个onClose用forkJoin/combineLatest组合若需要在某条消息被用户主动关闭时做差异化处理可检查onClose发射的布尔值true为用户操作。结语onClose是 ng-zorro-antd Message 组件中连接消息生命周期与业务逻辑的桥梁。借助它你可以在消息关闭无论是自动、手动还是动画结束后的精确时机执行回调并通过 RxJS 操作符将多条消息编排成严格有序的提示队列。本文演示的concatMap链式写法可以直接迁移到 loading → success/error 的任务结果提示、向导式分步引导等常见业务场景中是 Message 组件进阶用法的核心技能之一。赞分享UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载相关推荐ng-zorro-antd Alert 可关闭警告提示Closable实战指南关闭按钮、事件回调与源码原理ng zorro antd Alert 可关闭警告提示Closable实战指南关闭按钮、事件回调与源码原理 导读 在 Angular 应用中 nz alUI组件前端ng-zorro-antd Notification 自定义操作按钮nzButton实战指南ng zorro antd Notification 自定义操作按钮nzButton实战指南 本文聚焦 ng zorro antd 通知提醒框NotifiUI组件前端React Native CarPlay 权限与证书配置快速获取苹果CarPlay权限的终极指南React Native CarPlay 权限与证书配置快速获取苹果CarPlay权限的终极指南 React Native CarPlay 是让Reac上一篇ip2region 完全解析微秒级离线 IP 定位如何实现下一篇终极TeamSpeak3音乐机器人搭建指南5分钟实现语音聊天室音频播放创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考