ant-design-blazor 中销毁确认对话框:`ModalService.DestroyAllConfirmAsync` 与路由切换场景实战解析

原创2026-10-11 14:17:531,880 阅读
文章标签:前端UI组件设计系统WebAssembly

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 三个关键代码细节

  1. _modalService.Confirm(...) 返回的是 ConfirmRef,Demo 中未持有返回值,这正是“被动关闭”场景的特征——调用方不需要逐个保存引用;
  2. ConfirmOptions 只配置了 Icon 与 Content,其余参数使用默认值(详见第四节);
  3. 销毁按钮被放在了对话框内容区而非页面上,说明 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 一并配置好,即可彻底消除路由切换时“幽灵确认框”问题。

延伸阅读(仓库相对路径):

登录后查看全文
ant-design-blazor