syncfusion-aspnetcore-popups

Syncfusion ASP.NET Core 弹出窗口

对话框

本文介绍如何在 ASP.NET Core 应用中使用 <ejs-dialog> Tag Helper API 实现、配置和自定义 Syncfusion Dialog。内容涵盖设置、模态、定位、动画、模板、事件、无障碍功能和样式。

快速链接

• API 参考
• 入门指南
• 基本功能
• 定位与尺寸
• 动画与过渡效果
• 模板
• 无障碍功能与本地化
• 事件与交互
• 样式与主题

快速入门（Tag Helper）

在 Razor 视图中：

@using Syncfusion.EJ2

<ejs-dialog id="dialog" header="Welcome" isModal="true" width="500px">
    <e-content-template>
        <p>This is a basic dialog with default settings.</p>
    </e-content-template>
</ejs-dialog>

<script>
    window.onload = function () {
        document.getElementById('openBtn').onclick = function () {
            document.getElementById('dialog').ej2_instances[0].show();
        };
    };
</script>

确保在布局文件（_Layout.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>
<ejs-scripts></ejs-scripts>

常见模式

模态确认对话框

<ejs-dialog id="confirmDialog" header="Confirm Action" isModal="true" width="400px">
    <e-dialog-buttons>
        <e-dialog-dialogbutton content="Yes" isPrimary="true" click="confirmAction"></e-dialog-dialogbutton>
        <e-dialog-dialogbutton content="No" click="closeDialog"></e-dialog-dialogbutton>
    </e-dialog-buttons>
    <e-content-template>
        <p>Are you sure you want to proceed?</p>
    </e-content-template>
</ejs-dialog>

带标题栏的可拖动对话框

<ejs-dialog id="draggableDialog" 
    header="Drag Me" 
    allowDragging="true" 
    width="500px" 
    showCloseIcon="true">
    <e-content-template>
        <p>Grab the header to drag this dialog.</p>
    </e-content-template>
</ejs-dialog>

居中对话框

<ejs-dialog id="centeredDialog" 
    header="Centered Position" 
    width="500px">
    <e-dialog-position x="center" y="center"></e-dialog-position>
    <e-content-template>
        <p>This dialog is centered on the page.</p>
    </e-content-template>
</ejs-dialog>

关键属性

Tag Helper 属性	类型	用途	示例
header	string	对话框标题栏文本	header="Confirm Delete"
isModal	bool	在对话框后方显示遮罩层	isModal="true"
width	string	对话框宽度（px、%）	width="500px"
height	string	对话框高度（px、%）	height="300px"
minHeight	string	对话框最小高度	minHeight="150px"
allowDragging	bool	启用拖动以重新定位	allowDragging="true"
enableResize	bool	启用用户调整大小	enableResize="true"
showCloseIcon	bool	显示关闭（X）按钮	showCloseIcon="true"
closeOnEscape	bool	按 Escape 键关闭	closeOnEscape="true"
visible	bool	初始可见性	visible="false"
target	string	目标容器选择器	target="#container"
cssClass	string	自定义 CSS 类	cssClass="my-dialog"
enableRtl	bool	启用从右到左的渲染	enableRtl="true"
enablePersistence	bool	重新加载时保留状态	enablePersistence="true"
zIndex	double	Z 轴堆叠层级	zIndex="2000"
<e-dialog-position>	DialogPositionData	X/Y 定位	x="center" y="center"
<e-dialog-animationsettings>	DialogAnimationSettings	打开/关闭动画	effect="Zoom" duration="400"
footerTemplate	string	自定义页脚 HTML 字符串	footerTemplate="<span>...</span>"

已移除的无效 API： is-hidden（请使用 visible="false"）、position-x/position-y 平面属性（请使用 <e-dialog-position>）、allow-resizing（请使用 enable-resize）、max-height、max-width、min-width（不受支持）。

后续步骤

阅读 getting-started.md，了解完整的安装步骤、NuGet 包设置和配置详情。

预定义对话框

预定义对话框通过 DialogUtility JavaScript 实用程序类以命令式方式打开。它们提供开箱即用的警告、确认和提示对话框，无需设置组件。可使用预定义对话框快速发送通知并获取用户确认。

核心概念

预定义对话框不是 Tag Helper 组件，而是通过 JavaScript 调用：

ej.popups.DialogUtility.alert({ ... });
ej.popups.DialogUtility.confirm({ ... });

---

快速入门

<button class="e-btn e-danger" onclick="showAlert()">Alert</button>

<script>
    function showAlert() {
        ej.popups.DialogUtility.alert({
            title: 'Low Battery',
            width: '250px',
            content: '10% of battery remaining'
        });
    }
</script>

---

文档指南

入门指南

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

• 安装和设置
• 警告、确认和提示对话框的基本示例
• JavaScript 调用模式

位置

📄 阅读： references/predefineddialog-position.md

• 使用 X/Y 值设置 position 属性
• 居中、顶部、底部、左侧和右侧定位
• 自定义像素偏移量

动画

📄 阅读： references/predefineddialog-animation.md

• animationSettings，包含效果、时长和延迟
• Alert、Confirm 和 Prompt 动画示例

可拖动

📄 阅读： references/predefineddialog-draggable.md

• isDraggable 布尔属性
• 对话框拖动重新定位示例

尺寸

📄 阅读： references/predefineddialog-dimension.md

• width 和 height 属性
• 用于尺寸限制（min-width、max-width）的 cssClass

自定义

📄 阅读： references/predefineddialog-customization.md

• 自定义 okButton / cancelButton
• showCloseIcon 和 closeOnEscape
• 使用 HTML 字符串自定义内容

API 参考

📄 阅读： references/predefineddialog-api.md

• DialogUtility.alert() / confirm() 的所有选项属性
• 所有支持的字段和类型

---

常见模式

警告对话框：

ej.popups.DialogUtility.alert({
    title: 'Info',
    content: 'Operation complete.',
    width: '250px'
});

确认对话框：

var dialogObj = ej.popups.DialogUtility.confirm({
    title: 'Delete?',
    content: 'Are you sure?',
    width: '300px',
    okButton: { text: 'Yes', click: function() { /* delete */ dialogObj.hide(); } },
    cancelButton: { text: 'No', click: function() { dialogObj.hide(); } }
});

提示对话框：

var dialogObj = ej.popups.DialogUtility.confirm({
    title: 'Enter Name',
    content: '<p>Your name:</p><input id="nameInput" class="e-input" placeholder="Type here..." />',
    width: '300px',
    okButton: { text: 'Submit', click: function() { var val = document.getElementById('nameInput').value; dialogObj.hide(); } },
    cancelButton: { click: function() { dialogObj.hide(); } }
});

---

Tooltip

一种工具提示组件，当用户将鼠标悬停在元素上、单击元素或将焦点置于元素上时，会显示有用的信息或提示。<ejs-tooltip> Tag Helper 提供灵活的定位方式、动画、多种触发模式和无障碍功能。

Package： Syncfusion.EJ2.AspNet.Core
Tag Helper： <ejs-tooltip>

快速入门

<ejs-tooltip id="tooltip" target="#target" position="TopCenter" content="Tooltip Content">
    <e-content-template>
        <button class="e-btn" id="target">Show Tooltip</button>
    </e-content-template>
</ejs-tooltip>

---

文档指南

入门与设置

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

• 安装和 CSS 导入
• 在单个元素上创建基本工具提示
• 使用 title 属性为多个目标创建工具提示
• 运行应用程序

内容

📄 阅读： references/tooltip-content.md

• 字符串内容和 HTML 标记
• 通过 <e-content-template> 设置模板内容
• 通过 beforeRender 事件设置动态内容
• 出于安全考虑对 HTML 进行净化

定位

📄 阅读： references/tooltip-positioning.md

• 12 种静态位置（TopLeft、TopCenter、TopRight、BottomLeft 等）
• 提示箭头定位（Start、Middle、End）
• 使用 refresh() 方法进行动态定位
• 偏移值（offsetX、offsetY）
• 碰撞处理（windowCollision）

打开模式

📄 阅读： references/tooltip-open-mode.md

• 通过 opensOn 设置 Auto、Hover、Click、Focus、Custom 模式
• 组合多种模式（例如，opensOn="Hover Click"）
• 粘滞模式（isSticky），带关闭按钮
• 打开/关闭延迟（openDelay、closeDelay）

动画

📄 阅读： references/tooltip-animation.md

• 使用 <e-tooltip-animationsettings> 设置打开/关闭效果
• 7 种以上的动画效果（FadeIn、ZoomIn、SlideUp 等）
• 时长和延迟配置
• 将 effect 设为 'None' 可禁用动画

自定义

📄 阅读： references/tooltip-customization.md

• 使用 cssClass 自定义样式
• 提示箭头的显示与自定义
• 尺寸（width、height）
• RTL 支持（enableRtl）
• 鼠标跟随（mouseTrail）

无障碍功能

📄 阅读： references/tooltip-accessibility.md

• 符合 WCAG 2.2 和 Section 508 标准
• ARIA 属性（role、aria-describedby、aria-hidden）
• 键盘导航（Tab、Escape）
• 屏幕阅读器支持和焦点管理
• 无障碍工具提示的最佳实践

API 参考

📄 阅读： references/tooltip-api.md

• 所有属性及其类型和默认值
• 方法：open()、close()、refresh()、destroy()、dataBind()
• 事件：BeforeRender、AfterOpen、AfterClose、Created、Destroyed
• Position 和 TipPointerPosition 枚举值

---

常见模式

按钮上的基本工具提示：

<ejs-tooltip id="tooltip" target="#target" position="TopCenter" content="Submit the form">
    <e-content-template>
        <button class="e-btn" id="target">Submit</button>
    </e-content-template>
</ejs-tooltip>

多目标工具提示：

<ejs-tooltip id="tooltip" target=".info-icon" position="TopCenter">
    <e-content-template>
        <button class="e-btn info-icon" title="Information">Info 1</button>
        <button class="e-btn info-icon" title="Details">Info 2</button>
        <button class="e-btn info-icon" title="Help">Info 3</button>
    </e-content-template>
</ejs-tooltip>

点击触发的固定工具提示：

<ejs-tooltip target="#target" content="Click the × to close me" 
    opensOn="Click" 
    isSticky="true" 
    position="BottomCenter">
    <e-content-template>
        <button id="target" class="e-btn">Click Me</button>
    </e-content-template>
</ejs-tooltip>

以编程方式打开/关闭：

<ejs-tooltip id="tooltip" target="#target" content="Tooltip opened programmatically" opensOn="Custom">
    <e-content-template>
        <button id="target" class="e-btn" onclick="toggleTooltip()">Toggle Tooltip</button>
    </e-content-template>
</ejs-tooltip>

<script>
    function toggleTooltip() {
        var tooltipObj = document.getElementById('tooltip').ej2_instances[0];
        var btn = document.querySelector('.e-btn');
        
        if (btn.getAttribute('data-tooltip-open') === 'true') {
            tooltipObj.close();
            btn.setAttribute('data-tooltip-open', 'false');
        } else {
            tooltipObj.open(btn);
            btn.setAttribute('data-tooltip-open', 'true');
        }
    }
</script>

---

关键属性一览

Tag Helper 属性	类型	默认值	用途
content	string	—	工具提示文本或 HTML
target	string	—	多目标模式的 CSS 选择器
position	Position	'TopCenter'	12 种位置值
opensOn	string	'Auto'	悬停 / 点击 / 焦点 / 自定义
isSticky	bool	false	保持可见，直到用户关闭
mouseTrail	bool	false	跟随鼠标光标
showTipPointer	bool	true	显示/隐藏箭头尖端
tipPointerPosition	TipPointerPosition	'Auto'	自动 / 起始 / 中间 / 末尾
openDelay	number	0	打开前的延迟（毫秒）
closeDelay	number	0	关闭前的延迟（毫秒）
offsetX / offsetY	number	0	与目标的距离（像素）
width / height	string | number	'auto'	工具提示尺寸
cssClass	string	null	自定义 CSS 类
enableRtl	bool	false	从右向左渲染
enableHtmlSanitizer	bool	true	清理 HTML 内容
windowCollision	bool	false	与视口发生碰撞时的处理