syncfusion-angular-dialog

实现 Dialog

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

组件概览

主要功能

• 模态和非模态模式 - 阻止或允许与父级交互
• 模板 - 可自定义标题、内容和页脚
• 定位 - 内置 9 种位置或自定义放置方式
• 动画 - 流畅的打开/关闭效果（Fade、Zoom、Slide）
• 可拖动和可调整大小 - 允许用户移动和调整对话框大小
• 表单集成 - 响应式表单和模板驱动表单
• 无障碍访问 - 完整支持 WCAG 2.2 AA 级标准及 ARIA
• 键盘导航 - Tab、Escape、Enter 和方向键
• 响应式 - 在移动设备上切换为全屏模式

文档和导航指南

需要实现 Dialog 功能时，请参阅以下文档：

入门

📄 阅读： references/getting-started.md

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

对话框模式和类型

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

• 模态对话框行为（阻止与父级交互）
• 非模态对话框行为（允许与父级交互）
• 使用场景及各模式的适用时机
• 在不同模式间切换
• 遮罩层自定义和样式设置

内容和模板

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

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

定位和尺寸

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

• 内置位置（9 种位置：顶部、居中、底部等）
• 使用 X、Y 坐标自定义定位
• 宽度和高度配置
• 最小/最大高度限制
• 针对不同屏幕尺寸的响应式尺寸
• 在移动设备上切换为全屏模式

样式和自定义

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

• CSS 类自定义（标题、内容、页脚、遮罩层）
• 主题集成（Material、Bootstrap、Tailwind、Fluent）
• 深色模式支持
• 动画效果（Fade、Zoom、SlideLeft、SlideRight 等）
• 图标自定义（关闭按钮、调整大小的控点）
• RTL（从右到左）语言支持

无障碍访问和表单

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

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

交互和事件

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

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

高级模式

📄 阅读： references/advanced-patterns.md

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

API 参考（完整）

📄 阅读： 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 #footer>
    <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 #footer>
    <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 路由中使用对话框