ant-design-blazor 指南:通过 ModalService 手动更新与销毁 Confirm 对话框

原创2026-10-11 20:39:011,696 阅读
文章标签:UI组件前端

ant-design-blazor 指南:通过 ModalService 手动更新与销毁 Confirm 对话框

导读

在 ant-design-blazor 中,ModalService 不仅支持"一次性弹出"确认框,还允许你在对话框已经打开之后,继续通过返回的 ConfirmRef 引用手动更新内容、动态倒计时、中途修改文案,乃至主动销毁对话框。本文以官方示例 manual.md 与配套演示 Manual.razor 为主线,结合 ModalServiceForConfirm.cs、ConfirmRef.cs 等源码实现,完整讲解"手动更新和移除 Modal.method 方式创建的对话框"这一能力,读完你即可写出倒计时关闭、服务端任务进度提示等需要"事后更新"的交互。

适用场景:为什么需要手动更新与销毁

ModalService.Confirm / Success / Info 等方法是"创建即打开"的一步到位式 API,适合静态文案的提示框。但真实业务经常需要对话框打开后继续响应状态变化,典型场景包括:

  • 倒计时自动关闭:如"操作将在 N 秒后自动关闭",需要每秒刷新一次提示文案;
  • 任务进度提示:后台任务分阶段推进时,实时改写对话框内容;
  • 请求超时兜底:等待用户确认期间超时,主动强制销毁对话框;
  • 批量清理:路由切换或页面销毁时,一次性关闭所有由服务创建的确认框。

这些场景的共同点在于:对话框的生命周期不再由用户点击按钮决定,而是由业务代码控制。ant-design-blazor 为此提供了 ConfirmRef(对话框实例引用)和 UpdateConfigAsync() / DestroyConfirmAsync() 两个核心方法。

完整示例:5 秒倒计时后自动销毁

官方演示 Manual.razor 是理解这套机制的最佳入口,其完整逻辑如下:

@inject ModalService _modalService

<Button OnClick="@CountDown">Open modal to close in 5s</Button>

@code {

    private async Task CountDown()
    {
        var secondsToGo = 5;
        var props = new ConfirmOptions()
        {
            Title = "This is a notification message",
            Content = $"This modal will be destroyed after {secondsToGo} second."
        };
        var modelRef = _modalService.Success(props);
        while (secondsToGo > 0)
        {
            secondsToGo -= 1;
            await Task.Delay(1000);
            props.Content = $"This modal will be destroyed after {secondsToGo} second.";
            await modelRef.UpdateConfigAsync();
        }
        await _modalService.DestroyConfirmAsync(modelRef);
    }
}

整个流程可以拆解为三步:

  1. 创建:_modalService.Success(props) 以 ConfirmOptions 为配置创建并打开一个带成功图标的确认框,返回 ConfirmRef 类型的 modelRef;
  2. 更新:每秒修改 props.Content(即 ConfirmOptions 实例的字段),然后调用 modelRef.UpdateConfigAsync() 让对话框按最新配置重新渲染;
  3. 销毁:倒计时归零后调用 _modalService.DestroyConfirmAsync(modelRef) 主动关闭对话框。

值得注意的实现细节是:modelRef 与 props 指向同一个 ConfirmOptions 实例——从 ConfirmRef.cs 的 public ConfirmOptions Config { get; private set; } 可以看出,ConfirmRef 内部保存了创建时传入的配置对象,因此在外部直接修改 props 字段,ConfirmRef.Config 会同步感知,随后只需触发一次"刷新"即可。

核心 API 解析:创建、更新、销毁

创建对话框:Confirm 与快捷方法

ModalService 中所有创建确认框的方法最终都汇聚到 Confirm(ConfirmOptions props),见 ModalServiceForConfirm.cs:它会设置 props.CreateByService = true、做空值校验、新建 ConfirmRef 并挂上 TaskCompletionSource,最后触发 OnConfirmOpenEvent 让容器渲染。除基础 Confirm 外,还提供了带图标的快捷方法,它们都会额外设置 ConfirmIcon 并把 OkCancel 置为 false(即只显示 OK 按钮):

方法 图标 说明
Confirm(props) 无(confirm 风格) 标准 OK-Cancel 双按钮确认框
Info(options) Info 信息图标 信息提示
Success(options) Success 成功图标 成功提示(示例中使用的正是它)
Error(options) Error 错误图标 错误提示
Warning(options) Warning 警告图标 警告提示

对应的异步变体 ConfirmAsync / InfoAsync / SuccessAsync / ErrorAsync / WarningAsync 则会在用户点击后通过 TaskCompletionSource 返回 bool(点击 OK 为 true),见 ModalServiceForConfirm.cs。

更新对话框:UpdateConfigAsync 的两种用法

ConfirmRef 继承自 FeedbackRefWithOkCancelBase,提供了两个更新入口,见 ConfirmRef.cs:

  • 无参重载 UpdateConfigAsync():使用 ConfirmRef.Config 当前指向的配置对象进行刷新。适合"先改外部 props 字段、再通知刷新"的写法,示例中的 props.Content = ...; await modelRef.UpdateConfigAsync(); 就是这种模式;
  • 带参重载 UpdateConfigAsync(ConfirmOptions config):整体替换配置对象。实现为 Config = config; await UpdateConfigAsync();,适合一次性传入一份全新的配置。

两者最终都会调用 ModalService.UpdateConfirmAsync(confirmRef),底层触发 OnConfirmUpdateEvent(见 ModalServiceForConfirm.cs)。

更新请求到达 ComfirmContainer.razor.cs 的 OnConfirmUpdate 后,会先检查 confirmRef.Config.Visible:只有对话框仍处于可见状态才会调用 InvokeAsync(StateHasChanged) 触发重渲染。这保证了更新操作不会意外"复活"一个已关闭的对话框。

销毁对话框:DestroyConfirmAsync 与批量关闭

ModalService.DestroyConfirmAsync(ConfirmRef confirmRef) 触发 OnConfirmCloseEvent(见 ModalServiceForConfirm.cs),容器侧 OnConfirmClose 的处理逻辑为:

if (confirmRef.Config.Visible)
{
    confirmRef.Config.Visible = false;
    await InvokeAsync(StateHasChanged);
    if (confirmRef.OnClose != null)
    {
        await confirmRef.OnClose.Invoke();
    }
}

即先把 Visible 置为 false 隐藏对话框,再回调 OnClose。如果你需要一次关闭全部确认框,可以使用 DestroyAllConfirmAsync(),其容器实现会先拷贝 _confirmRefs 列表再逐个关闭,避免遍历过程中集合被修改(见 ComfirmContainer.razor.cs)。

补充:主动关闭与重新打开

ConfirmRef 还提供了对称的 CloseAsync() 与 OpenAsync():

  • CloseAsync() 等价于调用 Service.DestroyConfirmAsync(this);
  • OpenAsync() 调用 Service.OpenConfirmAsync(this),可重新唤起已创建的引用。

这与"销毁"的区别在于:CloseAsync 只关闭当前对话框实例,DestroyConfirmAsync 语义上也是关闭指定引用;而 DestroyAllConfirmAsync 是全局清理,常用于导航离开时的资源回收。事实上 ComfirmContainer.razor.cs 订阅了 NavigationManager.LocationChanged,路由变化时会清空 _confirmRefs 列表,避免跨页面残留对话框。

配置项速查:ConfirmOptions 关键参数

示例中只用到了 Title 和 Content,但手动更新场景下你通常还会用到以下配置(均定义于 ConfirmOptions.cs):

属性 默认值 说明
Title / TitleTemplate null 标题,支持字符串或 RenderFragment 模板
Content null 内容,OneOf<string, RenderFragment>,手动更新时最常修改的字段
Width 416 对话框宽度
Mask true 是否显示遮罩
MaskClosable false 点击遮罩是否可关闭(Confirm 默认不允许)
OkText / CancelText 取自 Locale 按钮文案,可覆盖默认的 OK / Cancel
AutoFocusButton ConfirmAutoFocusButton.Ok 打开后自动聚焦的按钮
OkCancel true 是否显示取消按钮;Success 等方法会将其置为 false
OnOk / OnCancel null 按钮点击回调(仅在 ModalService 创建的 Confirm 中触发)
Button1Props / Button2Props / Button3Props 见源码 按钮级属性,如 Type、Danger、Loading

构造时 ConfirmOptions.cs 会使用 LocaleProvider.CurrentLocale.Confirm 初始化 OkText 与 CancelText,配合 BuildButtonsDefaultOptions() 按 ConfirmButtons(OK、OKCancel、YesNo、YesNoCancel、RetryCancel、AbortRetryIgnore 等)为按钮填充默认文案与危险样式。

底层原理:事件驱动的服务-容器协作

从源码结构看,这套"手动更新与销毁"机制建立在事件订阅之上,核心链路为:

  1. ModalServiceForConfirm.cs 定义四个内部事件:OnConfirmOpenEvent、OnConfirmUpdateEvent、OnConfirmCloseEvent、OnConfirmCloseAllEvent;
  2. ComfirmContainer.razor 这个"确认框容器"在 OnInitialized 时订阅全部事件(见 ComfirmContainer.razor.cs),并把每个 ConfirmRef 渲染为一个 <Confirm> 组件;
  3. 业务代码调用 _modalService.Success(props) 时,事件被触发,容器把新 ConfirmRef 加入 _confirmRefs 列表并渲染;
  4. 后续每次 UpdateConfigAsync() / DestroyConfirmAsync() 调用都只是再次触发对应事件,由容器统一驱动 StateHasChanged。

ModalService 通过 ServiceCollectionExtensions.cs 注册为可注入服务,且 Confirm 组件本身被注释明确提醒"不要直接使用,请通过 ModalService 或 ConfirmService 创建"(见 Confirm.razor.cs),因此示例中的 @inject ModalService _modalService 正是官方推荐的接入方式。

延伸:模态对话框(Modal)同样支持手动更新

Modal.method 之外,ModalService.CreateModal(ModalOptions) 创建的模态对话框也提供完全对称的引用能力。CreateModal 返回 ModalRef(见 ModalServiceForModal.cs),其核心成员包括:

  • UpdateConfigAsync():刷新对话框配置;
  • CloseAsync():关闭对话框;
  • OpenAsync():打开对话框;
  • SetConfirmLoading(bool loading):动态切换确认按钮的加载状态(见 ModalRef.cs)。

因此,如果你的需求是更新"普通 Modal"而非确认框,只需把 ConfirmOptions 换成 ModalOptions、把 ConfirmRef 换成 ModalRef,更新的调用模式完全一致。

使用建议与注意事项

  • 修改后必须调用更新方法:直接改 props.Content 不会自动触发重渲染,必须紧跟 await modelRef.UpdateConfigAsync();;
  • 更新前确认对话框仍可见:容器在 Visible == false 时会忽略更新请求,所以长时间异步任务中若对话框已被用户手动关闭,更新操作不会产生副作用;
  • 用 async/await 串联倒计时:示例中使用 Task.Delay(1000) 配合 while 循环实现每秒刷新,避免阻塞 UI 线程;
  • 合理选择销毁 API:单实例用 DestroyConfirmAsync(modelRef) 或 modelRef.CloseAsync(),全局清理用 DestroyAllConfirmAsync();
  • 服务注册:使用前需确保 ModalService 已通过 DI 注入(services.AddAntDesign() 默认完成),并在组件中 @inject ModalService _modalService。

小结

"手动更新和移除"是 ModalService 体系中最具动态性的能力:通过 ConfirmRef 引用,开发者可以在确认框打开后自由改写标题、内容、按钮状态,并在任意时机主动销毁——官方 5 秒倒计时示例只是最直观的用法,同样的机制可以扩展到任务进度、超时兜底、批量清理等各类需要"事后控制"的业务场景。结合本文梳理的 ConfirmOptions 配置项与事件驱动源码链路,你可以在自己的 Blazor 应用中安全、高效地驾驭对话框的完整生命周期。

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