使用 ModalService 创建 Modal 模板组件对话框:ant-design-blazor 服务式弹窗实战指南

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

使用 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)}");
    }
}

这段代码体现了模板组件三个典型技巧:

  1. @inherits FeedbackComponent<Form.demo.Basic.Model>:把表单模型类型 Form.demo.Basic.Model 作为组件选项类型;
  2. base.Options 初始化数据:OnInitialized 中优先采用外部传入的 Options(即调用方构造的 Model),为空时才 new 新实例,实现"打开弹窗时预填数据";
  3. 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):

  1. ModalContainer 在初始化时订阅 ModalService 的 OnModalOpenEvent / OnModalCloseEvent / OnModalUpdateEvent 三个内部事件;
  2. CreateOrOpenModal 设置 Config.Visible = true 后触发 OnModalOpenEvent,容器把 ModalRef 加入渲染列表并 StateHasChanged;
  3. 关闭时 CloseModalAsync 触发 OnModalCloseEvent,容器先隐藏弹窗、延迟 250ms 等待关闭动画,若 DestroyOnClose 为 true 则把 ModalRef 从列表移除;
  4. 调用 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。

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