syncfusion-aspnetcore-notifications

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Syncfusion ASP.NET Core Toast

The Toast component displays brief, auto-dismissing notification messages on screen. It supports positioning, animations, action buttons, progress bars, templates, timeout control, and accessibility—covering simple alerts to rich notification UIs.

Do NOT skip this skill if users mention: notifications, alerts, snackbar, brief messages, dismiss popup, toast utility, progress notification, action button popup.

Toast组件在屏幕上显示简短的、自动消失的通知消息。它支持定位、动画、操作按钮、进度条、模板、超时控制和无障碍功能，涵盖从简单警报到丰富通知UI的各种场景。

当用户提及以下内容时，请勿跳过此技能： notifications、alerts、snackbar、brief messages、dismiss popup、toast utility、progress notification、action button popup。

Component Overview

组件概述

Key Capabilities

核心功能

Feature	Description
Types / cssClass	Predefined styles: `e-toast-success` , `e-toast-info` , `e-toast-warning` , `e-toast-danger`
Position	X: Left/Center/Right, Y: Top/Bottom or custom pixel/percent values
Timeout	Auto-dismiss via `timeOut` ; `extendedTimeout` for hover delay; `0` for static toast
Progress Bar	Visual countdown bar with `showProgressBar` ; direction via `progressDirection`
Action Buttons	Add button models with click handlers via `buttons` / `e-toast-buttonmodelprops`
Templates	Full custom HTML via `template` property or `<e-content-template>` tag
Animation	Custom show/hide animation effects via `animation` settings
Close Button	Manual close via `showCloseButton`
Multiple Toasts	Separate toast instances per position; `newestOnTop` ordering
Toast Utility	`ToastUtility.show()` for zero-markup quick toasts
Accessibility	WAI-ARIA `role="alert"` , WCAG 2.2 AA, Section 508, RTL support

特性	描述
类型 / cssClass	预定义样式： `e-toast-success` , `e-toast-info` , `e-toast-warning` , `e-toast-danger`
定位	X轴：左/中/右，Y轴：上/下，或自定义像素/百分比值
超时设置	通过 `timeOut` 实现自动消失； `extendedTimeout` 设置悬停延迟；设为 `0` 时Toast保持静态显示
进度条	通过 `showProgressBar` 显示可视化倒计时条；通过 `progressDirection` 设置进度方向
操作按钮	通过 `buttons` / `e-toast-buttonmodelprops` 添加带点击事件的按钮模型
模板	通过 `template` 属性或 `<e-content-template>` 标签实现完全自定义HTML
动画	通过 `animation` 设置自定义显示/隐藏动画效果
关闭按钮	通过 `showCloseButton` 启用手动关闭功能
多Toast支持	不同位置可创建独立Toast实例；通过 `newestOnTop` 设置排序规则
Toast工具类	使用 `ToastUtility.show()` 实现零标记快速创建Toast
无障碍支持	支持WAI-ARIA `role="alert"` 、WCAG 2.2 AA、Section 508、RTL布局

NuGet Package

NuGet包

Install-Package Syncfusion.EJ2.AspNet.Core

Install-Package Syncfusion.EJ2.AspNet.Core

Setup (one-time)

一次性配置

~/Pages/_ViewImports.cshtml

cshtml

@addTagHelper *, Syncfusion.EJ2

~/Pages/Shared/_Layout.cshtml
— inside

<head>

cshtml

<link rel="stylesheet" href="https://cdn.syncfusion.com/ej2/{{ site.ej2version }}/fluent.css" />
<script src="https://cdn.syncfusion.com/ej2/{{ site.ej2version }}/dist/ej2.min.js"></script>

And before

</body>

cshtml

<ejs-scripts></ejs-scripts>

~/Pages/_ViewImports.cshtml

cshtml

@addTagHelper *, Syncfusion.EJ2

~/Pages/Shared/_Layout.cshtml
— 在

<head>

标签内添加：

cshtml

<link rel="stylesheet" href="https://cdn.syncfusion.com/ej2/{{ site.ej2version }}/fluent.css" />
<script src="https://cdn.syncfusion.com/ej2/{{ site.ej2version }}/dist/ej2.min.js"></script>

并在

</body>

标签前添加：

cshtml

<ejs-scripts></ejs-scripts>

Documentation & Navigation Guide

文档与导航指南

📖 Getting Started

📖 快速入门

📄 Read: references/getting-started.md

Installation and NuGet setup
Tag helper registration
Basic toast with title and content
Triggering toast via JavaScript
```
show()
```
method
First working example

📄 阅读： references/getting-started.md

安装与NuGet配置
Tag Helper注册
带标题和内容的基础Toast
通过JavaScript
```
show()
```
方法触发Toast
第一个可运行示例

📖 Configuration & Options

📖 配置与选项

📄 Read: references/configuration.md

Title and content setup
Custom target container
Close button (
```
showCloseButton
```
)
Progress bar (
```
showProgressBar
```
,
```
progressDirection
```
)
Newest-on-top ordering (
```
newestOnTop
```
)
Width and height customization
HTML sanitizer (
```
enableHtmlSanitizer
```
)

📄 阅读： references/configuration.md

标题和内容设置
自定义目标容器
关闭按钮（
```
showCloseButton
```
）
进度条（
```
showProgressBar
```
,
```
progressDirection
```
）
最新消息置顶排序（
```
newestOnTop
```
）
宽高自定义
HTML清理器（
```
enableHtmlSanitizer
```
）

📖 Position & Layout

📖 定位与布局

📄 Read: references/position.md

Predefined X/Y positions (Left, Center, Right / Top, Bottom)
Custom pixel or percentage positions
Multiple toasts in different positions
Full-width toast with
```
width="100%"
```

📄 阅读： references/position.md

预定义X/Y位置（左、中、右 / 上、下）
自定义像素或百分比位置
不同位置的多Toast展示
宽度设为
```
width="100%"
```
的全屏Toast

📖 Timeout & Lifecycle

📖 超时与生命周期

📄 Read: references/timeout.md

Auto-dismiss with
```
timeOut
```
(milliseconds)
Extended hover timeout (
```
extendedTimeout
```
)
Static (persistent) toast with
```
timeOut="0"
```
Closing toast on click/tap
Restricting maximum visible toasts
Preventing duplicate toasts

📄 阅读： references/timeout.md

通过
```
timeOut
```
（毫秒）实现自动消失
悬停延长超时（
```
extendedTimeout
```
）
```
timeOut="0"
```
实现静态（持久）Toast
点击/轻触关闭Toast
限制最大可见Toast数量
防止重复Toast

📖 Action Buttons

📖 操作按钮

📄 Read: references/action-buttons.md

Adding buttons with
```
e-toast-buttonmodelprops
```
Button click handlers
Dismissing toast from a button click

📄 阅读： references/action-buttons.md

通过
```
e-toast-buttonmodelprops
```
添加按钮
按钮点击事件处理
通过按钮点击关闭Toast

📖 Templates & Animation

📖 模板与动画

📄 Read: references/templates-animation.md

Static HTML template via
```
template
```
property
Dynamic content template with
```
<e-content-template>
```
Changing templates dynamically on
```
show()
```
Custom show/hide animation effects
Playing audio before toast opens

📄 阅读： references/templates-animation.md

通过
```
template
```
属性设置静态HTML模板
使用
```
<e-content-template>
```
设置动态内容模板
在
```
show()
```
时动态切换模板
自定义显示/隐藏动画效果
Toast打开前播放音频

📖 Toast Types & Styling

📖 Toast类型与样式

📄 Read: references/types-and-styling.md

Predefined types using
```
cssClass
```
(success, info, warning, danger)
CSS customization for title, content, icon, background
```
ToastUtility.show()
```
with predefined types
```
ToastUtility.show()
```
with full ToastModel
Mobile swipe-close prevention

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

使用
```
cssClass
```
设置预定义类型（success、info、warning、danger）
自定义标题、内容、图标、背景的CSS样式
带预定义类型的
```
ToastUtility.show()
```
带完整ToastModel的
```
ToastUtility.show()
```
移动端防止滑动关闭

📖 Accessibility

📖 无障碍支持

📄 Read: references/accessibility.md

WAI-ARIA role="alert"
WCAG 2.2 AA compliance
Section 508 support
RTL rendering (
```
enableRtl
```
)
Screen reader compatibility

📄 阅读： references/accessibility.md

WAI-ARIA
```
role="alert"
```
WCAG 2.2 AA合规
Section 508支持
RTL渲染（
```
enableRtl
```
）
屏幕阅读器兼容性

📖 API Reference

📖 API参考

📄 Read: references/api.md

All properties with types and defaults
All events (BeforeOpen, Open, Close, BeforeClose, Click, Created, Destroyed, BeforeSanitizeHtml)
Sub-component types (ToastPosition, ToastAnimationSettings, ToastButtonModelProp)

📄 阅读： references/api.md

所有属性的类型与默认值
所有事件（BeforeOpen、Open、Close、BeforeClose、Click、Created、Destroyed、BeforeSanitizeHtml）
子组件类型（ToastPosition、ToastAnimationSettings、ToastButtonModelProp）

Quick Start Example

快速入门示例

cshtml

@* ~/Pages/Index.cshtml *@
<ejs-toast id="toast_default"
           title="Friend Request"
           content="Matt sent you a friend request."
           showCloseButton="true"
           showProgressBar="true"
           timeOut="5000">
    <e-toast-position X="Right" Y="Bottom"></e-toast-position>
</ejs-toast>

<ejs-button id="showBtn" content="Show Toast" cssClass="e-btn"></ejs-button>

<script>
    setTimeout(function () {
        var toast = document.getElementById('toast_default').ej2_instances[0];
        toast.target = document.body;
        toast.show();
    }, 500);

    document.getElementById('showBtn').addEventListener('click', function () {
        var toast = document.getElementById('toast_default').ej2_instances[0];
        toast.show();
    });
</script>

cshtml

@* ~/Pages/Index.cshtml *@
<ejs-toast id="toast_default"
           title="Friend Request"
           content="Matt sent you a friend request."
           showCloseButton="true"
           showProgressBar="true"
           timeOut="5000">
    <e-toast-position X="Right" Y="Bottom"></e-toast-position>
</ejs-toast>

<ejs-button id="showBtn" content="Show Toast" cssClass="e-btn"></ejs-button>

<script>
    setTimeout(function () {
        var toast = document.getElementById('toast_default').ej2_instances[0];
        toast.target = document.body;
        toast.show();
    }, 500);

    document.getElementById('showBtn').addEventListener('click', function () {
        var toast = document.getElementById('toast_default').ej2_instances[0];
        toast.show();
    });
</script>

Common Patterns

常见模式

Pattern 1: Show Typed Notification (Success / Error / Warning / Info)

模式1：显示分类通知（成功/错误/警告/提示）

cshtml

<ejs-toast id="typed_toast">
    <e-toast-position X="Right" Y="Top"></e-toast-position>
</ejs-toast>

<script>
    var toasts = [
        { title: 'Success !', content: 'Record saved successfully.', cssClass: 'e-toast-success' },
        { title: 'Error !',   content: 'Failed to save record.',    cssClass: 'e-toast-danger'  },
        { title: 'Warning !', content: 'Unsaved changes present.',  cssClass: 'e-toast-warning' },
        { title: 'Info !',    content: 'Session expires in 5 min.', cssClass: 'e-toast-info'    }
    ];
    function showToast(index) {
        var toast = document.getElementById('typed_toast').ej2_instances[0];
        toast.target = document.body;
        toast.show(toasts[index]);
    }
</script>

cshtml

<ejs-toast id="typed_toast">
    <e-toast-position X="Right" Y="Top"></e-toast-position>
</ejs-toast>

<script>
    var toasts = [
        { title: 'Success !', content: 'Record saved successfully.', cssClass: 'e-toast-success' },
        { title: 'Error !',   content: 'Failed to save record.',    cssClass: 'e-toast-danger'  },
        { title: 'Warning !', content: 'Unsaved changes present.',  cssClass: 'e-toast-warning' },
        { title: 'Info !',    content: 'Session expires in 5 min.', cssClass: 'e-toast-info'    }
    ];
    function showToast(index) {
        var toast = document.getElementById('typed_toast').ej2_instances[0];
        toast.target = document.body;
        toast.show(toasts[index]);
    }
</script>

Pattern 2: Toast Utility (Zero Markup)

模式2：Toast工具类（零标记）

javascript

// Predefined type — no container element needed
ejs.notifications.ToastUtility.show('Record saved successfully', 'Success', 5000);

// With full model
ejs.notifications.ToastUtility.show({
    title: 'Upload Complete',
    content: 'Your file has been uploaded.',
    timeOut: 5000,
    position: { X: 'Right', Y: 'Bottom' },
    showCloseButton: true
});

javascript

// 预定义类型 — 无需容器元素
ejs.notifications.ToastUtility.show('Record saved successfully', 'Success', 5000);

// 完整模型配置
ejs.notifications.ToastUtility.show({
    title: 'Upload Complete',
    content: 'Your file has been uploaded.',
    timeOut: 5000,
    position: { X: 'Right', Y: 'Bottom' },
    showCloseButton: true
});

Pattern 3: Action Buttons with Close Handler

模式3：带关闭处理的操作按钮

cshtml

<ejs-toast id="action_toast" title="New Message" timeOut="0">
    <e-toast-position X="Right" Y="Bottom"></e-toast-position>
    <e-toast-buttonmodelprops>
        <e-toast-buttonmodelprop model="ViewBag.AcceptBtn" click="onAccept"></e-toast-buttonmodelprop>
        <e-toast-buttonmodelprop model="ViewBag.DismissBtn"></e-toast-buttonmodelprop>
    </e-toast-buttonmodelprops>
</ejs-toast>

<script>
    function onAccept(e) {
        var toastEle = ej.base.closest(e.target, '.e-toast');
        document.getElementById('action_toast').ej2_instances[0].hide(toastEle);
    }
</script>

csharp

// Controller
ViewBag.AcceptBtn  = new { content = "Accept" };
ViewBag.DismissBtn = new { content = "Dismiss" };

cshtml

<ejs-toast id="action_toast" title="New Message" timeOut="0">
    <e-toast-position X="Right" Y="Bottom"></e-toast-position>
    <e-toast-buttonmodelprops>
        <e-toast-buttonmodelprop model="ViewBag.AcceptBtn" click="onAccept"></e-toast-buttonmodelprop>
        <e-toast-buttonmodelprop model="ViewBag.DismissBtn"></e-toast-buttonmodelprop>
    </e-toast-buttonmodelprops>
</ejs-toast>

<script>
    function onAccept(e) {
        var toastEle = ej.base.closest(e.target, '.e-toast');
        document.getElementById('action_toast').ej2_instances[0].hide(toastEle);
    }
</script>

csharp

// 控制器
ViewBag.AcceptBtn  = new { content = "Accept" };
ViewBag.DismissBtn = new { content = "Dismiss" };

Pattern 4: Prevent Duplicate Toast

模式4：防止重复Toast

cshtml

<ejs-toast id="dup_toast" beforeOpen="onBeforeOpen" close="onClose"
           title="Alert" content="Network issue detected.">
    <e-toast-position X="Center" Y="Top"></e-toast-position>
</ejs-toast>

<script>
    var isOpen = false;
    function onBeforeOpen(e) {
        if (isOpen) { e.cancel = true; }
        else { isOpen = true; }
    }
    function onClose() { isOpen = false; }
</script>

cshtml

<ejs-toast id="dup_toast" beforeOpen="onBeforeOpen" close="onClose"
           title="Alert" content="Network issue detected.">
    <e-toast-position X="Center" Y="Top"></e-toast-position>
</ejs-toast>

<script>
    var isOpen = false;
    function onBeforeOpen(e) {
        if (isOpen) { e.cancel = true; }
        else { isOpen = true; }
    }
    function onClose() { isOpen = false; }
</script>

Pattern 5: Restrict Maximum Toasts

模式5：限制最大Toast数量

cshtml

<ejs-toast id="max_toast" beforeOpen="onBeforeOpen"
           title="Notification" content="New item added.">
    <e-toast-position X="Center" Y="Top"></e-toast-position>
</ejs-toast>

<script>
    var maxCount = 3;
    function onBeforeOpen(e) {
        var toast = document.getElementById('max_toast').ej2_instances[0];
        if (toast.element.childElementCount >= maxCount) {
            e.cancel = true;
        }
    }
</script>

cshtml

<ejs-toast id="max_toast" beforeOpen="onBeforeOpen"
           title="Notification" content="New item added.">
    <e-toast-position X="Center" Y="Top"></e-toast-position>
</ejs-toast>

<script>
    var maxCount = 3;
    function onBeforeOpen(e) {
        var toast = document.getElementById('max_toast').ej2_instances[0];
        if (toast.element.childElementCount >= maxCount) {
            e.cancel = true;
        }
    }
</script>