syncfusion-angular-dialog

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Dialog

实现Dialog组件

The Dialog component is a window that displays information to the user and is used to get user input. It supports both modal dialogs (blocking parent interaction) and modeless dialogs (allowing parent interaction).
Dialog组件是一个向用户展示信息并用于获取用户输入的窗口。它同时支持modal对话框(阻止父组件交互)和modeless对话框(允许父组件交互)。

Component Overview

组件概述

Key Features

核心特性

  • Modal & Modeless modes - Block or allow parent interaction
  • Templates - Customizable headers, content, and footers
  • Positioning - 9 built-in positions or custom placement
  • Animations - Smooth open/close effects (Fade, Zoom, Slide)
  • Draggable & Resizable - Allow users to move and resize dialogs
  • Forms Integration - Reactive and template-driven forms
  • Accessibility - Full WCAG 2.2 Level AA support with ARIA
  • Keyboard Navigation - Tab, Escape, Enter, and arrow keys
  • Responsive - Full-screen mode on mobile devices
  • Modal & Modeless模式 - 阻止或允许父组件交互
  • 模板 - 可自定义页眉、内容和页脚
  • 定位 - 9种内置位置或自定义布局
  • 动画 - 流畅的打开/关闭效果(Fade、Zoom、Slide)
  • 可拖动与可调整大小 - 允许用户移动和调整对话框大小
  • 表单集成 - 响应式和模板驱动表单
  • 无障碍支持 - 全面支持WCAG 2.2 Level AA标准及ARIA属性
  • 键盘导航 - 支持Tab、Escape、Enter和方向键
  • 响应式设计 - 在移动设备上自动切换为全屏模式

Documentation and Navigation Guide

文档与导航指南

When you need to implement Dialog features, follow these references:
当你需要实现Dialog组件的各项功能时,请参考以下文档:

Getting Started

快速开始

📄 Read: references/getting-started.md
  • Installation and setup in Angular 21+
  • Basic dialog implementation
  • CSS imports and themes
  • Opening and closing dialogs
  • Built-in button support
📄 阅读: references/getting-started.md
  • Angular 21+中的安装与配置
  • 基础Dialog组件实现
  • CSS导入与主题设置
  • 对话框的打开与关闭
  • 内置按钮支持

Dialog Modes & Types

对话框模式与类型

📄 Read: references/modal-vs-modeless.md
  • Modal dialog behavior (blocks parent interaction)
  • Modeless dialog behavior (allows parent interaction)
  • Use cases and when to use each mode
  • Toggling between modes
  • Overlay customization and styling
📄 阅读: references/modal-vs-modeless.md
  • Modal对话框的行为(阻止父组件交互)
  • Modeless对话框的行为(允许父组件交互)
  • 使用场景及模式选择
  • 模式切换方法
  • 遮罩层自定义与样式设置

Content & Templates

内容与模板

📄 Read: references/templates-and-content.md
  • Header templates and customization
  • Content as strings, HTML, or ng-template
  • Footer templates with buttons
  • Using ng-content for dynamic content
  • Button binding and click events
  • Dynamic button arrays
📄 阅读: references/templates-and-content.md
  • 页眉模板与自定义
  • 内容支持字符串、HTML或ng-template
  • 带按钮的页脚模板
  • 使用ng-content实现动态内容
  • 按钮绑定与点击事件处理
  • 动态按钮数组

Positioning & Sizing

定位与尺寸

📄 Read: references/positioning-and-sizing.md
  • Built-in positions (9 locations: Top, Center, Bottom, etc.)
  • Custom positioning with X, Y coordinates
  • Width and height configuration
  • Min/max height constraints
  • Responsive sizing on different screen sizes
  • Full-screen mode on mobile devices
📄 阅读: references/positioning-and-sizing.md
  • 内置位置(9种:顶部、居中、底部等)
  • 使用X、Y坐标进行自定义定位
  • 宽度与高度配置
  • 最小/最大高度限制
  • 不同屏幕尺寸下的响应式尺寸调整
  • 移动设备上的全屏模式

Styling & Customization

样式与自定义

📄 Read: references/styling-and-customization.md
  • CSS class customization (header, content, footer, overlay)
  • Theme integration (Material, Bootstrap, Tailwind, Fluent)
  • Dark mode support
  • Animation effects (Fade, Zoom, SlideLeft, SlideRight, etc.)
  • Icon customization (close button, resize handles)
  • RTL (Right-to-Left) language support
📄 阅读: references/styling-and-customization.md
  • CSS类自定义(页眉、内容、页脚、遮罩层)
  • 主题集成(Material、Bootstrap、Tailwind、Fluent)
  • 深色模式支持
  • 动画效果(Fade、Zoom、SlideLeft、SlideRight等)
  • 图标自定义(关闭按钮、调整大小手柄)
  • RTL(从右到左)语言支持

Accessibility & Forms

无障碍与表单

📄 Read: references/accessibility-and-forms.md
  • WCAG 2.2 Level AA compliance standards
  • ARIA attributes (aria-labelledby, aria-describedby, aria-modal, aria-grabbed)
  • Keyboard navigation patterns (Tab, Shift+Tab, Escape, Enter)
  • Screen reader support and best practices
  • Form validation with FormValidator
  • Reactive forms patterns
  • Template-driven forms patterns
  • Custom validation rules and error handling
📄 阅读: references/accessibility-and-forms.md
  • WCAG 2.2 Level AA合规标准
  • ARIA属性(aria-labelledby、aria-describedby、aria-modal、aria-grabbed)
  • 键盘导航模式(Tab、Shift+Tab、Escape、Enter)
  • 屏幕阅读器支持与最佳实践
  • 结合FormValidator进行表单验证
  • 响应式表单模式
  • 模板驱动表单模式
  • 自定义验证规则与错误处理

Interaction & Events

交互与事件

📄 Read: references/interaction-and-events.md
  • Dialog open/close events
  • Draggable dialogs (allow users to move dialogs)
  • Resizable dialogs (allow users to resize)
  • Button click events and handling
  • Content interaction patterns
  • Preventing dialog closure
  • Focus management
  • Dialog lifecycle events
📄 阅读: references/interaction-and-events.md
  • 对话框打开/关闭事件
  • 可拖动对话框(允许用户移动对话框)
  • 可调整大小的对话框(允许用户调整尺寸)
  • 按钮点击事件与处理
  • 内容交互模式
  • 阻止对话框关闭
  • 焦点管理
  • 对话框生命周期事件

Advanced Patterns

高级模式

📄 Read: references/advanced-patterns.md
  • Nested dialogs (dialog within dialog)
  • Ajax-loaded content dynamically
  • Utility functions for programmatic creation
  • Complex layouts (Rich Text Editor, multi-step forms)
  • Scroll handling and auto-centering
  • Custom event emitters
  • Routing integration patterns
📄 阅读: references/advanced-patterns.md
  • 嵌套对话框(对话框内嵌套对话框)
  • 动态加载Ajax内容
  • 程序化创建的工具函数
  • 复杂布局(富文本编辑器、多步骤表单)
  • 滚动处理与自动居中
  • 自定义事件发射器
  • 路由集成模式

API Reference (Complete)

完整API参考

📄 Read: api-reference.md
  • Complete Dialog API documentation
  • All valid properties with types and examples
  • All methods (show, hide, refresh, destroy)
  • All events (beforeOpen, beforeClose, drag, resize, etc.)
  • Interfaces and models (AnimationSettingsModel, ButtonPropsModel, etc.)
  • Valid enumerations (DialogEffect, ResizeDirections)
  • Official Syncfusion documentation links
📄 阅读: api-reference.md
  • 完整的Dialog组件API文档
  • 所有有效属性的类型与示例
  • 所有方法(show、hide、refresh、destroy)
  • 所有事件(beforeOpen、beforeClose、drag、resize等)
  • 接口与模型(AnimationSettingsModel、ButtonPropsModel等)
  • 有效枚举(DialogEffect、ResizeDirections)
  • 官方Syncfusion文档链接

Quick Start Example

快速入门示例

Here's a minimal example to open a basic modal dialog:
typescript
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:
css
#dialog-container {
  height: 500px;
}
以下是一个打开基础modal对话框的最简示例:
typescript
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:
css
#dialog-container {
  height: 500px;
}

Common Patterns

常见模式

Pattern 1: Modal Confirmation Dialog

模式1:Modal确认对话框

typescript
// 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>
typescript
// 创建用于确认的modal对话框
<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>

Pattern 2: Dialog with Form (Reactive Forms)

模式2:内嵌表单的对话框(响应式表单)

typescript
// 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>
typescript
// 包含响应式表单的对话框
<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>

Pattern 3: Positioned Dialog

模式3:定位对话框

typescript
// Dialog positioned at a specific location
<ejs-dialog 
  [position]="{ X: 100, Y: 50 }"
  width="400px"
  content="Positioned Dialog"
>
</ejs-dialog>
typescript
// 定位到特定位置的对话框
<ejs-dialog 
  [position]="{ X: 100, Y: 50 }"
  width="400px"
  content="Positioned Dialog"
>
</ejs-dialog>

Key Props Quick Reference

核心属性速查

PropertyTypePurposeExample
isModal
booleanBlock parent interaction
[isModal]="true"
showCloseIcon
booleanShow close button in header
[showCloseIcon]="true"
width
string | numberSet dialog width
width="400px"
height
string | numberSet dialog height
height="300px"
minHeight
string | numberMinimum height constraint
[minHeight]="200"
position
PositionDataModelSet position (X, Y) or preset
[position]="{ X: 'center', Y: 'center' }"
target
HTMLElement | stringSet container element
target="#container"
content
string | HTMLElementSet content text or HTML
content="Hello"
header
string | HTMLElementSet header text or element
header="Title"
buttons
ButtonPropsModel[]Add footer buttons
[buttons]="buttonArray"
closeOnEscape
booleanClose on Escape key
[closeOnEscape]="true"
allowDragging
booleanEnable header dragging
[allowDragging]="true"
enableResize
booleanEnable resizing
[enableResize]="true"
resizeHandles
ResizeDirections[]Specify resize directions
[resizeHandles]="['All']"
cssClass
stringCustom CSS class(es)
cssClass="custom-dialog"
animationSettings
AnimationSettingsModelConfigure animations
[animationSettings]="{ effect: 'FadeZoom' }"
enablePersistence
booleanSave state between reloads
[enablePersistence]="true"
zIndex
numberZ-order for layering
[zIndex]="1000"
属性类型用途示例
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层级顺序
[zIndex]="1000"

Common Use Cases

常见使用场景

  1. Confirmation before delete - Modal dialog asking user to confirm deletion
  2. Form submission - Dialog with form for user to submit data
  3. Alerts and notifications - Display important information to users
  4. Multi-step processes - Use nested dialogs for workflows
  5. Settings panels - Modeless dialog for settings that don't block interaction
  6. Help and guidance - Display help content in a draggable dialog
  7. Loading states - Show progress in a dialog while processing
  8. Error handling - Display error messages in a modal

  1. 删除前确认 - 使用modal对话框确认用户是否要删除内容
  2. 表单提交 - 对话框内嵌表单用于用户提交数据
  3. 提醒与通知 - 向用户展示重要信息
  4. 多步骤流程 - 使用嵌套对话框实现工作流
  5. 设置面板 - 使用modeless对话框实现不阻止交互的设置界面
  6. 帮助与引导 - 在可拖动对话框中展示帮助内容
  7. 加载状态 - 在处理过程中用对话框展示进度
  8. 错误处理 - 在modal对话框中展示错误信息

Related Skills

相关技能

  • Dialog Animation - Customize open/close animations
  • Form Validation - Validate user input in dialogs
  • Routing Integration - Use dialogs with Angular routing
  • Dialog Animation - 自定义打开/关闭动画
  • Form Validation - 验证对话框中的用户输入
  • Routing Integration - 将对话框与Angular路由集成