ant-design-blazor Notification 通知提醒框完全指南:服务 API、全局配置与编程式控制

原创2026-10-11 12:08:491,829 阅读
文章标签:前端UI组件设计系统WebAssembly

ant-design-blazor Notification 通知提醒框完全指南:服务 API、全局配置与编程式控制

导读

Notification 是 ant-design-blazor 提供的全局通知提醒组件,用于在浏览器视口的四个角(乃至顶部/底部居中位置)展示结构复杂、可交互、由系统主动推送的提示信息。本文以 Notification 官方文档 为主线,结合 NotificationService.cs、NotificationConfig.cs 等核心源码与仓库内 示例 Demo,完整讲解其服务端 API、参数配置、全局默认值、NotificationRef 编程式控制以及自动关闭的实现原理,帮助你快速在 Blazor 应用中落地一套健壮的全局通知方案。

何时使用 Notification

与轻量的 Message 不同,Notification 面向需要承载更多信息与操作的通知场景,官方文档明确列出三类典型使用场景:

  • 较为复杂的通知内容:标题 + 长文本描述,甚至自定义 RenderFragment 富内容;
  • 带有交互的通知:通过 Btn 自定义按钮,向用户提供下一步行动点;
  • 系统主动推送:与用户操作无关的被动信息,如任务完成、版本发布、异常上报等。

Notification 在视口的四个角弹出(默认右上角),通过 INotificationService 以“服务调用”方式触发,不依赖页面内手动摆放组件实例。

使用前置条件:AntContainer 与服务注册

1. 在 App.Razor 中添加 AntContainer

文档中特别强调:请确认已经在 App.Razor 中添加了 <AntContainer /> 组件。如果通知不显示,这通常就是原因。

AntContainer.razor 是所有全局反馈类组件的挂载容器,其内部渲染了:

<Notification />
<Message />
<ComfirmContainer />
<DrawerContainer />
<ModalContainer />
<ImagePreviewContainer />

因此它必须出现在组件树的最外层(如 MainLayout 或 App 中),通知框才会被渲染出来。

2. 注册服务

在 Program.cs 中调用 builder.Services.AddAntDesign()。从 ServiceCollectionExtensions.cs 可以看到:

  • NotificationService 被注册为服务(Server 端为 Scoped,Wasm 端为 Singleton);
  • 同时注册了 INotificationService 接口,并通过 GetRequiredService<NotificationService>() 解析到同一实例;
  • 因此你在组件中既可 @inject NotificationService,也可 @inject INotificationService,二者指向同一个服务对象。

快速开始:打开第一条通知

最简用法只需 Message(标题)和 Description(内容)两个必选字段,4.5 秒后自动关闭。参考 Basic.razor:

@inject INotificationService _notice

<Button Type="ButtonType.Primary" OnClick="OnClick">
    Open the notification box
</Button>

@code{
    private async Task OnClick()
    {
        await _notice.Open(new NotificationConfig()
        {
            Message = "title",
            Description = "This is the content of the notification. This is the content of the notification. This is the content of the notification."
        });
    }
}

调用 Open 后,服务内部会先 CreateRefAsync 创建 NotificationRef,再通过 OpenAsync() 触发渲染(见 NotificationService.cs),最终返回 NotificationRef 供后续编程式控制。

INotificationService API 全览

INotificationService.cs 定义了如下方法,均为文档 API 列表的源码实现:

方法 说明
Open(config: NotificationConfig) 打开一个通知框(返回 NotificationRef)
Info(config) 以 Info 样式打开
Success(config) 以 Success 样式打开
Warning(config) 以 Warning 样式打开
Warn(config) 与 Warning 等价
Error(config) 以 Error 样式打开
Close(key: string) 按 Key 关闭指定通知
Destroy() 销毁全部通知
CreateRefAsync() 仅创建 NotificationRef,不立即打开
UpdateAsync(key, description, message?) 更新已存在通知的 Description 与 Message

从源码看,Info/Success/Warning/Error 等快捷方法实际是设置 config.NotificationType 后转发给 Open(见 NotificationService.cs),从而决定左侧图标类型。

NotificationConfig 参数详解

config 参数对应 NotificationConfig.cs,下表完整覆盖官方文档并补充了源码层面的取值细节:

参数 说明 类型 默认值
Btn 自定义关闭按钮(如“确认”操作按钮) RenderFragment null
ClassName 自定义 CSS class,叠加在通知项上 string null
CloseIcon 自定义关闭图标 RenderFragment null(取全局默认关闭图标)
Description 通知提醒内容,必选 string | RenderFragment -
Duration 自动关闭延时(秒);null 或 0 则不自动关闭 double? 4.5
Icon 自定义左侧图标 RenderFragment null
Key 通知唯一标志,用于关闭/更新 string Guid.NewGuid().ToString()
Message 通知提醒标题,必选 string | RenderFragment -
OnClose 通知关闭时触发的事件 event Action null
OnClick 点击通知时触发的事件 event Action null
Placement 弹出位置 NotificationPlacement? NotificationPlacement.TopRight
Style 自定义内联样式 string null

几点源码层面的补充:

  • Message 与 Description 使用 OneOf<string, RenderFragment>,在 NotificationItem.razor 中按 IsT0(string)与 AsT1(RenderFragment)分支渲染;string 会被作为 MarkupString 输出,注意避免直接拼接未经处理的用户输入;
  • Duration 在 NotificationConfig 中的源码默认值是 null,真正生效的 4.5 秒来自全局配置的默认值 _defaultDuration,由 ExtendConfig 在打开时填充(见 Notification.razor.cs);
  • Key 源码默认为 null,服务在 InternalOpen 中检测到空 Key 时会自动生成 Guid.NewGuid().ToString(),与文档表格中的默认值语义一致;
  • OnClose/OnClick 为 C# 事件(event Action),内部通过 InvokeOnClose()/InvokeOnClick() 调用,点击回调在 NotificationItem.razor.cs 中触发。

通知类型与快捷方法

通过 NotificationType.cs 枚举(None、Info、Success、Warning、Error)控制左侧图标。两种等效写法:

// 写法一:Open + NotificationType
await _notice.Open(new NotificationConfig()
{
    Message = "Notification Title",
    Description = "This is the content of the notification.",
    NotificationType = NotificationType.Success
});

// 写法二:快捷方法
await _notice.Success(new NotificationConfig()
{
    Message = "Notification Title",
    Description = "This is the content of the notification."
});

在 NotificationItem.razor 中,四种类型分别渲染 check-circle(Success)、exclamation-circle(Warning)、close-circle(Error)、info-circle(Info)图标,并附带 aria-label 以支持无障碍访问。完整示例见 WithIcon.razor。

全局配置 NotificationGlobalConfig

对于全站统一的偏移、默认延时、默认位置等,可以在首次调用前通过 INotificationService.Config(config) 一次性配置,之后所有通知默认生效:

_notice.Config(new NotificationGlobalConfig()
{
    Duration = 6,
    Placement = NotificationPlacement.BottomRight,
    Top = 32,
    Bottom = 32,
    Rtl = false,
    CloseIcon = @<Icon Type="@IconType.Outline.Close" />
});

对应 NotificationGlobalConfig.cs 的参数表:

参数 说明 类型 默认值
Bottom 从底部弹出时距底部的距离(像素) double? 24
Top 从顶部弹出时距顶部的距离(像素) double? 24
CloseIcon 自定义关闭图标 RenderFragment -
Duration 默认自动关闭延时(秒) double? 4.5
Placement 弹出位置 NotificationPlacement? NotificationPlacement.TopRight
Rtl 是否开启 RTL 模式 bool false

源码实现位于 Notification.razor.cs:Config(NotificationGlobalConfig) 逐项覆盖组件内部字段(_top、_bottom、_defaultDuration、_defaultPlacement、_defaultCloseIcon、_isRtl),随后 ExtendConfig 在每个通知打开时自动补全未显式设置的 Placement、Duration 与 CloseIcon。也就是说:单条通知显式设置的参数优先,未设置时回落到全局配置。

值得注意:开启 Rtl 后,默认位置会从 TopRight 变为 TopLeft(见 GetDefaultPlacement),CSS 上会追加 ant-notification-rtl 类(相关样式见 style/rtl.less)。

弹出位置 Placement

NotificationPlacement.cs 定义了 6 个位置,除文档中四个角外,还支持顶部/底部居中:

TopLeft = 0, TopRight = 1, BottomLeft = 2,
BottomRight = 3, Top = 4, Bottom = 5

每个位置对应的内联样式由 GetStyle 计算,例如 TopRight 为 right: 0px; top:{_top}px; bottom: auto;,Top 为 inset: {_top}px auto auto 50%; transform: translateX(-50%);——所以全局配置中的 Top/Bottom 只影响相应方向的弹出偏移量。

Placement.razor 展示了全部六个位置的用法,其中也使用了 NotificationPlacement.Top 与 NotificationPlacement.Bottom 这两个居中位置。对应位置的入场动画定义在 style/placement.less(NotificationTopFadeIn、NotificationBottomFadeIn、NotificationLeftFadeIn 等)。

自定义图标与自定义按钮

自定义左侧图标

将 Icon 设置为任意 RenderFragment,即可替换默认类型图标,参考 CustomIcon.razor:

@code{
    private async Task OnClick()
    {
        RenderFragment customIcon = @<Icon Type="@IconType.Outline.Smile" Style="color:#108ee9;" />;
        await _notice.Open(new NotificationConfig()
        {
            Message = "Notification Title",
            Description = "This is the content of the notification.",
            Icon = customIcon
        });
    }
}

设置 Icon 或 NotificationType 时,通知项会追加 ant-notification-notice-with-icon 类(见 NotificationItem.razor.cs)。

自定义操作按钮

Btn 允许在通知底部插入交互按钮。注意:当通知默认 4.5 秒后自动关闭时,按钮可能来不及点击,因此通常配合自定义 Key 并设置 Duration = 0(不自动关闭),在按钮回调中手动关闭,参考 WithBtn.razor:

@code{
    private async Task OnClick()
    {
        string key = $"open{DateTime.Now}";
        RenderFragment btn = @<Button Type="ButtonType.Primary" OnClick="() => { _notice.Close(key); }">
                                confirm
                            </Button>;
        await _notice.Open(new NotificationConfig()
        {
            Message = "Notification Title",
            Key = key,
            Description = "A function will be be called after the notification is closed.",
            Btn = btn
        });
    }
}

通过 Key 更新已打开的通知

UpdateAsync 与“同名 Key 复用”是更新通知的两种途径。

服务级更新:UpdateAsync

await _notice.UpdateAsync(key, "new description");
await _notice.UpdateAsync(key, "new description", "new message");

源码中 Notification.razor.cs 的 OnUpdating 会根据 Key 在 _configKeyDict 中找到旧配置,覆盖 Description(可选覆盖 Message)后触发 StateHasChanged 刷新界面。

同名 Key 打开即更新

Update.razor 展示了另一种技巧:对已存在的 Key 再次调用 Open,不会产生第二条通知,而是更新已有通知的内容。这源于 NotifyAsync 的去重逻辑:_configKeyDict 中命中相同 Key 时,直接改写 Message 和 Description 并返回。

NotificationRef:编程式控制

CreateRefAsync 可先创建引用、稍后再打开,适合需要“预配置 + 延迟打开 + 运行时更新”的场景。文档给出的 NotificationRef 成员如下:

属性

名称 说明
Config 只读 NotificationConfig 对象

方法

方法 说明
OpenAsync() 打开一个通知框
UpdateConfigAsync() 修改 Config 属性后,更新通知框
UpdateConfigAsync(OneOf<string, RenderFragment>) 仅更新通知框的 Description
UpdateConfigAsync(OneOf<string, RenderFragment>, OneOf<string, RenderFragment>) 同时更新 Message 与 Description
CloseAsync() 关闭通知框

完整生命周期示例(来自 NotificationRef.razor):

var config = new NotificationConfig()
{
    Duration = 0,   // 关闭自动移除,便于手动控制
    Message = "title",
    Description = "This is the content of the notification."
};

var notificationRef = await _notice.CreateRefAsync(config);

// 仅在 NotificationRef.OpenAsync() 时触发
notificationRef.OnOpen = () =>
{
    Console.WriteLine("notificationRef.OnOpen");
    return Task.CompletedTask;
};

// 仅在 NotificationRef.CloseAsync() 时触发
notificationRef.OnClose = () =>
{
    Console.WriteLine("notificationRef.OnClose");
    return Task.CompletedTask;
};

await notificationRef.OpenAsync();          // 打开
await Task.Delay(TimeSpan.FromSeconds(2));

config.Description = "new description";     // 修改 Config 后刷新
await notificationRef.UpdateConfigAsync();
// 等价写法:
// await notificationRef.UpdateConfigAsync("new description");
// await notificationRef.UpdateConfigAsync("new description", "new message");

await Task.Delay(TimeSpan.FromSeconds(2));
await notificationRef.CloseAsync();         // 关闭

注意区分:Config.OnClose(配置上的事件)在通知真正关闭时触发(自动超时或手动关闭都会调用 InvokeOnClose),而 NotificationRef.OnClose 仅在调用 ref.CloseAsync() 时触发(见 NotificationRef.cs)。

自动关闭的机制与鼠标悬停暂停

计时器原理

自动关闭由 Notification.razor.cs 的 Remove 方法 实现:

  • Duration > 0 时,创建 CancellationTokenSource,执行 Task.Delay(TimeSpan.FromSeconds(Duration), cts.Token),到期后调用 RemoveItem 关闭;
  • Duration <= 0 时,不启动计时器,通知常驻直到手动关闭。

设置 Duration = 0 即可实现“永不自动关闭”,参考 Duration.razor。

关闭动画与鼠标交互

RemoveItem 会先把 AnimationClass 从 AnimationType.Enter 切换为 AnimationType.Leave(定义见 AnimationType.cs,即 ant-notification-fade-leave 系列类),延迟约 500ms 等淡出动画结束后再从字典移除并触发 OnClose。同时该分支做了防重入判断,避免点击关闭与自动超时重复移除。

更有趣的细节:通知项绑定了鼠标事件(见 Notification.razor.cs 的 OnMouseEnter/OnMouseLeave):

  • 鼠标悬停:OnMouseEnter 调用 Cts?.Cancel() 取消当前计时器,暂停自动关闭;
  • 鼠标移出:OnMouseLeave 重新按 Duration 启动计时器。

也就是说,用户正在阅读或操作通知时,通知不会被突然关闭,体验上更友好。

结合 ErrorBoundary 做 Blazor 错误处理

.NET 6 起的 ErrorBoundary 可以捕获子组件渲染异常。仓库提供了一个把异常直接上报为 Error 通知的示例 ErrorBoundaryDemo.razor:

@inject INotificationService _notice

<ErrorBoundary @ref="errorBoundary">
    <ChildContent>
        <Button Danger OnClick=@OnClick>
            Click me to throw a error
        </Button>
    </ChildContent>
    <ErrorContent Context="ex">
        @{
           ShowNotification(ex);
        }
    </ErrorContent>
</ErrorBoundary>

@code {
    ErrorBoundary errorBoundary;

    void OnClick() => throw new Exception("An Uncaught Error");

    void ShowNotification(Exception ex)
    {
        _ = _notice.Error(new()
        {
            Message = ex.Message,
            Description = ex.StackTrace
        });

        errorBoundary.Recover();
    }
}

异常发生后,ErrorContent 渲染时调用 _notice.Error 弹出包含堆栈的错误通知,并调用 errorBoundary.Recover() 恢复界面。这是 Notification 在真实项目中典型的“系统主动推送”落地场景。

单元测试与源码索引

仓库为通知组件提供了基于 bUnit 的单元测试 tests/AntDesign.Tests/Notification/NotificationTest.cs,通过 Mock<INotificationService> 验证点击按钮后 Info 被以预期的 NotificationConfig(包含 Key、Message、Description)调用,可作为自行编写服务调用测试的模板。

进一步阅读建议:

结语

Notification 是 ant-design-blazor 全局反馈体系(与 Message、Modal、Drawer 等并列于 AntContainer)中承载复杂通知的主力组件。掌握 Open 系列快捷方法、NotificationConfig 与 NotificationGlobalConfig 的双层配置模型、NotificationRef 的编程式控制,以及 Key 去重与自动关闭机制,即可在业务系统中稳定实现系统推送、操作确认、异常上报等各类通知场景。

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