syncfusion-angular-popups

实现 Syncfusion Angular 弹出窗口

对话框

Dialog 组件是一个向用户显示信息并用于获取用户输入的窗口。它支持模态对话框（阻止与父级交互）和非模态对话框（允许与父级交互）。

组件概述

主要功能

• 模态和非模态模式 - 阻止或允许与父级交互
• 模板 - 可自定义的标题、内容和页脚
• 定位 - 9 种内置位置或自定义位置
• 动画 - 流畅的打开/关闭效果（淡入淡出、缩放、滑动）
• 可拖动和可调整大小 - 允许用户移动和调整对话框大小
• 表单集成 - 响应式表单和模板驱动表单
• 无障碍功能 - 全面支持 WCAG 2.2 AA 级标准和 ARIA
• 键盘导航 - Tab、Escape、Enter 和箭头键
• 响应式设计 - 在移动设备上支持全屏模式

文档和导航指南

需要实现对话框功能时，请参考以下文档：

入门指南

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

• 在 Angular 21+ 中安装和设置
• 基本对话框实现
• CSS 导入和主题
• 打开和关闭对话框
• 内置按钮支持

对话框模式和类型

📄 阅读： references/dialog-modal-vs-modeless.md

• 模态对话框行为（阻止与父级交互）
• 非模态对话框行为（允许与父级交互）
• 使用场景及模式选择指南
• 在不同模式之间切换
• 遮罩自定义和样式设置

内容和模板

📄 阅读： references/dialog-templates-and-content.md

• 标题模板和自定义
• 使用字符串、HTML 或 ng-template 作为内容
• 带按钮的页脚模板
• 使用 ng-content 添加动态内容
• 按钮绑定和点击事件
• 动态按钮数组

定位和尺寸

📄 阅读： references/dialog-positioning-and-sizing.md

• 内置位置（9 个位置：顶部、居中、底部等）
• 使用 X、Y 坐标自定义定位
• 配置宽度和高度
• 最小/最大高度限制
• 在不同屏幕尺寸下进行响应式尺寸调整
• 在移动设备上支持全屏模式

样式和自定义

📄 阅读： references/dialog-styling-and-customization.md

• CSS 类自定义（标题、内容、页脚、遮罩）
• 主题集成（Material、Bootstrap、Tailwind、Fluent）
• 深色模式支持
• 动画效果（淡入淡出、缩放、向左滑动、向右滑动等）
• 图标自定义（关闭按钮、调整大小手柄）
• RTL（从右到左）语言支持

无障碍功能和表单

📄 阅读： references/dialog-accessibility-and-forms.md

• 符合 WCAG 2.2 AA 级标准
• ARIA 属性（aria-labelledby、aria-describedby、aria-modal、aria-grabbed）
• 键盘导航模式（Tab、Shift+Tab、Escape、Enter）
• 屏幕阅读器支持和最佳实践
• 使用 FormValidator 验证表单
• 响应式表单模式
• 模板驱动表单模式
• 自定义验证规则和错误处理

交互和事件

📄 阅读： references/dialog-interaction-and-events.md

• 对话框打开/关闭事件
• 可拖动的对话框（允许用户移动对话框）
• 可调整大小的对话框（允许用户调整大小）
• 按钮点击事件和处理
• 内容交互模式
• 阻止关闭对话框
• 焦点管理
• 对话框生命周期事件

高级模式

📄 阅读： references/dialog-advanced-patterns.md

• 嵌套对话框（对话框中嵌套对话框）
• 动态加载 Ajax 内容
• 用于以编程方式创建对话框的实用函数
• 复杂布局（富文本编辑器、多步骤表单）
• 滚动处理和自动居中
• 自定义事件发射器
• 路由集成模式

API 参考（完整）

📄 阅读： references/dialog-api-reference.md

• 完整的 Dialog API 文档
• 所有有效属性及其类型和示例
• 所有方法（show、hide、refresh、destroy）
• 所有事件（beforeOpen、beforeClose、drag、resize 等）
• 接口和模型（AnimationSettingsModel、ButtonPropsModel 等）
• 有效枚举（DialogEffect、ResizeDirections）
• Syncfusion 官方文档链接

快速入门示例

下面是打开基本模态对话框的最简示例：

import { Component, ViewChild } from '@angular/core';
import { DialogModule, DialogComponent } from '@syncfusion/ej2-angular-popups';

@Component({
  selector: 'app-root',
  imports: [DialogModule],
  template: `
    <div id="dialog-container" style="height: 500px;">
      <button class="e-control e-btn" (click)="onOpenDialog()">
        Open Dialog
      </button>
      
      <ejs-dialog 
        #ejDialog
        target="#dialog-container"
        [showCloseIcon]="true"
        width="400px"
        content="This is a Dialog content"
      >
        <ng-template #header>
          <div class="e-dlg-header-content">
            <span>Dialog Title</span>
          </div>
        </ng-template>
      </ejs-dialog>
    </div>
  `
})
export class AppComponent {
  @ViewChild('ejDialog') ejDialog!: DialogComponent;

  onOpenDialog(): void {
    this.ejDialog.show();
  }
}

CSS：

#dialog-container {
  height: 500px;
}

常见模式

模式 1：模态确认对话框

// Create a modal dialog for confirmation
<ejs-dialog 
  [isModal]="true"
  [showCloseIcon]="true"
  width="350px"
  content="Are you sure you want to delete this item?"
>
  <ng-template #footerTemplate>
    <button class="e-control e-btn e-primary" (click)="onConfirm()">
      Yes, Delete
    </button>
    <button class="e-control e-btn" (click)="onCancel()">
      Cancel
    </button>
  </ng-template>
</ejs-dialog>

模式 2：带表单的对话框（响应式表单）

// Dialog containing a reactive form
<ejs-dialog [showCloseIcon]="true" width="450px">
  <form [formGroup]="form">
    <div class="e-dlg-content">
      <input formControlName="name" placeholder="Enter name" />
      <input formControlName="email" placeholder="Enter email" />
    </div>
  </form>
  
  <ng-template #footerTemplate>
    <button class="e-control e-btn e-primary" (click)="onSubmit()">
      Submit
    </button>
  </ng-template>
</ejs-dialog>

模式 3：定位对话框

// Dialog positioned at a specific location
<ejs-dialog 
  [position]="{ X: 100, Y: 50 }"
  width="400px"
  content="Positioned Dialog"
>
</ejs-dialog>

关键属性速查

属性	类型	用途	示例
isModal	boolean	阻止与父级交互	[isModal]="true"
showCloseIcon	boolean	在标题栏中显示关闭按钮	[showCloseIcon]="true"
width	string | number	设置对话框宽度	width="400px"
height	string | number	设置对话框高度	height="300px"
minHeight	string | number	最小高度限制	[minHeight]="200"
position	PositionDataModel	设置位置（X、Y）或预设位置	[position]="{ X: 'center', Y: 'center' }"
target	HTMLElement | string	设置容器元素	target="#container"
content	string | HTMLElement	设置内容文本或 HTML	content="Hello"
header	string | HTMLElement	设置标题文本或元素	header="Title"
buttons	ButtonPropsModel[]	添加页脚按钮	[buttons]="buttonArray"
closeOnEscape	boolean	按 Escape 键时关闭	[closeOnEscape]="true"
allowDragging	boolean	启用标题栏拖动	[allowDragging]="true"
enableResize	boolean	启用调整大小	[enableResize]="true"
resizeHandles	ResizeDirections[]	指定调整大小的方向	[resizeHandles]="['All']"
cssClass	string	自定义 CSS 类	cssClass="custom-dialog"
animationSettings	AnimationSettingsModel	配置动画	[animationSettings]="{ effect: 'FadeZoom' }"
enablePersistence	boolean	在重新加载之间保存状态	[enablePersistence]="true"
zIndex	number	用于分层的 Z 顺序	[zIndex]="1000"

常见用例

1. 删除前确认 - 使用模态对话框请求用户确认删除
2. 表单提交 - 使用带表单的对话框供用户提交数据
3. 警报和通知 - 向用户显示重要信息
4. 多步骤流程 - 使用嵌套对话框构建工作流
5. 设置面板 - 使用非模态对话框显示设置，不阻止用户交互
6. 帮助和指导 - 在可拖动的对话框中显示帮助内容
7. 加载状态 - 处理过程中在对话框中显示进度
8. 错误处理 - 在模态对话框中显示错误消息

---

相关技能

• 对话框动画 - 自定义打开和关闭动画
• 表单验证 - 验证对话框中的用户输入
• 路由集成 - 将对话框与 Angular 路由结合使用

预定义对话框

本技能介绍如何使用 Syncfusion 的 DialogUtility 构建警报、确认和提示对话框。这是一种无需模板、以工具为先的方法，可在 Angular 应用中显示模态反馈和用户输入对话框。

应使用哪种对话框类型？

需求	对话框类型	API
警告或告知用户，提供单个“确定”按钮	警告框	DialogUtility.alert(...)
请求确认（“确定”+“取消”）	确认框	DialogUtility.confirm(...)
收集用户输入（HTML 内容 +“确定”+“取消”）	提示框	使用 content 中的输入内容调用 DialogUtility.confirm(...)

关键点： Angular 的预定义对话框没有单独的“提示”方法——可在 content 属性中使用自定义 HTML，通过 DialogUtility.confirm() 构建提示模式。

快速入门

ng add @syncfusion/ej2-angular-popups

// src/app/app.ts
import { Component } from '@angular/core';
import { DialogModule } from '@syncfusion/ej2-angular-popups';
import { ButtonModule } from '@syncfusion/ej2-angular-buttons';
import { DialogUtility } from '@syncfusion/ej2-popups';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [DialogModule, ButtonModule],
  template: `
    <button ejs-button cssClass="e-danger" (click)="showAlert()">Alert</button>
    <button ejs-button cssClass="e-success" (click)="showConfirm()" style="margin-left:8px">Confirm</button>
    <button ejs-button [isPrimary]="true" (click)="showPrompt()" style="margin-left:8px">Prompt</button>
  `
})
export class App {
  showAlert(): void {
    DialogUtility.alert({
      title: 'Warning',
      content: 'Disk space is running low.',
      width: '280px'
    });
  }

  showConfirm(): void {
    const dlg = DialogUtility.confirm({
      title: 'Delete Item',
      content: 'Are you sure you want to delete this item?',
      width: '300px',
      okButton: { text: 'Yes', click: () => { dlg.hide(); /* handle confirm */ } },
      cancelButton: { text: 'No', click: () => { dlg.hide(); } }
    });
  }

  showPrompt(): void {
    const dlg = DialogUtility.confirm({
      title: 'Enter Name',
      content: '<p>Your name:</p><input id="nameInput" class="e-input" type="text" placeholder="Type here..." />',
      width: '300px',
      okButton: {
        text: 'Submit',
        click: () => {
          const value = (document.getElementById('nameInput') as HTMLInputElement).value;
          dlg.hide();
          // use value
        }
      },
      cancelButton: { text: 'Cancel', click: () => dlg.hide() }
    });
  }
}

/* styles.css */
@import '../node_modules/@syncfusion/ej2-base/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-icons/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-buttons/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-angular-popups/styles/material3.css';

常见模式

模式 1 — 带图标的删除确认：

DialogUtility.confirm({
  title: 'Delete Files',
  content: 'Permanently delete selected files?',
  width: '300px',
  okButton: { text: 'Yes', icon: 'e-icons e-check' },
  cancelButton: { text: 'No', icon: 'e-icons e-close' }
});

模式 2 — 带关闭按钮并支持 ESC 键的警告框：

DialogUtility.alert({
  title: 'Session Expired',
  content: 'Your session has expired. Please log in again.',
  width: '300px',
  showCloseIcon: true,
  closeOnEscape: true
});

模式 3 — 指定位置的模态确认框：

DialogUtility.confirm({
  title: 'Confirm Action',
  content: 'Submit the form?',
  isModal: true,
  position: { X: 'center', Y: 'center' },
  animationSettings: { effect: 'Zoom' },
  isDraggable: true,
  width: '280px'
});

关键属性一览

属性	用途	默认值
title	对话框标题文本	—
content	正文文本或 HTML 字符串	—
width	对话框宽度（px 或 %）	'100%'
isModal	遮罩层 + 模态行为	false
isDraggable	允许拖动标题栏以重新定位	false
showCloseIcon	显示 × 关闭按钮	false
closeOnEscape	按 ESC 键关闭	false
position	{ X, Y } — 预定义位置或偏移量	center/center
animationSettings	{ effect, duration, delay }	Fade, 400ms
okButton	“确定”按钮配置 { text, icon, click }	—
cancelButton	“取消”按钮配置 { text, icon, click }	—
cssClass	对话框根元素上的自定义 CSS 类	''
zIndex	堆叠顺序	1000
open	对话框打开后的回调	—
close	对话框关闭后的回调	—

文档

快速入门

📄 阅读： references/getting-started.md

• 安装和软件包设置
• CSS 导入和主题选项
• 基本的警告框、确认框和提示框示例
• 所有 DialogUtility 选项属性

自定义

📄 阅读： references/customization.md

• 自定义按钮文本和图标
• 显示/隐藏关闭图标及 ESC 键行为
• 在对话框中使用自定义 HTML 内容
• 使用 hide() 以编程方式关闭对话框

位置和尺寸

📄 阅读： references/position-and-dimension.md

• 位置 X/Y 值和偏移量用法
• 宽度和高度属性
• 通过 cssClass 设置最大宽度/最大高度
• 通过 cssClass 设置最小宽度/最小高度

动画和可拖动性

📄 阅读： references/animation-and-draggable.md

• animationSettings 效果选项（Zoom、Fade、FadeZoom 等）
• 时长和延迟配置
• 所有对话框类型的 isDraggable 属性

事件和模式

📄 阅读： references/events-and-patterns.md

• open 和 close 事件回调
• isModal、zIndex、cssClass 的高级用法
• 常见实际应用模式（删除确认、表单提示、信息警告）
• 管理多个对话框实例

API 参考

📄 阅读： references/api.md

• 完整的 DialogUtility.alert() 和 DialogUtility.confirm() 选项
• okButton / cancelButton 的 ButtonArgs 属性
• AnimationSettingsModel 属性
• PositionDataModel 属性
• DialogComponent 属性、方法和事件

工具提示

Syncfusion Angular 工具提示（ejs-tooltip）会在你将鼠标悬停、单击、聚焦或触摸目标元素时，显示包含信息或消息的弹出框。它支持 12 种位置、动画、HTML/模板/AJAX 内容、粘性模式、鼠标跟随以及完整的无障碍合规性。

导航指南

入门

📄 阅读： references/getting-started.md

• 安装和软件包设置（ng add @syncfusion/ej2-angular-popups）
• CSS 主题导入
• 基本的单目标工具提示
• 使用 target 属性的多目标工具提示
• 独立式（Angular 19+）和基于模块的设置

内容

📄 阅读： references/content.md

• 静态文本和 HTML 字符串内容
• 使用 ng-template 的模板内容
• 通过 beforeRender 事件使用 AJAX/Fetch 加载动态内容
• 在工具提示中加载 HTML 元素（iframe、视频）
• enableHtmlParse 和 enableHtmlSanitizer 选项

位置和尺寸

📄 阅读： references/position-and-dimension.md

• 全部 12 种位置值（TopCenter、BottomLeft 等）
• 显示/隐藏提示箭头及其位置
• 鼠标跟随
• 偏移值（offsetX、offsetY）
• 宽度、高度和滚动模式
• 窗口碰撞处理

打开模式

📄 阅读： references/open-mode.md

• opensOn：Auto、Hover、Click、Focus、Custom
• 组合多个打开模式
• 使用程序化 open()/close() 的 Custom 模式
• 粘滞模式（isSticky）
• 打开/关闭延迟

动画

📄 阅读： references/animation.md

• 带有打开/关闭设置的 animation 属性
• 所有支持的动画效果
• 通过 open()/close() 方法应用动画
• 自定义过渡效果

自定义和样式

📄 阅读： references/customization-and-style.md

• 使用 cssClass 自定义样式
• 工具提示结构的 CSS 类参考
• 自定义提示箭头
• 花式提示（曲线、气泡）
• SVG 和 canvas 工具提示
• 禁用元素上的工具提示
• 容器、RTL、htmlAttributes

无障碍

📄 阅读： references/accessibility.md

• 符合 WCAG 2.2、Section 508 标准
• WAI-ARIA 属性
• 键盘导航
• 屏幕阅读器支持

API 参考

📄 阅读： references/api.md

• 所有属性、方法和事件
• 类型定义和默认值
• TooltipEventArgs、AnimationModel、TooltipAnimationSettings
• Position、TipPointerPosition 和 Effect 枚举

快速开始

ng add @syncfusion/ej2-angular-popups

// src/app/app.ts (Angular 19+ standalone)
import { Component, ViewEncapsulation } from '@angular/core';
import { TooltipModule } from '@syncfusion/ej2-angular-popups';

@Component({
  standalone: true,
  imports: [TooltipModule],
  selector: 'app-root',
  encapsulation: ViewEncapsulation.None,
  template: `
    <ejs-tooltip content="Hello, I am a Tooltip!" position="BottomCenter">
      <button>Hover me</button>
    </ejs-tooltip>
  `
})
export class App {}

/* styles.css */
@import "@syncfusion/ej2-base/styles/material3.css";
@import "@syncfusion/ej2-angular-buttons/styles/material3.css";
@import "@syncfusion/ej2-angular-popups/styles/material3.css";

常见模式

多目标工具提示（单个实例）

<ejs-tooltip target=".has-tip">
  <div id="container">
    <button class="has-tip" title="Save your work">Save</button>
    <button class="has-tip" title="Delete selected item">Delete</button>
    <button>No tooltip here</button>
  </div>
</ejs-tooltip>

单击时打开的工具提示

<ejs-tooltip content="Clicked!" opensOn="Click" position="RightCenter">
  <button>Click me</button>
</ejs-tooltip>

带关闭按钮的粘滞工具提示

<ejs-tooltip content="I stay until you close me." [isSticky]="true">
  <span>Hover and pin me</span>
</ejs-tooltip>

HTML 内容工具提示

public htmlContent: string = '<b>Bold</b> and <i>italic</i> text with a <a href="#">link</a>.';

<ejs-tooltip [content]="htmlContent">
  <button>Rich content</button>
</ejs-tooltip>

程序化打开/关闭（Custom 模式）

@ViewChild('tooltip') tooltip!: TooltipComponent;

openTip(): void {
  this.tooltip.open(this.tooltip.element);
}
closeTip(): void {
  this.tooltip.close();
}

<ejs-tooltip #tooltip content="Custom trigger" opensOn="Custom">
  <span>Target</span>
</ejs-tooltip>
<button (click)="openTip()">Show</button>
<button (click)="closeTip()">Hide</button>

关键属性一览

属性	类型	默认值	用途
content	string | HTMLElement	—	工具提示内容
position	Position	'TopCenter'	工具提示显示位置
opensOn	string	'Auto'	触发方式：Auto/Hover/Click/Focus/Custom
isSticky	boolean	false	保持打开，直到手动关闭
mouseTrail	boolean	false	跟随鼠标指针
openDelay	number	0	打开前的延迟（毫秒）
closeDelay	number	0	关闭前的延迟（毫秒）
animation	AnimationModel	FadeIn/FadeOut 150ms	打开/关闭动画
target	string	—	多目标选择器
cssClass	string	null	自定义 CSS 类
showTipPointer	boolean	true	显示/隐藏提示箭头
width / height	string | number	'auto'	尺寸

如需查看完整的属性、方法和事件参考，请阅读 references/api.md。