syncfusion-wpf-toast-notification

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Toast Notifications in WPF

在WPF中实现提示通知（Toast Notification）

When to Use This Skill

适用场景

Use this skill whenever the user needs to:

Display temporary, non-intrusive notifications in WPF applications
Show status messages (save successful, operation completed, errors)
Implement notification alerts that auto-dismiss after a timeout
Create native Windows OS notifications or custom in-app toasts
Display severity-based messages (Info, Success, Warning, Error)
Add interactive action buttons to notifications (Reply, Undo, OK)
Show transient feedback that doesn't block user workflow
Implement global or window-scoped notifications

当你有以下需求时，可使用本技能：

在WPF应用中显示临时、非侵入式通知
显示状态消息（保存成功、操作完成、错误提示等）
实现超时后自动关闭的通知警报
创建原生Windows系统通知或自定义应用内提示框
显示基于严重级别的消息（信息、成功、警告、错误）
为通知添加交互式操作按钮（回复、撤销、确认）
显示不会阻塞用户工作流的临时反馈
实现全局或窗口级别的通知

Component Overview

组件概述

SfToastNotification is a non-UI control (no XAML required) that displays toast notifications in WPF applications. It supports three display modes:

Default Mode: Native Windows OS notifications (Windows 10+)
Window Mode: In-app notifications constrained to window boundaries
Screen Mode: Global overlay notifications across the screen

Key Characteristics:

Code-only implementation (no XAML markup needed)
Static API for showing/closing toasts
Multiple severity levels with built-in visual styling
Customizable animations, placement, and templates
Interactive action buttons with callbacks
Full template customization support

SfToastNotification 是一款无需XAML的非UI控件，用于在WPF应用中显示提示通知。它支持三种显示模式：

默认模式（Default Mode）：原生Windows系统通知（Windows 10及以上版本）
窗口模式（Window Mode）：受窗口边界限制的应用内通知
屏幕模式（Screen Mode）：覆盖整个屏幕的全局通知

核心特性：

纯代码实现（无需XAML标记）
用于显示/关闭通知的静态API
多种严重级别，内置视觉样式
可自定义动画、位置和模板
带回调的交互式操作按钮
全面的模板自定义支持

Documentation and Navigation Guide

文档导航指南

Getting Started & Core Concepts

快速入门与核心概念

📄 Read: references/getting-started.md

Assembly deployment and NuGet installation
Non-UI control architecture
Basic toast with
```
SfToastNotification.Show()
```
method
Title, Message, and Header properties
Duration configuration and auto-close behavior
Toast lifecycle management (Close, CloseAll)
Action buttons and close button visibility
When to read: User needs basic setup or first-time implementation

📄 阅读： references/getting-started.md

程序集部署与NuGet安装
非UI控件架构
使用
```
SfToastNotification.Show()
```
方法创建基础提示框
标题、消息和头部属性
持续时间配置与自动关闭行为
通知生命周期管理（Close、CloseAll）
操作按钮与关闭按钮可见性
适用场景：首次实现通知功能或需要基础配置时

Display Modes

显示模式

📄 Read: references/display-modes.md

Default Mode (Native OS notifications) with WindowsToastBootstrapper setup
Window Mode (window-constrained notifications)
Screen Mode (global overlay notifications)
Mode comparison and when to use each
Application startup configuration (App.xaml.cs)
Customization limitations by mode
When to read: User needs to choose between native OS vs in-app notifications, or configure application startup

📄 阅读： references/display-modes.md

使用WindowsToastBootstrapper配置默认模式（原生系统通知）
窗口模式（受窗口约束的通知）
屏幕模式（全局覆盖通知）
模式对比与适用场景
应用启动配置（App.xaml.cs）
不同模式下的自定义限制
适用场景：需要选择原生系统通知或应用内通知，或配置应用启动项时

Severity & Visual Styling

严重级别与视觉样式

📄 Read: references/severity-and-variants.md

Severity levels (None, Info, Success, Warning, Error)
Visual variants (Text, Outlined, Filled)
AccentBrush customization
Severity + Variant combinations
Visual styling rules and applicability
When to read: User needs to style toasts with colors, severity levels, or custom branding

📄 阅读： references/severity-and-variants.md

严重级别（无、信息、成功、警告、错误）
视觉变体（文本型、轮廓型、填充型）
AccentBrush自定义
严重级别与变体的组合
视觉样式规则与适用范围
适用场景：需要为通知添加颜色区分、严重级别标识或自定义品牌样式时

Placement & Animations

位置与动画

📄 Read: references/placement-and-animations.md

8 placement positions (TopLeft, TopCenter, TopRight, etc.)
Animation types (Fade, Zoom, Slide, Flip)
ShowAnimationType and CloseAnimationType
Animation reference table
When to read: User needs to position toasts or add animation effects

📄 阅读： references/placement-and-animations.md

8种位置选项（左上、顶部居中、右上等）
动画类型（淡入淡出、缩放、滑动、翻转）
ShowAnimationType与CloseAnimationType属性
动画参考表
适用场景：需要调整通知位置或添加动画效果时

Action Buttons

操作按钮

📄 Read: references/action-buttons.md

Simple action buttons
Action buttons with callbacks
CloseOnClick behavior
Custom ActionTemplate with DataTemplate
Multiple actions handling
When to read: User needs interactive buttons, callbacks, or custom button styling

📄 阅读： references/action-buttons.md

简单操作按钮
带回调的操作按钮
CloseOnClick行为
使用DataTemplate自定义ActionTemplate
多操作处理
适用场景：需要添加交互式按钮、回调逻辑或自定义按钮样式时

Template Customization

模板自定义

📄 Read: references/template-customization.md

TitleTemplate customization
ContentTemplate customization
CloseButtonTemplate customization
DataTemplate structure and resource binding
Advanced template scenarios
When to read: User needs to fully customize toast appearance beyond built-in options

📄 阅读： references/template-customization.md

TitleTemplate自定义
ContentTemplate自定义
CloseButtonTemplate自定义
DataTemplate结构与资源绑定
高级模板场景
适用场景：需要超越内置选项，完全自定义通知外观时

Quick Start Example

快速入门示例

Basic Information Toast

基础信息提示框

csharp

using System.Windows;
using Syncfusion.UI.Xaml.SfToastNotification;

namespace ToastDemo
{
    public partial class MainWindow : Window
    {
        public MainWindow()
        {
            InitializeComponent();
        }

        private void ShowToast_Click(object sender, RoutedEventArgs e)
        {
            // Simple toast with title and message
            SfToastNotification.Show(this, new ToastOptions
            {
                Mode = ToastMode.Screen,
                Title = "Welcome",
                Message = "Hello! This is your first toast notification."
            });
        }
    }
}

csharp

using System.Windows;
using Syncfusion.UI.Xaml.SfToastNotification;

namespace ToastDemo
{
    public partial class MainWindow : Window
    {
        public MainWindow()
        {
            InitializeComponent();
        }

        private void ShowToast_Click(object sender, RoutedEventArgs e)
        {
            // Simple toast with title and message
            SfToastNotification.Show(this, new ToastOptions
            {
                Mode = ToastMode.Screen,
                Title = "Welcome",
                Message = "Hello! This is your first toast notification."
            });
        }
    }
}

Success Toast with Custom Duration

自定义持续时间的成功提示框

csharp

// Success toast with 8-second duration
SfToastNotification.Show(this, new ToastOptions
{
    Title = "Save Successful",
    Message = "Your document has been saved successfully.",
    Severity = ToastSeverity.Success,
    Mode = ToastMode.Screen,
    Duration = TimeSpan.FromSeconds(8)
});

csharp

// Success toast with 8-second duration
SfToastNotification.Show(this, new ToastOptions
{
    Title = "Save Successful",
    Message = "Your document has been saved successfully.",
    Severity = ToastSeverity.Success,
    Mode = ToastMode.Screen,
    Duration = TimeSpan.FromSeconds(8)
});

Error Toast with Action Buttons

带操作按钮的错误提示框

csharp

// Error toast with Retry and Dismiss actions
SfToastNotification.Show(this, new ToastOptions
{
    Title = "Operation Failed",
    Message = "Unable to save your changes. Please try again.",
    Severity = ToastSeverity.Error,
    Mode = ToastMode.Screen,
    Actions = new List<ToastAction>
    {
        new ToastAction("Retry")
        {
            Callback = () => RetryOperation(),
            CloseOnClick = true
        },
        new ToastAction("Dismiss")
        {
            CloseOnClick = true
        }
    }
});

csharp

// Error toast with Retry and Dismiss actions
SfToastNotification.Show(this, new ToastOptions
{
    Title = "Operation Failed",
    Message = "Unable to save your changes. Please try again.",
    Severity = ToastSeverity.Error,
    Mode = ToastMode.Screen,
    Actions = new List<ToastAction>
    {
        new ToastAction("Retry")
        {
            Callback = () => RetryOperation(),
            CloseOnClick = true
        },
        new ToastAction("Dismiss")
        {
            CloseOnClick = true
        }
    }
});

Common Patterns

常见实现模式

Pattern 1: Native OS Notification

模式1：原生系统通知

csharp

// App.xaml.cs - Initialize at startup
private void Application_Startup(object sender, StartupEventArgs e)
{
    WindowsToastBootstrapper.RemoveShortcutOnUnload = true;
    WindowsToastBootstrapper.Initialize("MyApp.App", "MyApplication");
}

// MainWindow.xaml.cs - Show native toast
SfToastNotification.Show(this, new ToastOptions
{
    Title = "New Message",
    Message = "You have received a new message.",
    Mode = ToastMode.Default  // Native OS notification
});

csharp

// App.xaml.cs - Initialize at startup
private void Application_Startup(object sender, StartupEventArgs e)
{
    WindowsToastBootstrapper.RemoveShortcutOnUnload = true;
    WindowsToastBootstrapper.Initialize("MyApp.App", "MyApplication");
}

// MainWindow.xaml.cs - Show native toast
SfToastNotification.Show(this, new ToastOptions
{
    Title = "New Message",
    Message = "You have received a new message.",
    Mode = ToastMode.Default  // Native OS notification
});

Pattern 2: Custom Styled Toast

模式2：自定义样式提示框

csharp

// Filled variant with custom accent color
SfToastNotification.Show(this, new ToastOptions
{
    Title = "Custom Toast",
    Message = "This toast uses custom styling.",
    Mode = ToastMode.Screen,
    Severity = ToastSeverity.Info,
    Variant = ToastVariant.Filled,
    AccentBrush = new SolidColorBrush(Colors.Purple),
    Placement = ToastPlacement.BottomRight,
    ShowAnimationType = ToastAnimation.SlideBottomIn,
    CloseAnimationType = ToastAnimation.SlideBottomOut
});

csharp

// Filled variant with custom accent color
SfToastNotification.Show(this, new ToastOptions
{
    Title = "Custom Toast",
    Message = "This toast uses custom styling.",
    Mode = ToastMode.Screen,
    Severity = ToastSeverity.Info,
    Variant = ToastVariant.Filled,
    AccentBrush = new SolidColorBrush(Colors.Purple),
    Placement = ToastPlacement.BottomRight,
    ShowAnimationType = ToastAnimation.SlideBottomIn,
    CloseAnimationType = ToastAnimation.SlideBottomOut
});

Pattern 3: Persistent Toast (No Auto-Close)

模式3：持久化提示框（无自动关闭）

csharp

// Toast remains until user closes it
var options = new ToastOptions
{
    Id = "important-notification",
    Title = "Important Update",
    Message = "Please review this notification carefully.",
    Mode = ToastMode.Screen,
    Severity = ToastSeverity.Warning,
    PreventAutoClose = true  // Disable auto-close
};

SfToastNotification.Show(this, options);

// Manually close later by ID
SfToastNotification.Close("important-notification");

csharp

// Toast remains until user closes it
var options = new ToastOptions
{
    Id = "important-notification",
    Title = "Important Update",
    Message = "Please review this notification carefully.",
    Mode = ToastMode.Screen,
    Severity = ToastSeverity.Warning,
    PreventAutoClose = true  // Disable auto-close
};

SfToastNotification.Show(this, options);

// Manually close later by ID
SfToastNotification.Close("important-notification");

Pattern 4: Multiple Action Buttons

模式4：多操作按钮提示框

csharp

SfToastNotification.Show(this, new ToastOptions
{
    Title = "New Email",
    Message = "You have a new message from John Doe.",
    Mode = ToastMode.Screen,
    Actions = new List<ToastAction>
    {
        new ToastAction("Reply")
        {
            Arguments = "Reply",
            Callback = () => OpenReplyDialog(),
            CloseOnClick = true
        },
        new ToastAction("Mark as Read")
        {
            Callback = () => MarkAsRead(),
            CloseOnClick = true
        },
        new ToastAction("Later")
        {
            CloseOnClick = true
        }
    }
});

csharp

SfToastNotification.Show(this, new ToastOptions
{
    Title = "New Email",
    Message = "You have a new message from John Doe.",
    Mode = ToastMode.Screen,
    Actions = new List<ToastAction>
    {
        new ToastAction("Reply")
        {
            Arguments = "Reply",
            Callback = () => OpenReplyDialog(),
            CloseOnClick = true
        },
        new ToastAction("Mark as Read")
        {
            Callback = () => MarkAsRead(),
            CloseOnClick = true
        },
        new ToastAction("Later")
        {
            CloseOnClick = true
        }
    }
});

Key Properties

核心属性

Property	Type	Purpose	Default
Title	string	Bold text at top of toast	null
Message	string	Main body text	null
Header	string	Additional header (Window/Screen only)	null
Mode	ToastMode	Default, Window, or Screen	Default
Severity	ToastSeverity	None, Info, Success, Warning, Error	None
Variant	ToastVariant	Text, Outlined, Filled	Text
Duration	TimeSpan	How long toast stays visible	6 seconds
PreventAutoClose	bool	Disable auto-close	false
Placement	ToastPlacement	Screen position (8 options)	TopRight
AccentBrush	Brush	Custom color accent	null
ShowAnimationType	ToastAnimation	Show animation effect	FadeIn
CloseAnimationType	ToastAnimation	Hide animation effect	FadeOut
Actions	List<ToastAction>	Interactive action buttons	null
ShowActionButtons	bool	Display action button row	true
ShowCloseButton	bool	Display close button	true
Id	string	Unique identifier for management	null

属性	类型	用途	默认值
Title	string	提示框顶部的粗体文本	null
Message	string	主体消息文本	null
Header	string	附加头部信息（仅窗口/屏幕模式支持）	null
Mode	ToastMode	显示模式（默认、窗口、屏幕）	Default
Severity	ToastSeverity	严重级别（无、信息、成功、警告、错误）	None
Variant	ToastVariant	视觉变体（文本、轮廓、填充）	Text
Duration	TimeSpan	提示框显示时长	6秒
PreventAutoClose	bool	禁用自动关闭	false
Placement	ToastPlacement	屏幕位置（8种选项）	TopRight
AccentBrush	Brush	自定义强调色	null
ShowAnimationType	ToastAnimation	显示动画效果	FadeIn
CloseAnimationType	ToastAnimation	关闭动画效果	FadeOut
Actions	List<ToastAction>	交互式操作按钮	null
ShowActionButtons	bool	显示操作按钮行	true
ShowCloseButton	bool	显示关闭按钮	true
Id	string	用于管理的唯一标识	null

Common Use Cases

常见业务场景

Use Case 1: Save Operation Feedback

场景1：保存操作反馈

Show success confirmation when user saves a document or form.

csharp

SfToastNotification.Show(this, new ToastOptions
{
    Title = "Saved",
    Message = "Your changes have been saved successfully.",
    Severity = ToastSeverity.Success,
    Mode = ToastMode.Screen,
    Duration = TimeSpan.FromSeconds(4)
});

当用户保存文档或表单时，显示成功确认消息。

csharp

SfToastNotification.Show(this, new ToastOptions
{
    Title = "Saved",
    Message = "Your document has been saved successfully.",
    Severity = ToastSeverity.Success,
    Mode = ToastMode.Screen,
    Duration = TimeSpan.FromSeconds(4)
});

Use Case 2: Validation Errors

场景2：验证错误提示

Display validation errors without blocking the UI.

csharp

SfToastNotification.Show(this, new ToastOptions
{
    Title = "Validation Error",
    Message = "Please fill in all required fields before submitting.",
    Severity = ToastSeverity.Error,
    Mode = ToastMode.Screen,
    Placement = ToastPlacement.TopCenter
});

在不阻塞UI的情况下显示验证错误信息。

csharp

SfToastNotification.Show(this, new ToastOptions
{
    Title = "Validation Error",
    Message = "Please fill in all required fields before submitting.",
    Severity = ToastSeverity.Error,
    Mode = ToastMode.Screen,
    Placement = ToastPlacement.TopCenter
});

Use Case 3: Background Task Completion

场景3：后台任务完成通知

Notify users when long-running background tasks complete.

csharp

SfToastNotification.Show(this, new ToastOptions
{
    Title = "Export Complete",
    Message = "Your data has been exported to Excel.",
    Severity = ToastSeverity.Info,
    Mode = ToastMode.Default,  // Native OS notification
    Actions = new List<ToastAction>
    {
        new ToastAction("Open File")
        {
            Callback = () => OpenExportedFile(),
            CloseOnClick = true
        }
    }
});

当长时间后台任务完成时，通知用户。

csharp

SfToastNotification.Show(this, new ToastOptions
{
    Title = "Export Complete",
    Message = "Your data has been exported to Excel.",
    Severity = ToastSeverity.Info,
    Mode = ToastMode.Default,  // Native OS notification
    Actions = new List<ToastAction>
    {
        new ToastAction("Open File")
        {
            Callback = () => OpenExportedFile(),
            CloseOnClick = true
        }
    }
});

Use Case 4: Warning Messages

场景4：警告消息提示

Show warnings about unsaved changes or pending operations.

csharp

SfToastNotification.Show(this, new ToastOptions
{
    Title = "Unsaved Changes",
    Message = "You have unsaved changes. Don't forget to save before closing.",
    Severity = ToastSeverity.Warning,
    Mode = ToastMode.Screen,
    Duration = TimeSpan.FromSeconds(10),
    Placement = ToastPlacement.BottomCenter
});

显示关于未保存更改或待处理操作的警告。

csharp

SfToastNotification.Show(this, new ToastOptions
{
    Title = "Unsaved Changes",
    Message = "You have unsaved changes. Don't forget to save before closing.",
    Severity = ToastSeverity.Warning,
    Mode = ToastMode.Screen,
    Duration = TimeSpan.FromSeconds(10),
    Placement = ToastPlacement.BottomCenter
});

Use Case 5: Real-Time Notifications

场景5：实时通知

Display real-time updates like new messages or system alerts.

csharp

SfToastNotification.Show(this, new ToastOptions
{
    Id = "notification-" + DateTime.Now.Ticks,
    Title = "New Message",
    Message = $"From: {senderName}\n{messagePreview}",
    Severity = ToastSeverity.Info,
    Mode = ToastMode.Screen,
    Placement = ToastPlacement.BottomRight,
    PreventAutoClose = false,
    Duration = TimeSpan.FromSeconds(7)
});

显示新消息或系统警报等实时更新。

csharp

SfToastNotification.Show(this, new ToastOptions
{
    Id = "notification-" + DateTime.Now.Ticks,
    Title = "New Message",
    Message = $"From: {senderName}\n{messagePreview}",
    Severity = ToastSeverity.Info,
    Mode = ToastMode.Screen,
    Placement = ToastPlacement.BottomRight,
    PreventAutoClose = false,
    Duration = TimeSpan.FromSeconds(7)
});

Additional Resources

额外资源

Syncfusion Documentation: Toast Notification Overview
API Reference: SfToastNotification Class

Syncfusion官方文档： Toast Notification Overview
API参考： SfToastNotification Class