syncfusion-aspnetcore-notifications

实现 Syncfusion ASP.NET Core 通知

Toast

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

**如果用户提到以下内容，请勿跳过此技能：**通知、提醒、snackbar、简短消息、关闭弹出窗口、Toast 工具、进度通知、操作按钮弹出窗口。

---

组件概览

主要功能

功能	说明
类型 / 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 包

Install-Package Syncfusion.EJ2.AspNet.Core

设置（一次性）

~/Pages/_ViewImports.cshtml

@addTagHelper *, Syncfusion.EJ2

~/Pages/Shared/_Layout.cshtml — 在 <head> 内：

<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> 之前：

<ejs-scripts></ejs-scripts>

---

文档与导航指南

📖 入门

📄 阅读： references/getting-started.md

• 安装和 NuGet 设置
• 注册标签帮助程序
• 包含标题和内容的基本 Toast
• 通过 JavaScript show() 方法触发 Toast
• 首个可运行示例

📖 配置与选项

📄 阅读： references/configuration.md

• 设置标题和内容
• 自定义目标容器
• 关闭按钮（showCloseButton）
• 进度条（showProgressBar、progressDirection）
• 最新 Toast 显示在最前（newestOnTop）
• 自定义宽度和高度
• HTML 清理器（enableHtmlSanitizer）

📖 位置与布局

📄 阅读： references/position.md

• 预定义的 X/Y 位置（左侧、居中、右侧 / 顶部、底部）
• 自定义像素值或百分比位置
• 在不同位置显示多个 Toast
• 使用 width="100%" 显示全宽 Toast

📖 超时与生命周期

📄 阅读： references/timeout.md

• 使用 timeOut 自动消失（毫秒）
• 延长悬停超时时间（extendedTimeout）
• 使用 timeOut="0" 显示静态（持久）Toast
• 点击/轻触时关闭 Toast
• 限制最多可见的 Toast 数量
• 防止重复显示 Toast

📖 操作按钮

📄 阅读： references/action-buttons.md

• 使用 e-toast-buttonmodelprops 添加按钮
• 按钮点击处理程序
• 点击按钮时关闭 Toast

📖 模板与动画

📄 阅读： references/templates-animation.md

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

📖 Toast 类型与样式

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

• 使用 cssClass 设置预定义类型（success、info、warning、danger）
• 自定义标题、内容、图标和背景的 CSS
• 使用 ToastUtility.show() 和预定义类型
• 使用 ToastUtility.show() 和完整的 ToastModel
• 禁止在移动设备上通过滑动关闭 Toast

📖 无障碍功能

📄 阅读： references/accessibility.md

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

📖 API 参考

📄 阅读： references/api.md

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

---

快速入门示例

@* ~/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>

---

常见模式

模式 1：显示指定类型的通知（成功 / 错误 / 警告 / 信息）

<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>

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

// 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
});

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

<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>

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

模式 4：防止重复显示 Toast

<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>

模式 5：限制 Toast 的最大数量

<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>

---

消息

Syncfusion Message 组件通过图标和颜色等视觉严重性指示来显示上下文消息，向最终用户传达重要性和上下文。它支持五种严重性级别、三种视觉变体、关闭图标关闭、内容模板，并全面符合无障碍标准。

文档与导航指南

入门

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

• 安装 NuGet 包 Syncfusion.EJ2.AspNet.Core
• 在 _ViewImports.cshtml 中注册标记帮助程序
• 在 _Layout.cshtml 中注册样式表和脚本
• 添加第一个 <ejs-message> 标记帮助程序
• 通过 content 属性或内部内容设置内容
• 第一个可运行示例

严重性级别

📄 阅读： references/message-severities.md

• 五种严重性级别：Normal、Success、Info、Warning、Error
• severity 属性的用法和有效值
• 视觉差异（各严重性对应的图标和颜色）
• 根据使用场景选择合适的严重性
• 根据模型值动态设置严重性

显示变体

📄 阅读： references/message-variants.md

• 三种变体：Text（默认）、Outlined、Filled
• variant 属性的用法
• 组合使用变体和严重性
• 视觉效果的取舍以及各变体的适用场景

图标和关闭图标

📄 阅读： references/message-icons-and-close.md

• 严重性图标的显示：showIcon 属性（默认值为 true）
• 禁用严重性图标
• 通过 cssClass CSS 覆盖自定义严重性图标
• 关闭图标：showCloseIcon 属性（默认值为 false）
• 用于关闭回调的 closed 事件处理程序
• 使用 visible 属性切换可见性

自定义与模板

📄 阅读： references/message-customization.md

• 内容对齐方式：左对齐（默认）、居中（e-content-center）、右对齐（e-content-right）
• 使用 cssClass 自定义外观
• 纯 CSS 消息渲染（无需 JS，仅使用 HTML + CSS）
• 内容模板：<e-content-template> 子元素
• 通过 enableRtl 支持 RTL
• 使用 enablePersistence 保持设置

无障碍功能

📄 阅读： references/message-accessibility.md

• 符合 WCAG 2.2、Section 508 和 ADA 标准
• WAI-ARIA 属性（role="alert"、aria-label）
• 键盘导航（Tab、Enter/Space）
• 支持屏幕阅读器

API 参考

📄 阅读： references/message-api.md

• 所有属性及其类型、默认值和标记属性名称
• 事件：closed、created、destroyed
• Severity 和 Variant 枚举值
• 标记帮助程序语法参考

---

快速入门

@* ~/Pages/Index.cshtml *@
<ejs-message id="msg_default" content="Please read the comments carefully"></ejs-message>

---

常见模式

严重性消息

<ejs-message id="msg_normal"  content="Editing is restricted"></ejs-message>
<ejs-message id="msg_success" content="Operation completed"  severity="Success"></ejs-message>
<ejs-message id="msg_info"    content="Read these notes"     severity="Info"></ejs-message>
<ejs-message id="msg_warning" content="Check your connection" severity="Warning"></ejs-message>
<ejs-message id="msg_error"   content="Submission failed"    severity="Error"></ejs-message>

变体与严重性组合

<ejs-message id="msg_ft" content="Editing is restricted" variant="Filled"></ejs-message>
<ejs-message id="msg_os" content="Operation completed"  severity="Success" variant="Outlined"></ejs-message>
<ejs-message id="msg_fe" content="Submission failed"    severity="Error"   variant="Filled"></ejs-message>

可关闭消息

<ejs-message id="msg_dismiss"
             content="Your session will expire soon"
             severity="Warning"
             showCloseIcon="true"
             visible="true"
             closed="onMessageClosed">
</ejs-message>

<script>
    function onMessageClosed() {
        var msg = document.getElementById('msg_dismiss').ej2_instances[0];
        msg.visible = false;
    }
</script>

内容模板

<ejs-message id="msg_template" severity="Success" showCloseIcon="true" closed="onTemplateClosed">
    <e-content-template>
        <div>
            <h4>Build succeeded</h4>
            <p>All 42 tests passed.</p>
        </div>
    </e-content-template>
</ejs-message>

<script>
    function onTemplateClosed() {
        document.getElementById('msg_template').ej2_instances[0].visible = false;
    }
</script>

---

骨架屏

Syncfusion Skeleton 组件会渲染动画占位形状，模拟加载中内容的布局。它通过可配置的形状、闪烁动画和全面的无障碍支持，降低用户感知到的加载时间并向用户传达进度。

文档与导航指南

入门

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

• 安装 NuGet 包 Syncfusion.EJ2.AspNet.Core
• 在 _ViewImports.cshtml 中注册标签帮助程序
• 在 _Layout.cshtml 中注册样式表和脚本
• 使用 height 和 width 设置最简 <ejs-skeleton>
• 全部四种形状类型（Circle、Square、Text、Rectangle）

形状

📄 阅读： references/skeleton-shapes.md

• shape 属性："Circle"、"Square"、"Rectangle"、"Text"（默认值）
• 尺寸规则：Circle/Square 必须设置宽度；Rectangle/Text 必须设置宽度和高度
• 构建多形状卡片骨架屏布局
• 为头像、图像、文本和图标占位符选择合适的形状

闪烁效果

📄 阅读： references/skeleton-shimmer-effect.md

• shimmerEffect 属性："Wave"（默认值）、"Pulse"、"Fade"
• 各种效果类型的视觉表现
• 使用 Pulse 效果的列表骨架屏示例
• 选择与 UI 场景相匹配的效果

样式与可见性

📄 阅读： references/skeleton-styles.md

• 使用 cssClass 属性自定义 CSS 覆盖（波浪颜色、背景、动画速度）
• 使用 visible 属性，根据加载状态切换骨架屏的显示与隐藏
• 过渡模式：骨架屏 → 实际内容
• 自定义 CSS 变量

无障碍

📄 阅读： references/skeleton-accessibility.md

• 符合 WCAG 2.2、Section 508 和 ADA 要求
• WAI-ARIA 属性：role="status"、aria-label、aria-live、aria-busy
• 使用 label 属性设置无障碍骨架屏名称
• 通过 enableRtl 支持 RTL
• 遵循 prefers-reduced-motion 设置

API 参考

📄 阅读： references/skeleton-api.md

• 所有属性的类型、默认值和标签属性名称
• SkeletonType 和 ShimmerEffect 枚举值
• 标签帮助程序语法参考

---

快速入门

@* ~/Pages/Index.cshtml *@
<ejs-skeleton id="sk_default" height="15px" width="100%"></ejs-skeleton>

---

常见模式

个人资料卡片骨架屏

<div style="display: flex; align-items: center; gap: 12px; padding: 16px;">
    @* Avatar placeholder *@
    <ejs-skeleton id="sk_avatar" shape="Circle" width="48px"></ejs-skeleton>
    @* Name and subtitle placeholders *@
    <div style="flex: 1;">
        <ejs-skeleton id="sk_name" width="60%" height="15px"></ejs-skeleton>
        <br />
        <ejs-skeleton id="sk_sub"  width="40%" height="12px"></ejs-skeleton>
    </div>
</div>

数据加载时切换骨架屏

@{
    var loading = true;
    var content = "Data loaded successfully";
}
<div>
    @if (loading)
    {
        <ejs-skeleton id="sk_loader" width="80%" height="20px"></ejs-skeleton>
    }
    else
    {
        <p>@content</p>
    }
</div>

使用 Pulse 效果的闪烁列表

<ul style="list-style: none; padding: 0;">
    @for (var i = 1; i <= 3; i++)
    {
        <li style="display: flex; gap: 10px; margin-bottom: 12px;">
            <ejs-skeleton id="@($"sk_av_{i}")" shape="Circle" width="40px" shimmerEffect="Pulse"></ejs-skeleton>
            <div style="flex: 1;">
                <ejs-skeleton id="@($"sk_t1_{i}")" width="70%" height="14px" shimmerEffect="Pulse"></ejs-skeleton>
                <br />
                <ejs-skeleton id="@($"sk_t2_{i}")" width="45%" height="12px" shimmerEffect="Pulse"></ejs-skeleton>
            </div>
        </li>
    }
</ul>

---

主要属性一览

属性	类型	默认值	用途
shape	SkeletonType	Text	骨架屏形状类型
width	string	""	宽度；Circle/Square 必须设置
height	string	""	高度；用于 Rectangle/Text
shimmerEffect	ShimmerEffect	Wave	动画样式
visible	bool	true	显示/隐藏骨架屏
css-class	string	""	自定义 CSS 类
label	string	"Loading..."	用于无障碍的 ARIA 标签
enable-rtl	bool	false	从右向左渲染
enable-persistence	bool	false	在重新加载后保留状态