ant-design-blazor 指南:通过 ModalService 手动更新与销毁 Confirm 对话框
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);
}
}
整个流程可以拆解为三步:
- 创建:
_modalService.Success(props)以ConfirmOptions为配置创建并打开一个带成功图标的确认框,返回ConfirmRef类型的modelRef; - 更新:每秒修改
props.Content(即ConfirmOptions实例的字段),然后调用modelRef.UpdateConfigAsync()让对话框按最新配置重新渲染; - 销毁:倒计时归零后调用
_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 等)为按钮填充默认文案与危险样式。
底层原理:事件驱动的服务-容器协作
从源码结构看,这套"手动更新与销毁"机制建立在事件订阅之上,核心链路为:
- ModalServiceForConfirm.cs 定义四个内部事件:
OnConfirmOpenEvent、OnConfirmUpdateEvent、OnConfirmCloseEvent、OnConfirmCloseAllEvent; - ComfirmContainer.razor 这个"确认框容器"在
OnInitialized时订阅全部事件(见 ComfirmContainer.razor.cs),并把每个ConfirmRef渲染为一个<Confirm>组件; - 业务代码调用
_modalService.Success(props)时,事件被触发,容器把新ConfirmRef加入_confirmRefs列表并渲染; - 后续每次
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 应用中安全、高效地驾驭对话框的完整生命周期。