使用 ModalService 创建 Modal 模板组件对话框:ant-design-blazor 服务式弹窗实战指南
使用 ModalService 创建 Modal 模板组件对话框:ant-design-blazor 服务式弹窗实战指南
本文以 ant-design-blazor 官方示例《Modal 模板组件(ModalTemplate)》为线索,系统讲解如何通过 ModalService 以编程方式创建并打开自定义内容模板的 Modal 对话框,涵盖服务注册、FeedbackComponent 基类、ModalRef 生命周期回调、带返回值模板以及底层事件机制,帮助你完全掌握"代码控制弹窗"这一开发模式。
为什么要用 ModalService 创建模板弹窗
常规的 Modal 用法是在 Razor 页面中直接声明 <Modal Visible="@visible">...</Modal>,由页面自行维护 Visible 状态。但当弹窗需要在多处复用、或者希望把弹窗内容封装成独立组件时,命令式的 ModalService 模式更加灵活:你可以在任意事件处理器中通过一行服务调用把弹窗"推"出来,并在代码层面拿到 ModalRef 句柄,从而精准控制打开、关闭、更新配置与结果回传。
官方示例 modal_service_for_modal.md 演示的正是这种模式:通过 ModalService 创建一个 Modal 对话框,并在其中渲染一个自定义组件(一个登录表单)。模板代码位于 ModalTemplateDemo.razor,调用代码位于 Modal_service_for_modal.razor。
第一步:把 ModalService 注册进依赖注入容器
ModalService 由 AddAntDesign() 扩展方法统一注册,见 ServiceCollectionExtensions.cs:
services.AddAntDesign();
在该方法内部,ModalService 的生命周期会根据运行平台自动选择:
// components/core/Extensions/ServiceCollectionExtensions.cs
var serviceLifetime = RuntimeInformation.IsOSPlatform(OSPlatform.Create("BROWSER"))
? ServiceLifetime.Singleton : ServiceLifetime.Scoped;
services.TryAdd(new ServiceDescriptor(typeof(ModalService), typeof(ModalService), serviceLifetime));
即:在 WebAssembly 中注册为 Singleton,在 Server 端注册为 Scoped(因为 Server 端服务不能被不同用户共享)。同时,示例代码通过 @inject ModalService ModalService 注入服务实例。此外,为了接收服务端事件,页面中还应包含由 <AntContainer> 提供的 ModalContainer,它会订阅 ModalService 的打开、关闭与更新事件(详见下文"底层机制"一节)。
核心 API:CreateModal 系列方法
ModalService 定义在 ModalServiceForModal.cs,它为"打开弹窗"提供了四个主入口:
| 方法签名 | 说明 |
|---|---|
CreateModal(ModalOptions options) |
创建并打开普通 Modal,返回 ModalRef |
CreateModal<TResult>(ModalOptions options) |
创建可回传 TResult 结果的 Modal,返回 ModalRef<TResult> |
CreateModal<TComponent, TComponentOptions>(ModalOptions options, TComponentOptions componentOptions) |
创建并打开一个模板组件,约束 TComponent : FeedbackComponent<TComponentOptions>,将 componentOptions 作为 Options 传入模板 |
CreateModal<TComponent, TComponentOptions, TResult>(ModalOptions options, TComponentOptions componentOptions) |
创建带返回值的模板组件弹窗,约束 TComponent : FeedbackComponent<TComponentOptions, TResult>,返回 ModalRef<TResult> |
模板重载的实现本质,是把你传入的组件类型用 RenderTreeBuilder 动态挂载到弹窗的 Content 上,并自动注入两个关键参数(源码):
ModalRef modalRef = new ModalRef(options, this);
void Child(RenderTreeBuilder builder)
{
builder.OpenComponent<TComponent>(0);
builder.AddAttribute(1, "FeedbackRef", modalRef);
builder.AddAttribute(2, "Options", componentOptions);
builder.CloseComponent();
}
options.Content = Child;
options.ModalRef = modalRef;
options.CreateByService = true;
return CreateOrOpenModal(modalRef);
可以看到服务做了三件事:把 ModalRef 作为 FeedbackRef 参数传给模板;把调用方构造的 componentOptions 作为 Options 参数传入;最后调用 CreateOrOpenModal 将 options.Visible 置为 true 并触发 OnModalOpenEvent。
模板组件基类:FeedbackComponent
要让组件能够被 ModalService 装载,模板必须继承 FeedbackComponent。该基类位于 FeedbackComponent.cs,继承自 TemplateComponentBase<TComponentOptions>(见 TemplateComponentBase.cs),因此天然拥有两个关键成员:
Options(TComponentOptions类型参数):由CreateModal<TComponent, TComponentOptions>的第二个参数注入,是外部向模板传值的主要通道;FeedbackRef(IFeedbackRef类型参数):由服务自动注入的ModalRef,模板内可据此主动关闭弹窗、触发 Ok/Cancel 回调。
FeedbackComponent<TComponentOptions> 还提供了便捷方法:
public async Task CloseFeedbackAsync()
{
await (FeedbackRef?.CloseAsync() ?? Task.CompletedTask);
}
即模板内部可直接调用 CloseFeedbackAsync() 关闭自身所在弹窗。
对于带返回值的模板,继承 FeedbackComponent<TComponentOptions, TResult>,并通过 OkCancelRefWithResult 属性(IOkCancelRef<TResult>)向外部回传结果。此外,基类提供 OnFeedbackOkAsync(ModalClosingEventArgs args) 与 OnFeedbackCancelAsync(ModalClosingEventArgs args) 两个虚方法,模板可重写它们实现"校验不通过则阻止关闭"等逻辑(设置 args.Cancel = true),旧版 OkAsync/CancelAsync 方法已标记过时,新代码应改用上述两个方法。
实战一:模板组件写一个表单弹窗(对应官方示例)
官方示例的模板组件 ModalTemplateDemo.razor 是一个标准的 FeedbackComponent 表单:
@inherits FeedbackComponent<Form.demo.Basic.Model>
<Form Model="@_model"
LabelCol="new ColLayoutParam { Span = 8 }"
WrapperCol="new ColLayoutParam { Span = 16 }"
OnFinish="OnFinish"
OnFinishFailed="OnFinishFailed">
<FormItem Label="Username">
<Input @bind-Value="@context.Username" />
</FormItem>
<FormItem Label="Password">
<InputPassword @bind-Value="@context.Password" />
</FormItem>
<FormItem WrapperCol="new ColLayoutParam{ Offset = 8, Span = 16 }">
<Checkbox @bind-Value="context.RememberMe">Remember me</Checkbox>
</FormItem>
<FormItem WrapperCol="new ColLayoutParam{ Offset = 8, Span = 16 }">
<Button Type="ButtonType.Primary" HtmlType="submit">
Submit
</Button>
</FormItem>
</Form>
<br />
<br />
@code{
private Form.demo.Basic.Model _model;
protected override void OnInitialized()
{
_model = base.Options ?? new Form.demo.Basic.Model();
base.OnInitialized();
}
private void OnFinish(EditContext editContext)
{
Console.WriteLine($"Success:{JsonSerializer.Serialize(_model)}");
_ = base.FeedbackRef.CloseAsync();
}
private void OnFinishFailed(EditContext editContext)
{
Console.WriteLine($"Failed:{JsonSerializer.Serialize(_model)}");
}
}
这段代码体现了模板组件三个典型技巧:
@inherits FeedbackComponent<Form.demo.Basic.Model>:把表单模型类型Form.demo.Basic.Model作为组件选项类型;base.Options初始化数据:OnInitialized中优先采用外部传入的Options(即调用方构造的Model),为空时才 new 新实例,实现"打开弹窗时预填数据";base.FeedbackRef.CloseAsync()主动关窗:表单校验通过后由模板自行关闭弹窗,无需外部干预。Form组件内部通过@context(即绑定模型实例)与表单字段完成双向绑定。
实战二:在事件处理器中通过服务打开弹窗
调用方页面 Modal_service_for_modal.razor 演示了如何组装 ModalOptions 并打开模板:
@inject ModalService ModalService
<Input @bind-Value="@value" Placeholder="user name" />
<br />
<br />
<Button OnClick="OpenTemplate" Type="ButtonType.Primary">Use Template</Button>
<br />
<br />
<Button OnClick="OpenTemplateWithResult" Type="ButtonType.Primary">Use Template With Result</Button>
@code{
private string value = "blazor";
private ModalRef _modalRef;
private async Task OpenTemplate()
{
var templateOptions = new Form.demo.Basic.Model();
templateOptions.Username = value;
var modalConfig = new ModalOptions();
modalConfig.Title = "Basic Form";
modalConfig.OnCancel = async (e) =>
{
Console.WriteLine("OnCancel");
await _modalRef.CloseAsync();
};
modalConfig.AfterClose = () =>
{
Console.WriteLine("AfterClose");
value = templateOptions.Username;
InvokeAsync(StateHasChanged);
return Task.CompletedTask;
};
_modalRef = await ModalService
.CreateModalAsync<ModalTemplateDemo, Form.demo.Basic.Model>
(modalConfig, templateOptions);
_modalRef.OnOpen = () =>
{
Console.WriteLine("ModalRef OnOpen");
return Task.CompletedTask;
};
_modalRef.OnOk = () =>
{
Console.WriteLine("ModalRef OnOk");
return Task.CompletedTask;
};
_modalRef.OnCancel = () =>
{
Console.WriteLine("ModalRef OnCancel");
return Task.CompletedTask;
};
_modalRef.OnClose = () =>
{
Console.WriteLine("ModalRef OnClose");
return Task.CompletedTask;
};
}
}
要点说明:
- 调用顺序是:先构造
ModalOptions(标题、取消回调、关闭后回调),再以<模板组件类型, 选项类型>调用CreateModalAsync; AfterClose在弹窗关闭动画完成后触发,示例用它把表单里修改过的Username回写回外层页面状态并刷新 UI;- 返回的
_modalRef上可以挂四个回调:OnOpen(打开时)、OnOk(点确定)、OnCancel(点取消/关闭按钮)、OnClose(关闭后),它们均是无参的Func<Task>; - 注意:仓库源码中
CreateModalAsync系列方法已被标记<a href="https://link.gitcode.com/i/c1fb40698c253606d03cd1750e1aaad0" target="_blank">Obsolete("Use the CreateModal instead.")](见 [ModalServiceForModal.cs),官方 demo 仍在使用以兼容旧代码,新项目建议直接使用同步的CreateModal,二者返回的ModalRef语义一致。
ModalRef:弹窗句柄的完整能力
ModalRef 定义在 ModalRef.cs,继承自 FeedbackRefWithOkCancelBase,是服务模式弹窗的控制中枢,核心成员包括:
| 成员 | 说明 |
|---|---|
Config |
保存创建时传入的 ModalOptions,可直接读写(如改标题、改宽度) |
OpenAsync() |
重新打开弹窗,内部先置 Config.Visible = true 再调用服务 |
CloseAsync() |
关闭弹窗,经 ModalService.CloseModalAsync 触发关闭事件 |
UpdateConfigAsync() |
用当前 Config 刷新弹窗 UI,修改配置后调用它生效 |
SetConfirmLoading(bool loading) |
快捷切换确认按钮的 loading 状态 |
OnOpen / OnClose / OnOk / OnCancel |
无参回调委托 |
ModalRef<TResult> |
泛型版本额外提供 Func<TResult, Task> OnOk / OnCancel,以及 OkAsync(result) / CancelAsync(result) 用于从模板向外部回传结果 |
在 Ok/Cancel 按钮被点击时,基类 FeedbackRefBase.cs 的默认行为是:先 CloseAsync() 关闭弹窗,再依次触发对应回调,顺序可参照 OkAsync 实现:
public async Task OkAsync(ModalClosingEventArgs e)
{
await CloseAsync();
if (OnOk != null)
{
await OnOk();
}
}
实战三:带返回值的模板(Template With Result)
示例页面的第二个按钮演示了 ModalRef<TResult> 的用法。模板组件使用 ConfirmTemplateDemo.razor,继承 FeedbackComponent<string, string>(选项类型与返回类型均为 string):
@inherits FeedbackComponent<string, string>
<div>
<Text>Please input "@config"</Text>
value: <Input @bind-Value="value" Placeholder="@config" />
</div>
@code{
string config;
string value;
protected override void OnInitialized()
{
config = this.Options;
base.OnInitialized();
}
public override async Task OnFeedbackOkAsync(ModalClosingEventArgs args)
{
if (FeedbackRef is ConfirmRef confirmRef)
{
confirmRef.Config.OkButtonProps.Loading = true;
await confirmRef.UpdateConfigAsync();
}
else if (FeedbackRef is ModalRef modalRef)
{
modalRef.Config.ConfirmLoading = true;
await modalRef.UpdateConfigAsync();
}
await Task.Delay(1000);
// only the input's value equals the initialized value, the OK button will close the confirm dialog box
if (value != config)
args.Cancel = true;
else
await base.OkCancelRefWithResult!.OnOk(value);
await base.OnFeedbackOkAsync(args);
}
}
调用方则使用三泛型重载:
private async Task OpenTemplateWithResult()
{
var modalConfig = new ModalOptions();
modalConfig.Title = "TemplateWithResult";
modalConfig.Style = "top:20px;";
// In order for Dispose in ConfirmTemplateDemo to take effect every time it is closed
modalConfig.DestroyOnClose = true;
var modalRef = await ModalService.CreateModalAsync<ConfirmTemplateDemo, string, string>(modalConfig, value);
modalRef.OnOk = (result) =>
{
Console.WriteLine($"OnOk:{result}");
return Task.CompletedTask;
};
modalRef.OnCancel = (result) =>
{
Console.WriteLine($"OnCancel:{result}");
return Task.CompletedTask;
};
}
这里值得注意的模式:
OnFeedbackOkAsync中拦截校验:当输入值与初始值不一致时设置args.Cancel = true,弹窗不会关闭;一致时通过OkCancelRefWithResult!.OnOk(value)把输入值回传给调用方,外部modalRef.OnOk = (result) => ...即可拿到该值;DestroyOnClose = true:只有设置该项,模板组件的Dispose才会在每次关闭时被调用(源码注释对此有明确说明),适合需要每次打开都重建组件状态的场景;Style = "top:20px;":直接以内联样式控制弹窗位置。
ModalOptions 关键配置速查
ModalOptions 定义在 ModalOptions.cs,继承 DialogOptionsBase(见 DialogOptionsBase.cs)。常用配置项如下:
| 配置项 | 默认值 | 说明 |
|---|---|---|
Title / TitleTemplate |
null | 弹窗标题(字符串或 RenderFragment) |
Width |
520 | 弹窗宽度,支持数字或带单位字符串 |
OnOk / OnCancel |
默认关闭弹窗 | 点击确定/取消或右上角关闭时的回调;默认行为见 ModalOptions.DefaultOnCancelOrOk,即调用 ModalRef.CloseAsync() |
AfterClose |
空委托 | 关闭动画结束后触发 |
Mask |
true | 是否显示遮罩 |
MaskClosable |
true | 点击遮罩是否关闭 |
Keyboard |
true | 是否支持 Esc 关闭 |
Closable |
true | 是否显示右上角关闭按钮 |
Centered |
false | 是否垂直居中 |
ConfirmLoading |
false | 确定按钮 loading 状态 |
DestroyOnClose |
false | 关闭后是否将弹窗从 DOM 中移除 |
Footer |
默认底部按钮区 | 自定义底部;设为 null 则无底部 |
Content |
null | 弹窗内容 RenderFragment(服务创建模板时自动填充) |
Style / BodyStyle |
null | 弹窗容器 / 内容区样式 |
Draggable / DragInViewport |
false / true | 是否可拖动、是否限制在视口内拖动 |
Maximizable / DefaultMaximized |
false / false | 是否显示最大化按钮 / 初始化即最大化 |
Resizable |
false | 是否可调整大小 |
ZIndex |
1000 | z-index |
OkText / CancelText |
由当前 Locale 决定 | 确定/取消按钮文字 |
Locale |
LocaleProvider.CurrentLocale.Modal |
按钮文案等本地化 |
构造函数中 ModalOptions 会预置 Width = 520、MaskClosable = true,并从 LocaleProvider.CurrentLocale.Modal 读取确定/取消按钮文案(源码)。
底层机制:从服务调用到弹窗渲染
命令式弹窗之所以"零声明"也能工作,靠的是 ModalContainer 与 ModalService 的事件协作(见 ModalContainer.razor.cs):
ModalContainer在初始化时订阅ModalService的OnModalOpenEvent/OnModalCloseEvent/OnModalUpdateEvent三个内部事件;CreateOrOpenModal设置Config.Visible = true后触发OnModalOpenEvent,容器把ModalRef加入渲染列表并StateHasChanged;- 关闭时
CloseModalAsync触发OnModalCloseEvent,容器先隐藏弹窗、延迟 250ms 等待关闭动画,若DestroyOnClose为 true 则把ModalRef从列表移除; - 调用
UpdateConfigAsync/SetConfirmLoading则触发OnModalUpdateEvent,容器直接刷新整个弹窗 UI。
另外,容器还会订阅 NavigationManager.LocationChanged,路由切换时清空弹窗列表,避免跨页残留。这也解释了为什么使用服务式弹窗的页面需要有一个宿主容器(AntContainer)——它是事件到渲染的"中转站"。
最佳实践小结
- 新代码优先用
CreateModal:CreateModalAsync已被标记 Obsolete,语义相同但更推荐同步版本; - 模板内关闭用
FeedbackRef.CloseAsync()或CloseFeedbackAsync():不要依赖外部变量,模板组件应通过注入的FeedbackRef自管理生命周期; - 需要每次重建组件状态时设置
DestroyOnClose = true,否则关闭只做Visible=false的隐藏处理; - 回传结果用
FeedbackComponent<T, TResult>+OkCancelRefWithResult.OnOk(value),配合OnFeedbackOkAsync中的args.Cancel实现"校验不过不允许关闭"; - 通过
AfterClose做关闭后的数据回写(如把表单改动同步回页面),并记得调用InvokeAsync(StateHasChanged)刷新外部 UI; - 灵活使用
ModalRef.Config+UpdateConfigAsync():在运行时修改标题、宽度、ConfirmLoading等配置均通过这条路径生效。
通过 ModalService + FeedbackComponent 的组合,ant-design-blazor 让"以代码驱动弹窗、以组件复用表单"成为可能,尤其适合登录框、数据编辑、确认流程等高频场景。更多完整示例可继续阅读仓库中的 confirm_service.md(Confirm 服务)以及 form-in-modal.md(表单内嵌弹窗),并结合 index.zh-CN.md 查阅 Modal 组件的完整 API。