Back to Details

syncfusion-react-popups

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Syncfusion React Popups Component

Syncfusion React 弹窗组件

Implementing Syncfusion React Dialog Component

实现 Syncfusion React Dialog 组件

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

快速入门示例

⚠️ Dependency Alignment: All 
@syncfusion/ej2-*
packages must be on the same major version to avoid peer-dependency conflicts and supply-chain mismatches. Install them together:
npm install @syncfusion/ej2-react-popups @syncfusion/ej2-base @syncfusion/ej2-buttons @syncfusion/ej2-popups
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>
  );
}
⚠️ 依赖版本对齐： 所有
@syncfusion/ej2-*
包必须使用相同大版本，以避免peer依赖冲突和供应链不匹配。请一起安装：
npm install @syncfusion/ej2-react-popups @syncfusion/ej2-base @syncfusion/ej2-buttons @syncfusion/ej2-popups
基础模态对话框：
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[]页脚操作按钮-OK/Cancel按钮、操作确认
footerTemplate
JSX自定义页脚内容-默认按钮属性无法满足需求时
showCloseIcon
boolean在标题栏显示关闭按钮false允许用户关闭对话框
position
PositionDataX/Y定位（center、top等）{ 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从右到左渲染falseRTL语言环境
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. 设置/偏好 - 在标签式对话框中组织应用设置
下一步： 根据需要实现的功能选择对应的参考文档。所有参考文档均包含可运行的代码示例、最佳实践和故障排除指南。

Implementing Syncfusion React Predefined Dialog Component

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

Table of Contents

目录

Key Concept

核心概念

Syncfusion Predefined Dialogs are not component-based (
<ejs-dialog>
). They are opened imperatively via the 
DialogUtility
 utility class:
Dialog TypeMethod
Alert
DialogUtility.alert({ ... })
Confirm
DialogUtility.confirm({ ... })
Prompt (input)
DialogUtility.confirm({ content: '<input .../>', ... })
Import: 
import { DialogUtility } from '@syncfusion/ej2-react-popups';
Syncfusion 预定义对话框不是基于组件的（
<ejs-dialog>
）。它们通过**
DialogUtility
**工具类以命令式方式打开：
对话框类型方法
警告框
DialogUtility.alert({ ... })
确认框
DialogUtility.confirm({ ... })
提示框（输入）
DialogUtility.confirm({ content: '<input .../>', ... })
导入： 
import { DialogUtility } from '@syncfusion/ej2-react-popups';

Quick Start

快速入门

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

Documentation Guide

文档指南

Getting Started

快速入门

📄 Read: references/getting-started.md
  • Installation (
    @syncfusion/ej2-react-popups
    )
  • CSS imports
  • Alert, Confirm, and Prompt minimal examples
  • Functional and class component patterns
📄 阅读： references/getting-started.md
  • 安装（
    @syncfusion/ej2-react-popups
    ）
  • CSS导入
  • 警告框、确认框、提示框的最简示例
  • 函数组件与类组件模式

Animation

动画

📄 Read: references/animation.md
  • animationSettings
    property with 
    effect
    , 
    duration
    , 
    delay
  • Alert / Confirm / Prompt animation examples
📄 阅读： references/animation.md
  • animationSettings
    属性，包含
    effect
    、
    duration
    、
    delay
  • 警告框/确认框/提示框的动画示例

Draggable

可拖动

📄 Read: references/draggable.md
  • isDraggable
    boolean property
  • Alert / Confirm / Prompt drag examples
📄 阅读： references/draggable.md
  • isDraggable
    布尔属性
  • 警告框/确认框/提示框的拖动示例

Position

定位

📄 Read: references/position.md
  • position
    property: 
    { X, Y }
    — 
    left|center|right
    / 
    top|center|bottom
    or numeric offset
  • Alert / Confirm / Prompt position examples
📄 阅读： references/position.md
  • position
    属性：
    { X, Y }
    — 
    left|center|right
    / 
    top|center|bottom
    或数值偏移
  • 警告框/确认框/提示框的定位示例

Dimension

尺寸

📄 Read: references/dimension.md
  • width
    and 
    height
    properties
  • cssClass
    for max-width / min-width constraints
  • Alert / Confirm / Prompt dimension examples
📄 阅读： references/dimension.md
  • width
    与
    height
    属性
  • 使用
    cssClass
    设置最大宽度/最小宽度约束
  • 警告框/确认框/提示框的尺寸示例

Customization

自定义

📄 Read: references/customization.md
  • okButton
    / 
    cancelButton
    — custom 
    text
    , 
    icon
    , 
    click
    handler
  • showCloseIcon
    and 
    closeOnEscape
  • Custom 
    content
    for prompt dialogs
📄 阅读： references/customization.md
  • okButton
    / 
    cancelButton
    — 自定义
    text
    、
    icon
    、
    click
    处理函数
  • showCloseIcon
    与
    closeOnEscape
  • 提示框的自定义
    content

API Reference

API参考

📄 Read: references/api.md
  • Full 
    DialogUtility.alert()
    / 
    confirm()
    option properties
  • All supported fields: 
    title
    , 
    content
    , 
    width
    , 
    height
    , 
    position
    , 
    animationSettings
    , 
    isDraggable
    , 
    okButton
    , 
    cancelButton
    , 
    showCloseIcon
    , 
    closeOnEscape
    , 
    cssClass
📄 阅读： references/api.md
  • DialogUtility.alert()
    / 
    confirm()
    的完整配置属性
  • 所有支持字段：
    title
    、
    content
    、
    width
    、
    height
    、
    position
    、
    animationSettings
    、
    isDraggable
    、
    okButton
    、
    cancelButton
    、
    showCloseIcon
    、
    closeOnEscape
    、
    cssClass

Common Patterns

常见模式

Alert with OK callback:
tsx
const dialogObj = DialogUtility.alert({
  title: 'Info',
  content: 'Operation complete.',
  okButton: { click: () => { dialogObj.hide(); } }
});
Confirm with Yes / No:
tsx
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 (input capture):
tsx
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() }
});
带OK回调的警告框：
tsx
const dialogObj = DialogUtility.alert({
  title: 'Info',
  content: 'Operation complete.',
  okButton: { click: () => { dialogObj.hide(); } }
});
带Yes/No的确认框：
tsx
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(); } }
});
提示框（捕获输入）：
tsx
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() }
});

Implementing Syncfusion React Tooltip

实现 Syncfusion React Tooltip

A comprehensive skill for implementing the Syncfusion React 
TooltipComponent
— covering setup, content strategies, positioning, open modes, animation, customization, accessibility, and advanced how-to patterns.
Package: 
@syncfusion/ej2-react-popups

Import: 
import { TooltipComponent } from '@syncfusion/ej2-react-popups';
本指南全面介绍如何实现Syncfusion React 
TooltipComponent
— 涵盖设置、内容策略、定位、触发模式、动画、自定义、无障碍支持以及高级实现模式。
包： 
@syncfusion/ej2-react-popups

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

Quick Start

快速入门

bash
npm install @syncfusion/ej2-react-popups --save
css
/* src/App.css */
@import "../node_modules/@syncfusion/ej2-base/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-react-popups/styles/tailwind3.css";
tsx
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;
bash
npm install @syncfusion/ej2-react-popups --save
css
/* src/App.css */
@import "../node_modules/@syncfusion/ej2-base/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-react-popups/styles/tailwind3.css";
tsx
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;

Navigation Guide

导航指南

Getting Started & Setup

快速入门与设置

📄 Read: references/getting-started.md
  • Installation and CSS imports
  • Basic tooltip on a single element
  • Tooltip on multiple targets within a container (
    target
    prop)
  • Using 
    title
    attribute as fallback content
  • Running the application
📄 阅读： references/getting-started.md
  • 安装与CSS导入
  • 单个元素上的基础工具提示
  • 容器内多个目标元素的工具提示（
    target
    属性）
  • 使用
    title
    属性作为备用内容
  • 运行应用

Content

内容

📄 Read: references/content.md
  • Plain string content
  • Template content (JSX function)
  • Dynamic content loaded via Fetch/Ajax (
    beforeRender
    event)
  • HTML content (iframe, embedded elements)
  • Updating content programmatically with 
    dataBind()
📄 阅读： references/content.md
  • 纯文本内容
  • 模板内容（JSX函数）
  • 通过Fetch/Ajax加载动态内容（
    beforeRender
    事件）
  • HTML内容（iframe、嵌入元素）
  • 使用
    dataBind()
    以编程方式更新内容

Positioning

定位

📄 Read: references/position.md
  • 12 static positions (
    TopLeft
    , 
    TopCenter
    , 
    TopRight
    , 
    BottomLeft
    , 
    BottomCenter
    , 
    BottomRight
    , 
    LeftTop
    , 
    LeftCenter
    , 
    LeftBottom
    , 
    RightTop
    , 
    RightCenter
    , 
    RightBottom
    )
  • Tip pointer show/hide (
    showTipPointer
    ) and positioning (
    tipPointerPosition
    : Auto, Start, Middle, End)
  • Dynamic positioning with 
    refresh()
    method (draggable targets)
  • Mouse trailing (
    mouseTrail
    )
  • Offset values (
    offsetX
    , 
    offsetY
    )
  • Collision handling (auto-flip behavior, 
    windowCollision
    )
📄 阅读： 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
    ）

Open Modes

触发模式

📄 Read: references/open-mode.md
  • Auto
    , 
    Hover
    , 
    Click
    , 
    Focus
    , 
    Custom
    modes via 
    opensOn
  • Combining multiple modes (
    opensOn="Hover Click"
    )
  • Sticky mode (
    isSticky
    ) — close button appears
  • Open/close delay (
    openDelay
    , 
    closeDelay
    )
  • Custom open mode with 
    open()
    and 
    close()
    methods
  • Mobile behavior (tap-and-hold)
📄 阅读： references/open-mode.md
  • 通过
    opensOn
    属性设置
    Auto
    、
    Hover
    、
    Click
    、
    Focus
    、
    Custom
    模式
  • 组合多种模式（
    opensOn="Hover Click"
    ）
  • 粘性模式（
    isSticky
    ）— 显示关闭按钮
  • 打开/关闭延迟（
    openDelay
    、
    closeDelay
    ）
  • 使用
    open()
    与
    close()
    方法实现自定义触发模式
  • 移动端行为（长按触发）

Animation

动画

📄 Read: references/animation.md
  • animation
    property (open/close 
    AnimationModel
    )
  • All 15 available animation effects (FadeIn, ZoomIn, FlipX/Y, etc.)
  • Custom duration and delay
  • Animating via 
    open()
    and 
    close()
    methods programmatically
  • Transition effect using 
    beforeRender
    + CSS transitions
📄 阅读： references/animation.md
  • animation
    属性（打开/关闭
    AnimationModel
    ）
  • 所有15种可用动画效果（FadeIn、ZoomIn、FlipX/Y等）
  • 自定义时长与延迟
  • 通过
    open()
    与
    close()
    方法以编程方式触发动画
  • 使用
    beforeRender
    + CSS过渡实现过渡效果

Customization

自定义

📄 Read: references/customization.md
  • cssClass
    for custom themes and styles
  • Tip pointer size, background, and border customization
  • Full tooltip appearance (background, opacity, font)
  • Curved tip and bubble tip arrow patterns
  • Dimension control (
    width
    , 
    height
    ) and scroll mode
  • RTL support (
    enableRtl
    )
📄 阅读： references/customization.md
  • 使用
    cssClass
    自定义主题与样式
  • 提示箭头大小、背景与边框定制
  • 工具提示整体外观（背景、透明度、字体）
  • 弧形提示与气泡箭头模式
  • 尺寸控制（
    width
    、
    height
    ）与滚动模式
  • RTL支持（
    enableRtl
    ）

How-To Patterns

实现模式

📄 Read: references/how-to.md
  • Tooltip on multiple targets (dynamic content per target)
  • Tooltip on disabled elements
  • Enabling/disabling tooltip with 
    destroy()
    and 
    render()
  • Displaying tooltip on SVG and Canvas elements
  • Embedding iframes or HTML elements in tooltip content
  • Custom open modes (double-click, right-click)
📄 阅读： references/how-to.md
  • 多目标元素的工具提示（每个目标动态内容）
  • 禁用元素上的工具提示
  • 使用
    destroy()
    与
    render()
    启用/禁用工具提示
  • SVG与Canvas元素上的工具提示
  • 在工具提示内容中嵌入iframe或HTML元素
  • 自定义触发模式（双击、右键点击）

Accessibility

无障碍支持

📄 Read: references/accessibility.md
  • WCAG 2.2 and Section 508 compliance
  • WAI-ARIA attributes (
    role="tooltip"
    , 
    aria-describedby
    , 
    aria-hidden
    )
  • Keyboard shortcuts (Escape, Tab)
  • Screen reader behavior
📄 阅读： references/accessibility.md
  • WCAG 2.2与Section 508合规性
  • WAI-ARIA属性（
    role="tooltip"
    、
    aria-describedby
    、
    aria-hidden
    ）
  • 键盘快捷键（Escape、Tab）
  • 屏幕阅读器行为

API Reference

API参考

📄 Read: references/api.md
  • All properties, methods, and events with types and defaults
  • TooltipAnimationSettings
    , 
    TooltipEventArgs
    types
  • Position
    and 
    TipPointerPosition
    enum values
📄 阅读： references/api.md
  • 所有属性、方法与事件，包含类型与默认值
  • TooltipAnimationSettings
    、
    TooltipEventArgs
    类型
  • Position
    与
    TipPointerPosition
    枚举值

Common Patterns

常见模式

Tooltip on a Button

按钮上的工具提示

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

Multi-Target Tooltip in a Container

容器内多目标工具提示

tsx
// 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>
tsx
// 单个TooltipComponent处理所有.e-info目标；
// 每个目标使用自身的`title`属性作为内容
<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>

Click-Triggered Sticky Tooltip

点击触发的粘性工具提示

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

Programmatic Open/Close

编程式打开/关闭

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

Mouse-Trailing Tooltip

鼠标跟随工具提示

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

Key Props at a Glance

关键属性概览

PropTypeDefaultPurpose
content
string | HTMLElement | Function
—Tooltip text, HTML, or JSX template
target
string
—CSS selector for multi-target mode
position
Position
'TopCenter'
12 placement values
opensOn
string
'Auto'
Hover / Click / Focus / Custom
isSticky
boolean
false
Keep visible until user closes
mouseTrail
boolean
false
Follow mouse cursor
showTipPointer
boolean
true
Show/hide arrow tip
tipPointerPosition
TipPointerPosition
'Auto'
Auto / Start / Middle / End
openDelay
number
0
ms delay before opening
closeDelay
number
0
ms delay before closing
offsetX
/ 
offsetY
number
0
Distance from target (px)
width
/ 
height
string | number
'auto'
Tooltip dimensions
cssClass
string
null
Custom CSS class
animation
AnimationModel
FadeIn/FadeOut 150msOpen/close animation
enableRtl
boolean
false
Right-to-left rendering
enableHtmlSanitizer
boolean
true
Sanitize HTML content
container
string | HTMLElement
body
Popup append target
windowCollision
boolean
false
Collision vs viewport
属性类型默认值用途
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
淡入/淡出150ms打开/关闭动画
enableRtl
boolean
false
从右到左渲染
enableHtmlSanitizer
boolean
true
清理HTML内容
container
string | HTMLElement
body
弹窗挂载目标
windowCollision
boolean
false
与视口碰撞处理