syncfusion-react-popups

Syncfusion React 弹出窗口组件

实现 Syncfusion React 对话框组件

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）
• AnimationSettingsModel 及其全部 16 种效果
• 类型和枚举
• 快速参考模式

快速入门示例

⚠️ 依赖项版本对齐： 所有 @syncfusion/ej2-* 软件包必须使用相同的主版本，以避免 peer-dependency 冲突和供应链不匹配。请一起安装：

npm install @syncfusion/ej2-react-popups @syncfusion/ej2-base @syncfusion/ej2-buttons @syncfusion/ej2-popups

基本模态对话框：

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：带动画的对话框

带缩放动画的对话框：

<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	RTL 语言
locale	string	区域设置/语言代码	'en-US'	本地化
zIndex	number	堆叠顺序	-	管理重叠的对话框
enablePersistence	boolean	重新加载时保留状态	false	记住尺寸/位置

常见使用场景

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

---

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

实现 Syncfusion React 预定义对话框组件

目录

• 关键概念
• 快速开始
• 文档指南
• 常见模式

关键概念

Syncfusion 预定义对话框不是基于组件的（<ejs-dialog>）。它们通过 DialogUtility 工具类以命令式方式打开：

对话框类型	方法
警告	DialogUtility.alert({ ... })
确认	DialogUtility.confirm({ ... })
提示（输入）	DialogUtility.confirm({ content: '<input .../>', ... })

导入： import { DialogUtility } from '@syncfusion/ej2-react-popups';

---

快速开始

import { ButtonComponent } from '@syncfusion/ej2-react-buttons';
import { DialogUtility } from '@syncfusion/ej2-react-popups';
import * as React from 'react';

function App() {
  function showAlert() {
    DialogUtility.alert({
      title: 'Low Battery',
      width: '250px',
      content: '10% of battery remaining',
    });
  }
  return <ButtonComponent cssClass="e-danger" onClick={showAlert}>Alert</ButtonComponent>;
}
export default App;

---

文档指南

入门

📄 阅读： references/getting-started.md

• 安装（@syncfusion/ej2-react-popups）
• CSS 导入
• Alert、Confirm 和 Prompt 的最简示例
• 函数组件和类组件模式

动画

📄 阅读： references/animation.md

• animationSettings 属性，包含 effect、duration、delay
• Alert / Confirm / Prompt 动画示例

可拖动

📄 阅读： references/draggable.md

• isDraggable 布尔属性
• Alert / Confirm / Prompt 拖动示例

位置

📄 阅读： references/position.md

• position 属性：{ X, Y } — left|center|right / top|center|bottom 或数值偏移
• Alert / Confirm / Prompt 位置示例

尺寸

📄 阅读： references/dimension.md

• width 和 height 属性
• 使用 cssClass 设置最大宽度 / 最小宽度限制
• Alert / Confirm / Prompt 尺寸示例

自定义

📄 阅读： references/customization.md

• okButton / cancelButton — 自定义 text、icon、click 处理程序
• showCloseIcon 和 closeOnEscape
• 为 Prompt 对话框自定义 content

API 参考

📄 阅读： references/api.md

• DialogUtility.alert() / confirm() 的完整选项属性
• 所有支持的字段：title、content、width、height、position、animationSettings、isDraggable、okButton、cancelButton、showCloseIcon、closeOnEscape、cssClass

---

常见模式

带 OK 回调的 Alert：

const dialogObj = DialogUtility.alert({
  title: 'Info',
  content: 'Operation complete.',
  okButton: { click: () => { dialogObj.hide(); } }
});

带 Yes / No 选项的 Confirm：

const dialogObj = DialogUtility.confirm({
  title: 'Delete?',
  content: 'Are you sure?',
  width: '300px',
  okButton: { text: 'Yes', click: () => { dialogObj.hide(); /* do delete */ } },
  cancelButton: { text: 'No', click: () => { dialogObj.hide(); } }
});

Prompt（捕获输入）：

const dialogObj = DialogUtility.confirm({
  title: 'Enter Name',
  content: '<p>Your name:</p><input id="nameInput" class="e-input" placeholder="Type here..." />',
  width: '300px',
  okButton: {
    text: 'Submit',
    click: () => {
      const val = (document.getElementById('nameInput') as HTMLInputElement).value;
      dialogObj.hide();
    }
  },
  cancelButton: { click: () => dialogObj.hide() }
});

实现 Syncfusion React Tooltip

一项全面的技能，介绍如何实现 Syncfusion React TooltipComponent，涵盖设置、内容策略、定位、打开模式、动画、自定义、无障碍访问和高级操作模式。

包： @syncfusion/ej2-react-popups
导入： import { TooltipComponent } from '@syncfusion/ej2-react-popups';

快速开始

npm install @syncfusion/ej2-react-popups --save

/* src/App.css */
@import "../node_modules/@syncfusion/ej2-base/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-react-popups/styles/tailwind3.css";

import * as React from 'react';
import { TooltipComponent } from '@syncfusion/ej2-react-popups';
import './App.css';

function App() {
  return (
    <TooltipComponent content="Tooltip Content" position="TopCenter">
      <button className="e-btn">Show Tooltip</button>
    </TooltipComponent>
  );
}
export default App;

导航指南

入门与设置

📄 阅读： references/getting-started.md

• 安装和 CSS 导入
• 在单个元素上显示基本工具提示
• 在容器内的多个目标上显示工具提示（target 属性）
• 使用 title 属性作为备用内容
• 运行应用程序

内容

📄 阅读： references/content.md

• 纯字符串内容
• 模板内容（JSX 函数）
• 通过 Fetch/Ajax 加载动态内容（beforeRender 事件）
• HTML 内容（iframe、嵌入元素）
• 使用 dataBind() 以编程方式更新内容

定位

📄 阅读： references/position.md

• 12 个静态位置（TopLeft、TopCenter、TopRight、BottomLeft、BottomCenter、BottomRight、LeftTop、LeftCenter、LeftBottom、RightTop、RightCenter、RightBottom）
• 显示 / 隐藏尖角指示器（showTipPointer）及其定位（tipPointerPosition：Auto、Start、Middle、End）
• 使用 refresh() 方法动态定位（可拖动目标）
• 鼠标跟随（mouseTrail）
• 偏移值（offsetX、offsetY）
• 碰撞处理（自动翻转行为、windowCollision）

打开模式

📄 阅读： references/open-mode.md

• 通过 opensOn 设置 Auto、Hover、Click、Focus、Custom 模式
• 组合多种模式（opensOn="Hover Click"）
• 粘滞模式（isSticky）— 显示关闭按钮
• 打开 / 关闭延迟（openDelay、closeDelay）
• 使用 open() 和 close() 方法设置自定义打开模式
• 移动设备行为（轻触并按住）

动画

📄 阅读： references/animation.md

• animation 属性（打开/关闭 AnimationModel）
• 全部 15 种可用动画效果（FadeIn、ZoomIn、FlipX/Y 等）
• 自定义持续时间和延迟
• 通过 open() 和 close() 方法以编程方式播放动画
• 使用 beforeRender + CSS transitions 实现过渡效果

自定义

📄 阅读： references/customization.md

• 使用 cssClass 设置自定义主题和样式
• 自定义提示箭头的大小、背景和边框
• 自定义工具提示的整体外观（背景、透明度、字体）
• 曲线提示箭头和气泡提示箭头样式
• 尺寸控制（width、height）和滚动模式
• RTL 支持（enableRtl）

实用模式

📄 阅读： references/how-to.md

• 在多个目标上显示工具提示（每个目标使用动态内容）
• 在禁用的元素上显示工具提示
• 使用 destroy() 和 render() 启用/禁用工具提示
• 在 SVG 和 Canvas 元素上显示工具提示
• 在工具提示内容中嵌入 iframe 或 HTML 元素
• 自定义打开方式（双击、右键单击）

无障碍

📄 阅读： references/accessibility.md

• 符合 WCAG 2.2 和 Section 508 标准
• WAI-ARIA 属性（role="tooltip"、aria-describedby、aria-hidden）
• 键盘快捷键（Escape、Tab）
• 屏幕阅读器行为

API 参考

📄 阅读： references/api.md

• 所有属性、方法和事件的类型及默认值
• TooltipAnimationSettings、TooltipEventArgs 类型
• Position 和 TipPointerPosition 枚举值

常见模式

按钮上的工具提示

<TooltipComponent content="Submit the form" position="TopCenter">
  <button className="e-btn e-primary">Submit</button>
</TooltipComponent>

容器中的多目标工具提示

// Single TooltipComponent handles all .e-info targets; 
// each uses its own `title` attribute as content
<TooltipComponent target=".e-info" position="RightCenter">
  <form>
    <input className="e-info" type="text" title="Enter your name" />
    <input className="e-info" type="email" title="Enter a valid email" />
  </form>
</TooltipComponent>

单击触发的固定工具提示

<TooltipComponent
  content="Click the × to close me"
  opensOn="Click"
  isSticky={true}
  position="BottomCenter"
>
  <button className="e-btn">Click Me</button>
</TooltipComponent>

以编程方式打开/关闭

import * as React from 'react';
import { TooltipComponent } from '@syncfusion/ej2-react-popups';

function App() {
  let tooltipRef: TooltipComponent;
  const target = React.useRef<HTMLButtonElement>(null);

  return (
    <TooltipComponent
      ref={t => (tooltipRef = t)}
      content="Tooltip opened programmatically"
      opensOn="Custom"
    >
      <button
        ref={target}
        className="e-btn"
        onClick={() => {
          if (target.current.getAttribute('data-tooltip-id')) {
            tooltipRef.close();
          } else {
            tooltipRef.open(target.current);
          }
        }}
      >
        Toggle Tooltip
      </button>
    </TooltipComponent>
  );
}

随鼠标移动的工具提示

<TooltipComponent
  content="Following your mouse!"
  mouseTrail={true}
  showTipPointer={false}
>
  <div style={{ width: '200px', height: '100px', background: '#eee' }}>
    Hover over me
  </div>
</TooltipComponent>

主要属性一览

属性	类型	默认值	用途
content	string | HTMLElement | Function	—	工具提示文本、HTML 或 JSX 模板
target	string	—	多目标模式的 CSS 选择器
position	Position	'TopCenter'	12 种定位值
opensOn	string	'Auto'	悬停 / 单击 / 聚焦 / 自定义
isSticky	boolean	false	保持显示，直到用户将其关闭
mouseTrail	boolean	false	跟随鼠标光标
showTipPointer	boolean	true	显示/隐藏箭头
tipPointerPosition	TipPointerPosition	'Auto'	自动 / 起始 / 中间 / 末尾
openDelay	number	0	打开前的延迟（毫秒）
closeDelay	number	0	关闭前的延迟（毫秒）
offsetX / offsetY	number	0	与目标的距离（像素）
width / height	string | number	'auto'	工具提示尺寸
cssClass	string	null	自定义 CSS 类
animation	AnimationModel	FadeIn/FadeOut 150ms	打开/关闭动画
enableRtl	boolean	false	从右向左渲染
enableHtmlSanitizer	boolean	true	清理 HTML 内容
container	string | HTMLElement	body	弹出层的挂载目标
windowCollision	boolean	false	与视口进行碰撞检测