syncfusion-react-dialog

实现 React Dialog

DialogComponent 可在浮动窗口中显示内容，并支持模态和非模态模式、自定义定位、拖动、调整大小、动画、模板以及全面的无障碍功能。

组件概览

DialogComponent 功能：

• 模态/非模态模式：控制是否阻止与父级的交互
• 9 种预设位置 + 自定义 X/Y：灵活定位
• 拖动：基于标题栏的拖放（allowDragging）
• 调整大小：对角线调整大小控点（enableResize）
• 模板：自定义标题栏、内容和页脚
• 动画：16 种效果（Fade、Zoom、Flip、Slide、FadeZoom 等）
• 按钮：内置操作按钮及点击处理程序
• 事件：open、close、beforeOpen、beforeClose、drag、dragStart、dragStop、resize 事件
• 键盘导航：Tab、Escape（closeOnEscape）、Enter
• WCAG 2.2 无障碍功能：ARIA 角色、焦点管理
• 本地化：通过 locale 属性支持 20 多种语言环境
• RTL 支持：从右向左渲染

文档与导航指南

入门指南

📄 阅读： references/getting-started.md

• 安装（@syncfusion/ej2-react-popups）
• CSS/主题导入（material、bootstrap、tailwind）
• DialogComponent 的基本 JSX 结构
• show()/hide() 方法和 refs
• 使用 hooks 的函数组件模式
• 使用 visible 属性设置初始可见性

模态与非模态

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

• isModal 布尔属性（true/false）
• 模态遮罩行为和阻止与父级交互
• 非模态浮动行为
• 焦点管理差异
• 如何选择模式
• 并排比较

定位与拖动

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

• position 对象（X：'center'|'left'|'right'|number，Y：'top'|'center'|'bottom'|number）
• 9 种预设位置组合
• 基于像素的自定义定位
• allowDragging 布尔属性
• enableResize 和 resizeHandles 配置
• 使用 target 属性限制目标元素

模板与内容

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

• content 属性（字符串、HTML、JSX 函数）
• header 属性（文本或模板）
• footerTemplate（自定义页脚 JSX）
• 动态内容更新
• HTML 清理（enableHtmlSanitizer）
• 内容样式设置和边缘情况

按钮与操作

📄 阅读： references/buttons-and-actions.md

• 包含 ButtonPropsModel[] 的 buttons 数组
• ButtonPropsModel 结构（buttonModel、click、isFlat、type）
• buttonModel 属性（content、isPrimary、cssClass）
• 点击事件处理程序
• 使用 cssClass 设置按钮样式
• 按钮类型（Button、Submit、Reset）

动画效果

📄 阅读： references/animation-effects.md

• AnimationSettingsModel（effect、duration、delay）
• 16 种动画效果（Fade、FadeZoom、FlipLeftDown、FlipLeftUp 等）
• 以毫秒为单位的持续时间
• 动画开始前的延迟
• 禁用动画（effect: 'None'）
• 性能注意事项

本地化与无障碍功能

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

• 用于设置区域/语言的 locale 属性
• 符合 WCAG 2.2 标准
• 键盘导航（Tab、Enter、Escape）
• closeOnEscape 行为控制
• ARIA 角色和属性
• 屏幕阅读器支持
• 使用 enableRtl 支持 RTL
• 焦点管理模式

高级模式

📄 阅读： references/advanced-patterns.md

• 事件：open、close、beforeOpen、beforeClose、drag、dragStart、dragStop、resizeStart、resizeStop、resizing
• 嵌套和堆叠对话框
• 带验证的表单
• AJAX 内容加载
• 防止关闭逻辑（beforeClose 事件）
• 全屏对话框
• HTML 清理和安全性
• CSS 类和 z-index 管理
• 启用持久化（enablePersistence）
• 常见边缘情况和故障排除

API 参考（完整）

📄 阅读： references/api-reference.md

• 全部 24 个 DialogModel 属性及其类型和默认值
• 全部 11 个事件及其事件参数
• 方法：show()、hide()、refresh()、destroy()
• ButtonPropsModel 结构（buttonModel、click、isFlat、type）
• 包含全部 16 种效果的 AnimationSettingsModel
• 类型和枚举
• 快速参考模式

快速入门示例

基本模态对话框：

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>
  );
}

常见模式

模式 1：确认对话框

带确认按钮的删除操作：

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()
  }
];

模式 2：表单对话框

带表单输入和验证的对话框：

<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>

模式 3：居中对话框

将对话框放在屏幕中央：

<DialogComponent
  header="Alert"
  position={{ X: 'center', Y: 'center' }}
  isModal={true}
  showCloseIcon={true}
  width="350px"
>
  This dialog is centered on the screen.
</DialogComponent>

模式 4：可拖动浮动面板

非模态、可拖动的属性面板：

<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>

模式 5：动画对话框

带 Zoom 动画的对话框：

<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>

模式 6：自定义页脚模板

使用自定义页脚代替按钮：

<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>

模式 7：嵌套对话框

父对话框包含子对话框：

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>

关键属性（DialogModel）

属性	类型	描述	默认值	使用场景
isModal	boolean	启用模态模式（阻止与父级交互）	false	确认、警告、关键操作
visible	boolean	初始可见状态	false	控制对话框的初始显示状态
header	string | JSX	对话框页眉/标题	-	每个对话框都需要标题
content	string | HTML | JSX	对话框主体内容	-	对话框的主要信息
buttons	ButtonPropsModel[]	页脚中的操作按钮	-	用于确定/取消和操作确认
footerTemplate	JSX	自定义页脚内容	-	不适合使用 buttons 属性时
showCloseIcon	boolean	在页眉中显示关闭按钮	false	允许用户关闭对话框
position	PositionData	X/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 (selector)	容器元素	document.body	模态对话框定位
enableHtmlSanitizer	boolean	清理 HTML 内容	true	安全性（防止 XSS）
cssClass	string	自定义 CSS 类	-	样式和主题
enableRtl	boolean	启用从右向左渲染	false	从右向左书写的语言
locale	string	区域设置/语言代码	'en-US'	本地化
zIndex	number	堆叠顺序	-	管理重叠的对话框
enablePersistence	boolean	重新加载时保留状态	false	记住大小/位置

常见用例

1. 确认对话框 - 执行删除、提交或其他关键操作前进行确认
2. 警报/信息弹窗 - 显示系统消息、警告或通知
3. 表单对话框 - 在模态表单中编辑个人资料、设置或创建新记录
4. 输入提示 - 收集用户执行特定操作所需的输入（例如，“输入文件名”）
5. 属性面板 - 可拖动的非模态面板，用于设置或属性
6. 多步骤工作流 - 使用嵌套对话框实现分步流程
7. 加载/处理中 - 显示进度指示器或加载状态
8. 帮助/文档 - 提供上下文相关的帮助、提示或教程叠加层
9. 图片库 - 使用灯箱对话框预览图片或媒体
10. 设置/偏好设置 - 在带标签页的对话框中整理应用设置

---

下一步： 根据要实现的功能选择参考内容。所有参考内容都包含可运行的代码示例、最佳实践和故障排查指南。