ant-design-blazor Notification 通知提醒框完全指南:服务 API、全局配置与编程式控制
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)调用,可作为自行编写服务调用测试的模板。
进一步阅读建议:
- 服务与接口:INotificationService.cs、NotificationService.cs
- 配置模型:NotificationConfig.cs、NotificationGlobalConfig.cs
- 渲染与生命周期:Notification.razor、Notification.razor.cs、NotificationItem.razor、NotificationRef.cs
- 类型定义:NotificationPlacement.cs、NotificationType.cs
- 挂载容器与服务注册:AntContainer.razor、ServiceCollectionExtensions.cs
- 样式与动画:style/placement.less、style/rtl.less
- 演示与文档:Demo 目录、英文文档
结语
Notification 是 ant-design-blazor 全局反馈体系(与 Message、Modal、Drawer 等并列于 AntContainer)中承载复杂通知的主力组件。掌握 Open 系列快捷方法、NotificationConfig 与 NotificationGlobalConfig 的双层配置模型、NotificationRef 的编程式控制,以及 Key 去重与自动关闭机制,即可在业务系统中稳定实现系统推送、操作确认、异常上报等各类通知场景。