syncfusion-blazor-notifications

实现 Syncfusion Blazor Notifications

全面介绍如何实现 Syncfusion Blazor Notifications 中的 Toast、Message 和 Skeleton 组件。这些组件提供必不可少的用户反馈机制，包括临时通知、内联消息和内容加载状态。

组件概览

SfToast

轻量、非阻塞的通知弹窗，会临时显示以提供反馈。支持位置设置、动画、操作按钮和模板。

主要功能：

• 可配置的位置（左上、顶部居中、右上、左下、底部居中、右下）
• 可自定义时间的显示/隐藏动画
• 带超时设置和进度条的自动关闭
• 供用户交互的操作按钮
• 支持自定义内容模板
• 事件回调（OnOpen、OnClose、OnClick）
• 多条 Toast 堆叠（最新的显示在顶部/底部）

SfMessage

内联警告组件，用于显示不同严重级别的上下文反馈消息。

主要功能：

• 严重级别（Normal、Info、Success、Warning、Error），并采用颜色区分样式
• 多种变体（Text、Outlined、Filled），呈现不同视觉样式
• 与严重级别匹配的内置图标
• 可选的关闭按钮，用于关闭消息
• 内容对齐方式（左、中、右）
• 可见性控制和关闭事件处理
• 支持自定义 CSS 样式

SfSkeleton

加载占位组件，可显示动画形状以表示内容正在加载。

主要功能：

• 多种形状（Circle、Square、Rectangle、Text），适用于不同类型的内容
• 多种闪烁效果（Pulse、Wave、Fade、None），提供视觉反馈
• 可配置的尺寸（宽度、高度）
• 适用于屏幕阅读器的无障碍标签
• 可见性切换，用于显示/隐藏
• 支持通过 CSS 自定义样式

快速入门

Toast - 基本示例

@page "/toast-demo"
@using Syncfusion.Blazor.Notifications
@using Syncfusion.Blazor.Buttons

<SfButton @onclick="ShowToast">Show Toast</SfButton>

<SfToast @ref="ToastObj" Title="Notification" Content="Your changes have been saved successfully!" />

@code {
    SfToast ToastObj;

    private async Task ShowToast()
    {
        await ToastObj.ShowAsync();
    }
}

Message - 基本示例

@page "/message-demo"
@using Syncfusion.Blazor.Notifications

<SfMessage Severity="MessageSeverity.Success" ShowIcon="true" ShowCloseIcon="true">
    Your profile has been updated successfully!
</SfMessage>

<SfMessage Severity="MessageSeverity.Warning" ShowIcon="true">
    Your session will expire in 5 minutes.
</SfMessage>

<SfMessage Severity="MessageSeverity.Error" ShowIcon="true" ShowCloseIcon="true">
    Failed to save changes. Please try again.
</SfMessage>

Skeleton - 基本示例

@page "/skeleton-demo"
@using Syncfusion.Blazor.Notifications

<div class="skeleton-container">
    <SfSkeleton Shape="SkeletonType.Circle" Width="60px" Height="60px" />
    <div class="skeleton-text">
        <SfSkeleton Shape="SkeletonType.Text" Width="80%" />
        <SfSkeleton Shape="SkeletonType.Text" Width="60%" />
    </div>
</div>

<style>
    .skeleton-container {
        display: flex;
        gap: 16px;
        padding: 16px;
    }
    .skeleton-text {
        flex: 1;
        display: flex;
        flex-direction: column;
        gap: 8px;
    }
</style>

文档和导航指南

Toast 组件

开始使用 Toast

📄 阅读： references/toast-getting-started.md

• 安装和 NuGet 包设置
• 在 Program.cs 中注册服务
• 基本 Toast 实现
• 以编程方式显示和隐藏 Toast
• 位置配置基础知识
• 简单的成功/错误通知

Toast 高级功能

📄 阅读： references/toast-features.md

• 位置和对齐选项（9 种预定义位置）
• 动画设置（带效果和持续时间的显示/隐藏动画）
• 设置超时和延长超时的自动关闭
• 进度条显示和方向
• 带事件处理程序的操作按钮
• 标题和内容模板
• 多条 Toast 的管理和堆叠顺序
• 事件回调（OnOpen、OnClose、OnClick、BeforeOpen、BeforeClose）
• RTL（从右到左）支持
• 自定义宽度、高度和 CSS 样式
• 指定目标容器

Message 组件

Message 实现

📄 阅读： references/message-implementation.md

• 开始使用 Message 组件
• 严重级别（Normal、Info、Success、Warning、Error）
• 变体样式（Text、Outlined、Filled）
• 图标配置（内置和自定义）
• 关闭图标和关闭处理
• 内容对齐选项
• 可见性控制和双向绑定
• 关闭事件处理
• 使用 ChildContent 自定义内容
• CSS 类自定义
• 无障碍功能
• 与表单和验证集成

Skeleton 组件

Skeleton 实现

📄 阅读： references/skeleton-implementation.md

• 从 Skeleton 组件入手
• Skeleton 形状（Circle、Square、Rectangle、Text）
• 闪烁效果（Pulse、Wave、Fade、None）
• 宽度和高度配置
• 加载状态下的可见性切换
• 供屏幕阅读器使用的无障碍标签
• 多种 Skeleton 布局（列表、卡片、表格）
• 常见加载模式（个人资料、文章、网格）
• CSS 自定义和主题设置
• 性能注意事项

样式和主题

为所有通知组件设置样式

📄 阅读： references/styling-and-themes.md

• 主题集成（Bootstrap、Material、Fluent、Tailwind）
• Toast 的自定义 CSS 类
• Message 的自定义 CSS 类
• Skeleton 的自定义 CSS 类
• 所有组件均支持深色模式
• 响应式设计模式
• 颜色自定义
• 动画自定义
• 针对特定组件的样式设置技巧

使用场景和示例

真实场景实现示例

📄 阅读： references/use-cases-and-examples.md

• 表单提交反馈（Toast + Message）
• 电商购物车通知
• 仪表板数据更新
• 文件上传进度和反馈
• 用户身份验证反馈
• 使用 Skeleton 占位符加载数据
• 错误处理和恢复
• 多步骤流程反馈
• 通知中心／历史记录
• 有效组合使用这三个组件

常见模式

模式 1：使用 Toast 提供成功／错误反馈

@code {
    SfToast ToastObj;

    private async Task SaveData()
    {
        try
        {
            await DataService.SaveAsync();
            ToastObj.Title = "Success";
            ToastObj.Content = "Data saved successfully!";
            await ToastObj.ShowAsync();
        }
        catch (Exception ex)
        {
            ToastObj.Title = "Error";
            ToastObj.Content = $"Failed to save: {ex.Message}";
            await ToastObj.ShowAsync();
        }
    }
}

模式 2：使用 Message 进行表单验证

<EditForm Model="@model" OnValidSubmit="HandleValidSubmit">
    <DataAnnotationsValidator />
    
    @if (!string.IsNullOrEmpty(errorMessage))
    {
        <SfMessage Severity="MessageSeverity.Error" 
                   ShowIcon="true" 
                   ShowCloseIcon="true"
                   Closed="@(() => errorMessage = null)">
            @errorMessage
        </SfMessage>
    }
    
    
</EditForm>

模式 3：使用 Skeleton 显示加载状态

@if (isLoading)
{
    <div class="product-card-skeleton">
        <SfSkeleton Shape="SkeletonType.Rectangle" Width="100%" Height="200px" />
        <SfSkeleton Shape="SkeletonType.Text" Width="80%" />
        <SfSkeleton Shape="SkeletonType.Text" Width="60%" />
    </div>
}
else
{
    <div class="product-card">
        <img src="@product.ImageUrl" alt="@product.Name" />
        <h3>@product.Name</h3>
        <p>@product.Description</p>
    </div>
}

模式 4：多种 Toast 类型

<SfToast @ref="SuccessToast" 
         Title="Success" 
         Icon="e-success" 
         CssClass="e-toast-success"
         <ToastPosition X="Right" Y="Top"></ToastPositio

<SfToast @ref="ErrorToast" 
         Title="Error" 
         Icon="e-error" 
         CssClass="e-toast-danger"
         <ToastPosition X="Right" Y="Top"></ToastPosition>

<SfToast @ref="WarningToast" 
         Title="Warning" 
         Icon="e-warning" 
         CssClass="e-toast-warning"
         <ToastPosition X="Right" Y="Top"></ToastPosition>

@code {
    SfToast SuccessToast, ErrorToast, WarningToast;

    private async Task ShowSuccess(string message)
    {
        SuccessToast.Content = message;
        await SuccessToast.ShowAsync();
    }

    private async Task ShowError(string message)
    {
        ErrorToast.Content = message;
        await ErrorToast.ShowAsync();
    }

    private async Task ShowWarning(string message)
    {
        WarningToast.Content = message;
        await WarningToast.ShowAsync();
    }
}

安装

NuGet 包

dotnet add package Syncfusion.Blazor.Notifications
dotnet add package Syncfusion.Blazor.Themes

服务注册

Program.cs：

using Syncfusion.Blazor;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSyncfusionBlazor();

命名空间导入

_Imports.razor：

@using Syncfusion.Blazor.Notifications

主题引用

App.razor 或布局文件：

<link href="_content/Syncfusion.Blazor.Themes/bootstrap5.css" rel="stylesheet" />
<script src="_content/Syncfusion.Blazor.Core/scripts/syncfusion-blazor.min.js"></script>

关键属性参考

Toast 属性

属性	类型	描述
Content	string	Toast 消息内容
Title	string	Toast 标题文本
Icon	string	图标 CSS 类
Position	ToastPosition	X 和 Y 位置（Top、Bottom、Left、Right、Center）
Timeout	int	自动隐藏时长（毫秒，默认值：5000）
ShowCloseButton	bool	显示关闭按钮（默认值：false）
ShowProgressBar	bool	显示进度条（默认值：false）
NewestOnTop	bool	将最新的 Toast 显示在最上方（默认值：true）
CssClass	string	自定义 CSS 类

Message 属性

属性	类型	描述
Severity	MessageSeverity	Normal、Info、Success、Warning、Error
Variant	MessageVariant	Text、Outlined、Filled
ShowIcon	bool	显示严重性图标（默认值：true）
ShowCloseIcon	bool	显示关闭按钮（默认值：false）
Visible	bool	控制可见性
ContentAlignment	HorizontalAlign	左对齐、居中、右对齐
CssClass	string	自定义 CSS 类

Skeleton 属性

属性	类型	描述
Shape	SkeletonType	Circle、Square、Rectangle、Text
Effect	ShimmerEffect	Pulse、Wave、Fade、None
Width	string	宽度，单位可为 px、% 或其他 CSS 单位
Height	string	高度，单位可为 px、% 或其他 CSS 单位
Visible	bool	控制可见性
Label	string	无障碍标签
CssClass	string	自定义 CSS 类

常见用例

1. 表单提交反馈 - 表单提交后显示成功／错误提示
2. 验证消息 - 显示验证错误的内联消息
3. 加载状态 - 获取数据时使用骨架屏
4. 购物车操作 - 添加到购物车或从购物车移除时显示提示通知
5. 文件上传 - 提供进度反馈和完成通知
6. API 错误 - 显示错误消息并提供重试选项
7. 会话警告 - 会话过期前显示警告消息
8. 数据刷新 - 刷新期间显示骨架占位符
9. 多步表单 - 在每个步骤提供进度反馈
10. 实时更新 - 实时数据变更时显示提示通知

故障排查

提示未显示

• 确保调用 ShowAsync() 以显示提示
• 确认提示组件包含内容或模板
• 检查提示超时时间是否过短
• 确认 ToastPosition 位于视口范围内

消息不可见

• 检查 Visible 属性是否设为 true
• 确认 ChildContent 或 Content 属性中包含消息内容
• 确保组件已渲染到 DOM 中（未被父级隐藏）
• 检查 CSS z-index 冲突

骨架屏未产生动画

• 确认已设置 Effect 属性（Pulse、Wave 或 Fade）
• 检查主题是否已加载闪烁效果 CSS
• 确保已为骨架屏定义宽度和高度
• 确认 Visible 已设为 true

主题未应用

• 确认主题 CSS 已在 App.razor 或布局中引用
• 检查是否已安装 Syncfusion.Blazor.Themes 包
• 确保 CSS 链接位于组件使用之前
• 尝试清除浏览器缓存

服务未注册

• 在 Program.cs 中添加 builder.Services.AddSyncfusionBlazor()
• 确认已安装 Syncfusion.Blazor.Core 包
• 确保存在 using 语句
• 添加服务后重新构建项目

最佳实践

1. 使用合适的通知类型 - 临时通知使用 Toast，持久通知使用 Message
2. 限制提示时长 - 大多数消息显示 3-7 秒，错误消息可适当延长
3. 提供明确的操作 - 在适当情况下添加重试／关闭按钮
4. 使骨架屏与内容相似 - 让骨架屏形状与实际内容结构相匹配
5. 无障碍性 - 始终为骨架屏和图标提供标签
6. 保持位置一致 - 在整个应用中使用相同的提示位置
7. 消息严重程度 - 根据消息场景使用正确的严重程度级别
8. 避免过度使用 - 不要向用户显示过多通知
9. 渐进增强 - 使用骨架屏提升感知性能
10. 错误处理 - 始终妥善处理提示／消息显示错误

后续步骤

• 查看 Toast 高级功能，了解动画和模板
• 了解 Message 实现，用于表单验证
• 查看 Skeleton 模式，了解加载状态
• 查看 样式指南，了解自定义方法
• 查看 真实场景示例，了解完整场景