syncfusion-react-dialog

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing React Dialog

实现React对话框

The DialogComponent displays content in a floating window with support for modal and modeless modes, custom positioning, dragging, resizing, animations, templating, and comprehensive accessibility features.
DialogComponent在浮动窗口中展示内容,支持模态与非模态模式、自定义定位、拖拽、调整大小、动画、模板化以及全面的无障碍功能。

Component Overview

组件概述

DialogComponent Features:
  • Modal/Modeless modes: Control parent interaction blocking
  • 9 preset positions + custom X/Y: Flexible placement
  • Dragging: Header-based drag and drop (allowDragging)
  • Resizing: Diagonal resize grip (enableResize)
  • Templating: Custom header, content, footer
  • Animations: 16 effects (Fade, Zoom, Flip, Slide, FadeZoom, etc.)
  • Buttons: Built-in action buttons with click handlers
  • Events: open, close, beforeOpen, beforeClose, drag, dragStart, dragStop, resize events
  • Keyboard Navigation: Tab, Escape (closeOnEscape), Enter
  • WCAG 2.2 Accessibility: ARIA roles, focus management
  • Localization: 20+ locales via locale property
  • RTL Support: Right-to-left rendering
DialogComponent特性:
  • 模态/非模态模式:控制父级交互阻塞
  • 9种预设位置+自定义X/Y坐标:灵活的布局方式
  • 拖拽功能:基于标题栏的拖放(allowDragging属性)
  • 调整大小:对角线调整手柄(enableResize属性)
  • 模板化:自定义标题、内容、页脚
  • 动画效果:16种动画(淡入、缩放、翻转、滑动、淡入缩放等)
  • 按钮:内置带点击处理器的操作按钮
  • 事件:open、close、beforeOpen、beforeClose、drag、dragStart、dragStop、resize事件
  • 键盘导航:Tab、Escape(closeOnEscape属性)、Enter键
  • WCAG 2.2无障碍支持:ARIA角色、焦点管理
  • 本地化:通过locale属性支持20+种语言环境
  • RTL支持:从右到左渲染

Documentation & Navigation Guide

文档与导航指南

Getting Started

快速开始

📄 Read: references/getting-started.md
  • Installation (
    @syncfusion/ej2-react-popups
    )
  • CSS/theme imports (material, bootstrap, tailwind)
  • Basic DialogComponent JSX structure
  • show()/hide() methods and refs
  • Functional component patterns with hooks
  • Initial visibility with visible prop
📄 阅读: references/getting-started.md
  • 安装(
    @syncfusion/ej2-react-popups
  • CSS/主题导入(material、bootstrap、tailwind)
  • 基础DialogComponent JSX结构
  • show()/hide()方法与refs
  • 结合hooks的函数式组件模式
  • 使用visible属性控制初始可见性

Modal vs Modeless

模态 vs 非模态

📄 Read: references/modal-vs-modeless.md
  • isModal boolean property (true/false)
  • Modal overlay behavior and parent blocking
  • Modeless floating behavior
  • Focus management differences
  • When to choose each mode
  • Side-by-side comparisons
📄 阅读: references/modal-vs-modeless.md
  • isModal布尔属性(true/false)
  • 模态遮罩行为与父级阻塞
  • 非模态浮动行为
  • 焦点管理差异
  • 两种模式的适用场景
  • 对比说明

Positioning and Dragging

定位与拖拽

📄 Read: references/positioning-and-dragging.md
  • position object (X: 'center'|'left'|'right'|number, Y: 'top'|'center'|'bottom'|number)
  • 9 preset position combinations
  • Custom pixel-based positioning
  • allowDragging boolean property
  • enableResize and resizeHandles configuration
  • Target element constraints with target prop
📄 阅读: references/positioning-and-dragging.md
  • position对象(X: 'center'|'left'|'right'|数字, Y: 'top'|'center'|'bottom'|数字)
  • 9种预设位置组合
  • 基于像素的自定义定位
  • allowDragging布尔属性
  • enableResize与resizeHandles配置
  • 通过target属性约束目标元素

Templates and Content

模板与内容

📄 Read: references/templates-and-content.md
  • content property (string, HTML, JSX function)
  • header property (text or template)
  • footerTemplate (custom footer JSX)
  • Dynamic content updates
  • HTML sanitization (enableHtmlSanitizer)
  • Styling content and edge cases
📄 阅读: references/templates-and-content.md
  • content属性(字符串、HTML、JSX函数)
  • header属性(文本或模板)
  • footerTemplate(自定义页脚JSX)
  • 动态内容更新
  • HTML清理(enableHtmlSanitizer)
  • 内容样式与边缘情况处理

Buttons and Actions

按钮与操作

📄 Read: references/buttons-and-actions.md
  • buttons array with ButtonPropsModel[]
  • ButtonPropsModel structure (buttonModel, click, isFlat, type)
  • buttonModel properties (content, isPrimary, cssClass)
  • Click event handlers
  • Styling buttons with cssClass
  • Button types (Button, Submit, Reset)
📄 阅读: references/buttons-and-actions.md
  • buttons数组,包含ButtonPropsModel[]
  • ButtonPropsModel结构(buttonModel、click、isFlat、type)
  • buttonModel属性(content、isPrimary、cssClass)
  • 点击事件处理器
  • 使用cssClass设置按钮样式
  • 按钮类型(Button、Submit、Reset)

Animation Effects

动画效果

📄 Read: references/animation-effects.md
  • AnimationSettingsModel (effect, duration, delay)
  • 16 animation effects (Fade, FadeZoom, FlipLeftDown, FlipLeftUp, etc.)
  • Duration in milliseconds
  • Delay before animation starts
  • Disable animations (effect: 'None')
  • Performance considerations
📄 阅读: references/animation-effects.md
  • AnimationSettingsModel(effect、duration、delay)
  • 16种动画效果(Fade、FadeZoom、FlipLeftDown、FlipLeftUp等)
  • 动画时长(毫秒)
  • 动画延迟启动时间
  • 禁用动画(effect: 'None')
  • 性能考量

Localization and Accessibility

本地化与无障碍

📄 Read: references/localization-and-accessibility.md
  • locale property for culture/language
  • WCAG 2.2 compliance
  • Keyboard navigation (Tab, Enter, Escape)
  • closeOnEscape behavior control
  • ARIA roles and attributes
  • Screen reader support
  • RTL support with enableRtl
  • Focus management patterns
📄 阅读: references/localization-and-accessibility.md
  • locale属性设置文化/语言
  • 符合WCAG 2.2标准
  • 键盘导航(Tab、Enter、Escape)
  • closeOnEscape行为控制
  • ARIA角色与属性
  • 屏幕阅读器支持
  • enableRtl实现RTL渲染
  • 焦点管理模式

Advanced Patterns

高级模式

📄 Read: references/advanced-patterns.md
  • Events: open, close, beforeOpen, beforeClose, drag, dragStart, dragStop, resizeStart, resizeStop, resizing
  • Nested and stacked dialogs
  • Forms with validation
  • AJAX content loading
  • Prevent close logic (beforeClose event)
  • Full-screen dialogs
  • HTML sanitization and security
  • CSS classes and z-index management
  • Enable persistence (enablePersistence)
  • Common edge cases and troubleshooting
📄 阅读: references/advanced-patterns.md
  • 事件:open、close、beforeOpen、beforeClose、drag、dragStart、dragStop、resizeStart、resizeStop、resizing
  • 嵌套与堆叠对话框
  • 带验证的表单
  • AJAX内容加载
  • 阻止关闭逻辑(beforeClose事件)
  • 全屏对话框
  • HTML清理与安全
  • CSS类与z-index管理
  • 启用持久化(enablePersistence)
  • 常见边缘情况与故障排除

API Reference (Complete)

完整API参考

📄 Read: references/api-reference.md
  • All 24 DialogModel properties with types and defaults
  • All 11 events with event arguments
  • Methods: show(), hide(), refresh(), destroy()
  • ButtonPropsModel structure (buttonModel, click, isFlat, type)
  • AnimationSettingsModel with all 16 effects
  • Types and enumerations
  • Quick reference patterns
📄 阅读: references/api-reference.md
  • 全部24个DialogModel属性,包含类型与默认值
  • 全部11个事件与事件参数
  • 方法:show()、hide()、refresh()、destroy()
  • ButtonPropsModel结构(buttonModel、click、isFlat、type)
  • 包含全部16种效果的AnimationSettingsModel
  • 类型与枚举
  • 快速参考示例

Quick Start Example

快速开始示例

Basic Modal Dialog:
jsx
import React, { useRef, useState } from 'react';
import { DialogComponent } from '@syncfusion/ej2-react-popups';
import '@syncfusion/ej2-base/styles/material.css';
import '@syncfusion/ej2-buttons/styles/material.css';
import '@syncfusion/ej2-popups/styles/material.css';

export default function App() {
  const dialogRef = useRef(null);
  const [isOpen, setIsOpen] = useState(false);

  const handleOpen = () => {
    dialogRef.current?.show();
    setIsOpen(true);
  };

  const handleClose = () => {
    dialogRef.current?.hide();
    setIsOpen(false);
  };

  const buttons = [
    {
      buttonModel: {
        content: 'OK',
        cssClass: 'e-flat',
        isPrimary: true,
      },
      click: handleClose,
    },
    {
      buttonModel: {
        content: 'Cancel',
        cssClass: 'e-flat',
      },
      click: handleClose,
    },
  ];

  return (
    <div id="dialog-target" style={{ position: 'relative', width: '100%', minHeight: '400px' }}>
      <button onClick={handleOpen} className="e-control e-btn e-primary">
        Open Dialog
      </button>

      <DialogComponent
        ref={dialogRef}
        header="Confirm Action"
        buttons={buttons}
        showCloseIcon={true}
        target="#dialog-target"
        width="400px"
        isModal={true}
        visible={false}
      >
        <p>Are you sure you want to proceed with this action?</p>
      </DialogComponent>
    </div>
  );
}
基础模态对话框:
jsx
import React, { useRef, useState } from 'react';
import { DialogComponent } from '@syncfusion/ej2-react-popups';
import '@syncfusion/ej2-base/styles/material.css';
import '@syncfusion/ej2-buttons/styles/material.css';
import '@syncfusion/ej2-popups/styles/material.css';

export default function App() {
  const dialogRef = useRef(null);
  const [isOpen, setIsOpen] = useState(false);

  const handleOpen = () => {
    dialogRef.current?.show();
    setIsOpen(true);
  };

  const handleClose = () => {
    dialogRef.current?.hide();
    setIsOpen(false);
  };

  const buttons = [
    {
      buttonModel: {
        content: 'OK',
        cssClass: 'e-flat',
        isPrimary: true,
      },
      click: handleClose,
    },
    {
      buttonModel: {
        content: 'Cancel',
        cssClass: 'e-flat',
      },
      click: handleClose,
    },
  ];

  return (
    <div id="dialog-target" style={{ position: 'relative', width: '100%', minHeight: '400px' }}>
      <button onClick={handleOpen} className="e-control e-btn e-primary">
        Open Dialog
      </button>

      <DialogComponent
        ref={dialogRef}
        header="Confirm Action"
        buttons={buttons}
        showCloseIcon={true}
        target="#dialog-target"
        width="400px"
        isModal={true}
        visible={false}
      >
        <p>Are you sure you want to proceed with this action?</p>
      </DialogComponent>
    </div>
  );
}

Common Patterns

常见模式

Pattern 1: Confirmation Dialog

模式1:确认对话框

Delete action with confirmation buttons:
jsx
const buttons = [
  {
    buttonModel: { content: 'Delete', cssClass: 'e-flat e-danger', isPrimary: true },
    click: () => { performDelete(); dialogRef.current?.hide(); }
  },
  {
    buttonModel: { content: 'Cancel', cssClass: 'e-flat' },
    click: () => dialogRef.current?.hide()
  }
];
带确认按钮的删除操作:
jsx
const buttons = [
  {
    buttonModel: { content: 'Delete', cssClass: 'e-flat e-danger', isPrimary: true },
    click: () => { performDelete(); dialogRef.current?.hide(); }
  },
  {
    buttonModel: { content: 'Cancel', cssClass: 'e-flat' },
    click: () => dialogRef.current?.hide()
  }
];

Pattern 2: Form Dialog

模式2:表单对话框

Dialog with form inputs and validation:
jsx
<DialogComponent header="Edit Profile" buttons={buttons} isModal={true} width="500px">
  <div style={{ padding: '16px' }}>
    <input type="text" placeholder="Name" className="form-control" />
    <input type="email" placeholder="Email" className="form-control" />
    <textarea placeholder="Bio" className="form-control"></textarea>
  </div>
</DialogComponent>
带输入与验证的对话框:
jsx
<DialogComponent header="Edit Profile" buttons={buttons} isModal={true} width="500px">
  <div style={{ padding: '16px' }}>
    <input type="text" placeholder="Name" className="form-control" />
    <input type="email" placeholder="Email" className="form-control" />
    <textarea placeholder="Bio" className="form-control"></textarea>
  </div>
</DialogComponent>

Pattern 3: Centered Dialog

模式3:居中对话框

Position dialog in center of screen:
jsx
<DialogComponent
  header="Alert"
  position={{ X: 'center', Y: 'center' }}
  isModal={true}
  showCloseIcon={true}
  width="350px"
>
  This dialog is centered on the screen.
</DialogComponent>
屏幕居中的对话框:
jsx
<DialogComponent
  header="Alert"
  position={{ X: 'center', Y: 'center' }}
  isModal={true}
  showCloseIcon={true}
  width="350px"
>
  This dialog is centered on the screen.
</DialogComponent>

Pattern 4: Draggable Floating Panel

模式4:可拖拽浮动面板

Non-modal, draggable properties panel:
jsx
<DialogComponent
  header="Properties"
  isModal={false}
  allowDragging={true}
  position={{ X: 200, Y: 150 }}
  width="300px"
  enableResize={true}
  resizeHandles={['All']}
  showCloseIcon={true}
>
  Drag me around! I don't block the page.
</DialogComponent>
非模态、可拖拽的属性面板:
jsx
<DialogComponent
  header="Properties"
  isModal={false}
  allowDragging={true}
  position={{ X: 200, Y: 150 }}
  width="300px"
  enableResize={true}
  resizeHandles={['All']}
  showCloseIcon={true}
>
  Drag me around! I don't block the page.
</DialogComponent>

Pattern 5: Animated Dialog

模式5:带动画的对话框

Dialog with Zoom animation:
jsx
<DialogComponent
  header="Welcome"
  animationSettings={{ effect: 'Zoom', duration: 400, delay: 0 }}
  isModal={true}
  position={{ X: 'center', Y: 'center' }}
  width="400px"
>
  This dialog zooms in smoothly!
</DialogComponent>
带缩放动画的对话框:
jsx
<DialogComponent
  header="Welcome"
  animationSettings={{ effect: 'Zoom', duration: 400, delay: 0 }}
  isModal={true}
  position={{ X: 'center', Y: 'center' }}
  width="400px"
>
  This dialog zooms in smoothly!
</DialogComponent>

Pattern 6: Custom Footer Template

模式6:自定义页脚模板

Custom footer instead of buttons:
jsx
<DialogComponent
  header="Custom Footer"
  isModal={true}
  footerTemplate={
    <div style={{ padding: '12px', textAlign: 'right' }}>
      <button className="e-control e-btn e-primary" style={{ marginRight: '8px' }}>
        Save
      </button>
      <button className="e-control e-btn">Cancel</button>
    </div>
  }
>
  Dialog content with custom footer.
</DialogComponent>
使用自定义页脚替代默认按钮:
jsx
<DialogComponent
  header="Custom Footer"
  isModal={true}
  footerTemplate={
    <div style={{ padding: '12px', textAlign: 'right' }}>
      <button className="e-control e-btn e-primary" style={{ marginRight: '8px' }}>
        Save
      </button>
      <button className="e-control e-btn">Cancel</button>
    </div>
  }
>
  Dialog content with custom footer.
</DialogComponent>

Pattern 7: Nested Dialogs

模式7:嵌套对话框

Parent dialog containing child dialog:
jsx
const childDialogRef = useRef(null);

<DialogComponent header="Parent" isModal={true} width="400px">
  <button onClick={() => childDialogRef.current?.show()} className="e-control e-btn">
    Open Child Dialog
  </button>
  
  <DialogComponent
    ref={childDialogRef}
    header="Child"
    isModal={true}
    width="300px"
    visible={false}
  >
    Nested dialog content
  </DialogComponent>
</DialogComponent>
包含子对话框的父对话框:
jsx
const childDialogRef = useRef(null);

<DialogComponent header="Parent" isModal={true} width="400px">
  <button onClick={() => childDialogRef.current?.show()} className="e-control e-btn">
    Open Child Dialog
  </button>
  
  <DialogComponent
    ref={childDialogRef}
    header="Child"
    isModal={true}
    width="300px"
    visible={false}
  >
    Nested dialog content
  </DialogComponent>
</DialogComponent>

Key Props (DialogModel)

核心属性(DialogModel)

PropTypeDescriptionDefaultWhen to Use
isModal
booleanEnable modal mode (blocks parent interaction)falseConfirmations, alerts, critical actions
visible
booleanInitial visibility statefalseControl initial dialog display
header
string | JSXDialog header/title-Every dialog needs a title
content
string | HTML | JSXDialog body content-Main dialog information
buttons
ButtonPropsModel[]Action buttons in footer-For OK/Cancel, action confirmations
footerTemplate
JSXCustom footer content-When buttons prop doesn't fit
showCloseIcon
booleanShow close button in headerfalseAllow users to dismiss
position
PositionDataX/Y positioning (center, top, etc.){ X: 'center', Y: 'center' }Custom placement
allowDragging
booleanEnable drag functionalityfalseMovable dialogs, floating panels
enableResize
booleanEnable resize with gripfalseResizable dialogs
resizeHandles
ResizeDirections[]Which edges/corners resize['All']Control resize behavior
width
string | numberDialog width'330px'Control dialog size
height
string | numberDialog height'auto'Control dialog size
minHeight
string | numberMinimum height-Prevent too-small resize
animationSettings
AnimationSettingsModelAnimation effect/duration/delay-Smooth open/close transitions
closeOnEscape
booleanClose on Escape key presstrueKeyboard navigation
target
string (selector)Container elementdocument.bodyModal positioning
enableHtmlSanitizer
booleanSanitize HTML contenttrueSecurity (prevent XSS)
cssClass
stringCustom CSS classes-Styling and theming
enableRtl
booleanRight-to-left renderingfalseRTL languages
locale
stringCulture/language code'en-US'Localization
zIndex
numberStack order-Manage overlapping dialogs
enablePersistence
booleanPersist state on reloadfalseRemember size/position
属性类型描述默认值适用场景
isModal
boolean启用模态模式(阻塞父级交互)false确认操作、提示、关键操作
visible
boolean初始可见状态false控制对话框初始显示
header
string | JSX对话框标题-所有需要标题的对话框
content
string | HTML | JSX对话框主体内容-对话框核心信息展示
buttons
ButtonPropsModel[]页脚操作按钮-确定/取消、操作确认场景
footerTemplate
JSX自定义页脚内容-默认按钮属性无法满足需求时
showCloseIcon
boolean在标题栏显示关闭按钮false允许用户关闭对话框
position
PositionDataX/Y定位(居中、顶部等){ X: 'center', Y: 'center' }自定义布局位置
allowDragging
boolean启用拖拽功能false可移动对话框、浮动面板
enableResize
boolean启用调整大小手柄false可调整尺寸的对话框
resizeHandles
ResizeDirections[]可调整的边缘/角落['All']控制调整大小的行为
width
string | number对话框宽度'330px'控制对话框尺寸
height
string | number对话框高度'auto'控制对话框尺寸
minHeight
string | number最小高度-防止对话框尺寸过小
animationSettings
AnimationSettingsModel动画效果/时长/延迟-平滑的打开/关闭过渡
closeOnEscape
boolean按下Escape键时关闭对话框true键盘导航支持
target
string (选择器)容器元素document.body模态对话框定位
enableHtmlSanitizer
boolean清理HTML内容true安全防护(防止XSS)
cssClass
string自定义CSS类-样式与主题定制
enableRtl
boolean从右到左渲染false支持RTL语言
locale
string文化/语言代码'en-US'本地化支持
zIndex
number堆叠顺序-管理重叠对话框的层级
enablePersistence
boolean重载时保留状态false记住对话框尺寸/位置

Common Use Cases

常见使用场景

  1. Confirmation Dialogs - Confirm delete, submit, or critical actions before proceeding
  2. Alert/Info Popups - Display system messages, warnings, or notifications
  3. Form Dialogs - Edit profiles, settings, or create new records in modal forms
  4. Input Prompts - Collect user input for specific actions (e.g., "Enter file name")
  5. Properties Panels - Draggable, non-modal panels for settings or properties
  6. Multi-Step Workflows - Nested dialogs for step-by-step processes
  7. Loading/Processing - Show progress indicators or loading states
  8. Help/Documentation - Contextual help, tips, or tutorial overlays
  9. Image Galleries - Lightbox dialogs for images or media previews
  10. Settings/Preferences - Organize application settings in tabbed dialogs

Next: Choose a reference based on what you need to implement. All references include working code examples, best practices, and troubleshooting guidance.
  1. 确认对话框 - 在执行删除、提交或关键操作前进行确认
  2. 提示/信息弹窗 - 显示系统消息、警告或通知
  3. 表单对话框 - 在模态表单中编辑个人资料、设置或创建新记录
  4. 输入提示 - 收集用户特定操作的输入(如“输入文件名”)
  5. 属性面板 - 可拖拽的非模态设置或属性面板
  6. 多步骤流程 - 使用嵌套对话框实现分步流程
  7. 加载/处理中 - 显示进度指示器或加载状态
  8. 帮助/文档 - 上下文帮助、提示或教程覆盖层
  9. 图片画廊 - 用于图片或媒体预览的灯箱对话框
  10. 设置/偏好 - 在标签式对话框中组织应用设置

下一步: 根据需要实现的功能选择对应的参考文档。所有参考文档均包含可运行的代码示例、最佳实践和故障排除指南。