ant-design-blazor 中销毁确认对话框:`ModalService.DestroyAllConfirmAsync` 与路由切换场景实战解析
ant-design-blazor 中销毁确认对话框:ModalService.DestroyAllConfirmAsync 与路由切换场景实战解析
导读
在基于 ant-design-blazor 的单页应用中,通过 ModalService 弹出的确认对话框(Confirm)由服务动态创建,路由前进或后退时页面组件已卸载,对话框却可能残留并“钉”在界面上。本篇文章围绕官方 Demo confirm-router 展开,深入讲解 ModalService.DestroyAllConfirmAsync() 的作用、与单例销毁 DestroyConfirmAsync 的差异、底层事件订阅与路由监听的实现原理,并结合仓库源码给出可在路由监听中直接复用的完整方案。
一、问题场景:路由切换后残留的确认对话框
ModalService.Confirm()、Info()、Success()、Error()、Warning() 等方法创建的确认对话框是服务驱动的:它们通过 ComfirmContainer 组件渲染在页面级容器中,与发起弹窗的页面组件生命周期并不绑定。当用户在确认框弹出期间点击浏览器前进/后退、或执行路由跳转时,新页面组件已渲染完成,而旧对话框仍停留在屏幕上,形成“关不掉、无处关”的悬挂对话框。
ant-design-blazor 官方在 Modal 组件的 Demo 中提供了专门解法,见 confirm-router.md 文档:
使用
Modal.destroyAll()可以销毁弹出的确认窗。通常用于路由监听当中,处理路由前进、后退不能销毁确认对话框的问题。
需要说明的是:这里提到的 Modal.destroyAll() 是 Ant Design React 中的 API 命名;在当前 Blazor 仓库中,对应的真实方法为 ModalService.DestroyAllConfirmAsync(),这一点在组件文档 index.zh-CN.md 中明确列出,后续代码均以此为准。
二、核心 API:DestroyAllConfirmAsync 与 DestroyConfirmAsync 的差异
ModalService 是 partial class,其中用于确认对话框的一组方法实现在 ModalServiceForConfirm.cs。与销毁相关的两个核心方法如下:
// 关闭单个 Confirm 对话框
public async Task DestroyConfirmAsync(ConfirmRef confirmRef)
{
await (OnConfirmCloseEvent?.Invoke(confirmRef) ?? Task.CompletedTask);
}
// 关闭全部 Confirm 对话框
public async Task DestroyAllConfirmAsync()
{
await (OnConfirmCloseAllEvent?.Invoke() ?? Task.CompletedTask);
}
两者的使用定位(出自组件文档 index.zh-CN.md 原文):
ModalService.DestroyConfirmAsync(confirmRef):主动关闭,适用于明确持有某个ConfirmRef实例、需要定向关闭单个确认框的场景(例如确认后手动关闭);ModalService.DestroyAllConfirmAsync():批量销毁,适用于路由切换这类“被动关闭”场景,无需在各个页面分别持有返回值,一处调用即可清空所有确认对话框。
组件文档中的原话是:
通常用于路由监听当中,处理路由前进、后退不能销毁确认对话框的问题,而不用各处去使用实例的返回值进行关闭(
ModalService.DestroyConfirmAsync(config)适用于主动关闭,而不是路由这样被动关闭)。
三、官方 Demo 源码解析:一个按钮批量弹出与一键销毁
演示代码位于 ConfirmRouter.razor,完整实现如下:
@inject ModalService _modalService
<Button OnClick="@ShowConfirm">Confirm</Button>
@code {
private async Task DestroyAll()
{
await _modalService.DestroyAllConfirmAsync();
}
private async Task ShowConfirm()
{
RenderFragment icon = @<Icon Type="@IconType.Outline.ExclamationCircle" />;
RenderFragment content = @<Button OnClick="DestroyAll"> Click to destroy all </Button>;
for (int i = 0; i < 3; i++)
{
_modalService.Confirm(new ConfirmOptions()
{
Icon = icon,
Content = content,
});
await Task.Delay(500);
}
}
}
3.1 演示逻辑拆解
- 注入服务:通过
@inject ModalService _modalService注入ModalService(需要项目已配置依赖注入,并在App.razor中放置<AntContainer />,详见下文第五节); - 连续弹出多个确认框:
ShowConfirm在一个for循环中连续调用_modalService.Confirm(...),每次间隔 500ms,模拟“多个确认对话框同时存在”的状态; - 自定义图标与内容:
Icon使用IconType.Outline.ExclamationCircle展示感叹号图标;Content被设置为一个内嵌Button(内容为 “Click to destroy all”),点击该按钮触发DestroyAll; - 一键销毁:
DestroyAll调用await _modalService.DestroyAllConfirmAsync(),一次性关闭全部已弹出的确认对话框。
3.2 三个关键代码细节
_modalService.Confirm(...)返回的是ConfirmRef,Demo 中未持有返回值,这正是“被动关闭”场景的特征——调用方不需要逐个保存引用;ConfirmOptions只配置了Icon与Content,其余参数使用默认值(详见第四节);- 销毁按钮被放在了对话框内容区而非页面上,说明
DestroyAllConfirmAsync可以在任意上下文(包括对话框自身的渲染内容)中被调用,因为它走的是ModalService的全局事件。
四、ConfirmOptions 配置说明与默认值
Demo 中仅设置了两个属性,但了解完整配置有助于在生产环境中写出正确的代码。ConfirmOptions 定义于 ConfirmOptions.cs,其构造函数给出了关键默认值:
public ConfirmOptions()
{
Width = 416; // 默认宽度 416
Mask = true; // 默认显示遮罩
MaskClosable = false; // 默认点击遮罩不关闭
Locale = LocaleProvider.CurrentLocale.Confirm;
OkText = Locale.OkText; // 从当前 Locale 读取“确定”文案
CancelText = Locale.CancelText; // 从当前 Locale 读取“取消”文案
}
常用配置项一览(与组件文档 index.zh-CN.md 的 ConfirmOptions 表格一致):
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
AutoFocusButton |
指定自动获得焦点的按钮 | ConfirmAutoFocusButton |
ConfirmAutoFocusButton.Ok |
CancelText |
取消按钮文字,等价于 Button2Props.ChildContent |
string/RenderFragment |
Cancel |
Centered |
垂直居中展示 | bool |
false |
ClassName |
容器(.ant-modal)类名 |
string |
- |
Content |
内容 | string/RenderFragment |
- |
Icon |
自定义图标 | RenderFragment |
- |
MaskClosable |
点击蒙层是否允许关闭 | bool |
false |
OkText |
确认按钮文字,等价于 Button1Props.ChildContent |
string/RenderFragment |
确定 |
OkType |
确认按钮类型,等价于 Button1Props.Type |
ButtonType |
primary |
OkButtonProps |
ok 按钮 props,与 Button1Props 等价 |
ButtonProps |
- |
CancelButtonProps |
cancel 按钮 props,与 Button2Props 等价 |
ButtonProps |
- |
Title / TitleTemplate |
标题(模板优先) | string/RenderFragment |
null |
Width |
宽度 | string/double |
416 |
ZIndex |
设置 z-index | int |
1000 |
OnCancel / OnOk |
取消/确定回调,仅通过 ModalService 创建的 Confirm 触发 |
Func<ModalClosingEventArgs, Task> |
null |
此外,ConfirmOptions 还提供 Button1Props(LTR 模式最左侧按钮,默认 Type = ButtonType.Primary)、Button2Props、Button3Props 三个按钮属性,以及 OkCancel(是否显示取消按钮,默认由 ConfirmButtons 决定)等配置。
五、实现原理:事件订阅、路由监听与批量关闭
DestroyAllConfirmAsync 之所以能“一呼百应”,关键在于 ComfirmContainer 组件承担了所有确认对话框的宿主与生命周期管理。
5.1 事件注册与容器渲染
ComfirmContainer.razor.cs 在 OnInitialized 中把自身方法挂到 ModalService 的四个内部事件上,并订阅路由变更:
protected override void OnInitialized()
{
ModalService.OnConfirmOpenEvent += OnConfirmOpen;
ModalService.OnConfirmCloseEvent += OnConfirmClose;
ModalService.OnConfirmCloseAllEvent += OnConfirmCloseAll;
ModalService.OnConfirmUpdateEvent += OnConfirmUpdate;
ConfirmService.OnOpenEvent += OnConfirmOpen;
NavigationManager.LocationChanged += OnLocationChanged;
}
对应的渲染模板 ComfirmContainer.razor 遍历内存中的 _confirmRefs 列表,逐个渲染 Confirm 组件:
@foreach (ConfirmRef confirmRef in _confirmRefs)
{
var modalConfig = confirmRef.Config;
<Confirm @key="@modalConfig"
ConfirmRef="@confirmRef"
Config="@modalConfig"
OnRemove="@OnConfirmRemove"/>
}
而 ModalService.Confirm() 创建 ConfirmRef 后通过 OnConfirmOpenEvent 把引用“推送”进该列表,从而完成“服务创建 → 容器渲染”的闭环,见 ModalServiceForConfirm.cs:
public ConfirmRef Confirm(ConfirmOptions props)
{
props.CreateByService = true;
CheckConfirmOptionsIsNull(props);
ConfirmRef confirmRef = new ConfirmRef(props, this);
confirmRef.TaskCompletionSource = new TaskCompletionSource<ConfirmResult>();
OnConfirmOpenEvent?.Invoke(confirmRef);
return confirmRef;
}
5.2 批量关闭的内部流程
DestroyAllConfirmAsync 触发 OnConfirmCloseAllEvent,最终落到 OnConfirmCloseAll:
private async Task OnConfirmCloseAll()
{
// 拷贝列表,避免遍历过程中 _confirmRefs 被修改影响迭代
var confirmRefsTemp = new List<ConfirmRef>(_confirmRefs);
foreach (var confirmRef in confirmRefsTemp)
{
await OnConfirmClose(confirmRef);
}
}
OnConfirmClose 将 Visible 置为 false 并刷新界面;随后由 Confirm 组件的关闭逻辑完成 DOM 移除与引用清理。Confirm.razor.cs 中的 Close() 方法展示了完整关闭链路:
internal async Task Close()
{
if (Config.Visible)
{
Config.Visible = false;
await InvokeAsync(StateHasChanged);
await Task.Delay(250); // 等待关闭动画
if (OnRemove.HasDelegate)
{
await OnRemove.InvokeAsync(ConfirmRef); // 从 _confirmRefs 移除
}
ConfirmRef.OnClose?.Invoke();
}
}
从源码结构看,OnConfirmCloseAll 采用“先拷贝列表再逐个关闭”的策略,正是为了避免关闭过程中列表被 OnRemove 修改而引发迭代异常,这是批量销毁实现中值得借鉴的细节。
5.3 容器自身的路由监听兜底
值得注意:ComfirmContainer 自身已经订阅了 NavigationManager.LocationChanged,路由变化时会清空确认框列表:
private void OnLocationChanged(object sender, EventArgs e)
{
_confirmRefs.Clear();
InvokeStateHasChanged();
}
也就是说,容器对路由切换已有基础兜底。官方仍建议在路由监听中显式调用 DestroyAllConfirmAsync(),可以推断原因包括:一是让销毁行为确定可控(不依赖容器内部行为),二是配合 ConfirmRef.TaskCompletionSource 等机制让调用方得到完整关闭结果、并正确触发 OnClose 回调。在实践中,两种机制可以并存。
六、实战:在路由监听中自动销毁确认对话框
结合以上原理,给出在 Blazor 应用中对接路由切换的标准写法。以基于 NavigationManager.LocationChanged 的监听器为例:
public class ConfirmCleanupService : IDisposable
{
private readonly ModalService _modalService;
private readonly NavigationManager _navigation;
public ConfirmCleanupService(ModalService modalService, NavigationManager navigation)
{
_modalService = modalService;
_navigation = navigation;
_navigation.LocationChanged += OnLocationChanged;
}
private async void OnLocationChanged(object sender, LocationChangedEventArgs e)
{
// 路由前进/后退时,销毁所有由 ModalService 弹出的确认对话框
await _modalService.DestroyAllConfirmAsync();
}
public void Dispose()
{
_navigation.LocationChanged -= OnLocationChanged;
}
}
6.1 使用前提:AntContainer
ModalService 创建的对话框依赖 ComfirmContainer 承载。官方组件文档明确指出:
请确认已经在
App.Razor中添加了<AntContainer />组件。
因此使用 DestroyAllConfirmAsync 前,必须确保根组件中已渲染 AntContainer(组件源码位于 AntContainer.razor),否则 ModalService 的事件没有宿主订阅,弹窗与批量销毁均无法生效。
6.2 注册与释放
- 注册:在
Program.cs/Startup.cs中向 DI 容器注册ModalService(通常使用builder.Services.AddAntDesign()即可连带注册),并在App.razor中放置<AntContainer />; - 释放:实现
IDisposable的服务记得在Dispose中退订LocationChanged,避免监听器泄漏(对应容器自身的Dispose实现同样退订了全部事件,见 ComfirmContainer.razor.cs 的Dispose方法)。
七、相关 API 速览
围绕确认对话框,ModalService 还提供了以下方法(完整清单见组件文档 index.zh-CN.md):
- 同步创建:
Confirm、Info、Success、Error、Warning,返回ConfirmRef; - 异步创建:
ConfirmAsync、InfoAsync、SuccessAsync、ErrorAsync、WarningAsync,返回Task<bool>,用于判断用户点击的是 OK(true)还是 Cancel(false); - 更新与关闭:
UpdateConfirmAsync、DestroyConfirmAsync、DestroyAllConfirmAsync、CreateConfirmAsync、CreateConfirm、CreateConfirm<TComponent, ...>等; - 模板化创建:
CreateConfirm<TComponent, TComponentOptions, TResult>,可将自定义组件作为对话框内容并约定返回结果。
此外,ConfirmService(见 ConfirmService.cs)提供类似 WinForm MessageBox 的 Show 方法,始终返回 ConfirmResult 枚举(OK、Cancel、Abort、Retry、Ignore、Yes、No 等,见 ConfirmResult.cs),用于区分用户点击的具体按钮。二者定位不同:ModalService 只创建 OK-Cancel 风格的确认框并返回引用,ConfirmService 更接近系统消息框语义。
八、小结
ModalService.DestroyAllConfirmAsync() 是 ant-design-blazor 处理“路由切换残留确认对话框”问题的标准答案:
- 面向场景:路由前进、后退等被动式关闭,无需持有每个
ConfirmRef; - 实现机理:通过
ComfirmContainer订阅OnConfirmCloseAllEvent,拷贝列表后逐个执行关闭流程,并在组件销毁时自动退订; - 落地要点:确保
<AntContainer />已渲染、在LocationChanged中调用、注意监听器释放; - 配套能力:单个销毁用
DestroyConfirmAsync,主动关闭用ConfirmRef.CloseAsync(),需要按钮级结果时改用ConfirmService。
在 Blazor 单页应用中把上述监听服务与 AntContainer 一并配置好,即可彻底消除路由切换时“幽灵确认框”问题。
延伸阅读(仓库相对路径):
- 官方 Demo 文档:confirm-router.md 与演示代码 ConfirmRouter.razor
- 组件完整文档:index.zh-CN.md
- 核心实现:ModalServiceForConfirm.cs、ComfirmContainer.razor.cs、Confirm.razor.cs
- 配置模型:ConfirmOptions.cs
- JS 侧兜底工具:modalHelper.ts(
destroyAllDialog用于清理.ant-modal-root节点并恢复页面滚动)