syncfusion-react-dialog
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseImplementing 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)
| Prop | Type | Description | Default | When to Use |
|---|---|---|---|---|
| boolean | Enable modal mode (blocks parent interaction) | false | Confirmations, alerts, critical actions |
| boolean | Initial visibility state | false | Control initial dialog display |
| string | JSX | Dialog header/title | - | Every dialog needs a title |
| string | HTML | JSX | Dialog body content | - | Main dialog information |
| ButtonPropsModel[] | Action buttons in footer | - | For OK/Cancel, action confirmations |
| JSX | Custom footer content | - | When buttons prop doesn't fit |
| boolean | Show close button in header | false | Allow users to dismiss |
| PositionData | X/Y positioning (center, top, etc.) | { X: 'center', Y: 'center' } | Custom placement |
| boolean | Enable drag functionality | false | Movable dialogs, floating panels |
| boolean | Enable resize with grip | false | Resizable dialogs |
| ResizeDirections[] | Which edges/corners resize | ['All'] | Control resize behavior |
| string | number | Dialog width | '330px' | Control dialog size |
| string | number | Dialog height | 'auto' | Control dialog size |
| string | number | Minimum height | - | Prevent too-small resize |
| AnimationSettingsModel | Animation effect/duration/delay | - | Smooth open/close transitions |
| boolean | Close on Escape key press | true | Keyboard navigation |
| string (selector) | Container element | document.body | Modal positioning |
| boolean | Sanitize HTML content | true | Security (prevent XSS) |
| string | Custom CSS classes | - | Styling and theming |
| boolean | Right-to-left rendering | false | RTL languages |
| string | Culture/language code | 'en-US' | Localization |
| number | Stack order | - | Manage overlapping dialogs |
| boolean | Persist state on reload | false | Remember size/position |
| 属性 | 类型 | 描述 | 默认值 | 适用场景 |
|---|---|---|---|---|
| boolean | 启用模态模式(阻塞父级交互) | false | 确认操作、提示、关键操作 |
| boolean | 初始可见状态 | false | 控制对话框初始显示 |
| string | JSX | 对话框标题 | - | 所有需要标题的对话框 |
| string | HTML | JSX | 对话框主体内容 | - | 对话框核心信息展示 |
| ButtonPropsModel[] | 页脚操作按钮 | - | 确定/取消、操作确认场景 |
| JSX | 自定义页脚内容 | - | 默认按钮属性无法满足需求时 |
| boolean | 在标题栏显示关闭按钮 | false | 允许用户关闭对话框 |
| PositionData | X/Y定位(居中、顶部等) | { X: 'center', Y: 'center' } | 自定义布局位置 |
| boolean | 启用拖拽功能 | false | 可移动对话框、浮动面板 |
| boolean | 启用调整大小手柄 | false | 可调整尺寸的对话框 |
| ResizeDirections[] | 可调整的边缘/角落 | ['All'] | 控制调整大小的行为 |
| string | number | 对话框宽度 | '330px' | 控制对话框尺寸 |
| string | number | 对话框高度 | 'auto' | 控制对话框尺寸 |
| string | number | 最小高度 | - | 防止对话框尺寸过小 |
| AnimationSettingsModel | 动画效果/时长/延迟 | - | 平滑的打开/关闭过渡 |
| boolean | 按下Escape键时关闭对话框 | true | 键盘导航支持 |
| string (选择器) | 容器元素 | document.body | 模态对话框定位 |
| boolean | 清理HTML内容 | true | 安全防护(防止XSS) |
| string | 自定义CSS类 | - | 样式与主题定制 |
| boolean | 从右到左渲染 | false | 支持RTL语言 |
| string | 文化/语言代码 | 'en-US' | 本地化支持 |
| number | 堆叠顺序 | - | 管理重叠对话框的层级 |
| boolean | 重载时保留状态 | false | 记住对话框尺寸/位置 |
Common Use Cases
常见使用场景
- Confirmation Dialogs - Confirm delete, submit, or critical actions before proceeding
- Alert/Info Popups - Display system messages, warnings, or notifications
- Form Dialogs - Edit profiles, settings, or create new records in modal forms
- Input Prompts - Collect user input for specific actions (e.g., "Enter file name")
- Properties Panels - Draggable, non-modal panels for settings or properties
- Multi-Step Workflows - Nested dialogs for step-by-step processes
- Loading/Processing - Show progress indicators or loading states
- Help/Documentation - Contextual help, tips, or tutorial overlays
- Image Galleries - Lightbox dialogs for images or media previews
- 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.
- 确认对话框 - 在执行删除、提交或关键操作前进行确认
- 提示/信息弹窗 - 显示系统消息、警告或通知
- 表单对话框 - 在模态表单中编辑个人资料、设置或创建新记录
- 输入提示 - 收集用户特定操作的输入(如“输入文件名”)
- 属性面板 - 可拖拽的非模态设置或属性面板
- 多步骤流程 - 使用嵌套对话框实现分步流程
- 加载/处理中 - 显示进度指示器或加载状态
- 帮助/文档 - 上下文帮助、提示或教程覆盖层
- 图片画廊 - 用于图片或媒体预览的灯箱对话框
- 设置/偏好 - 在标签式对话框中组织应用设置
下一步: 根据需要实现的功能选择对应的参考文档。所有参考文档均包含可运行的代码示例、最佳实践和故障排除指南。