syncfusion-react-popups（syncfusion React popups 开发）

Syncfusion React Popups Component

Implementing Syncfusion React Dialog Component

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.

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

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

Modal vs Modeless

📄 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

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

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

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)

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

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

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

API Reference (Complete)

📄 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

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:

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

Delete action with confirmation buttons:

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

Dialog with form inputs and validation:

<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

Position dialog in center of screen:

<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

Non-modal, draggable properties panel:

<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

Dialog with Zoom animation:

<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

Custom footer instead of buttons:

<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

Parent dialog containing child dialog:

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)

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.

Implementing Syncfusion React Predefined Dialog Component

Table of Contents

• Key Concept
• Quick Start
• Documentation Guide
• Common Patterns

Key Concept

Syncfusion Predefined Dialogs are not component-based (<ejs-dialog>). They are opened imperatively via the DialogUtility utility class:

Import: import {DialogUtility} from '@syncfusion/ej2-react-popups';

Quick Start

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

Animation

📄 Read: references/animation.md

• animationSettings property with effect, duration, delay
• Alert / Confirm / Prompt animation examples

Draggable

📄 Read: references/draggable.md

• isDraggable boolean property
• Alert / Confirm / Prompt drag examples

Position

📄 Read: references/position.md

• position property: {X, Y} — left|center|right / top|center|bottom or numeric offset
• Alert / Confirm / Prompt position examples

Dimension

📄 Read: references/dimension.md

• width and height properties
• cssClass for max-width / min-width constraints
• Alert / Confirm / Prompt dimension examples

Customization

📄 Read: references/customization.md

• okButton / cancelButton — custom text, icon, click handler
• showCloseIcon and closeOnEscape
• Custom content for prompt dialogs

API Reference

📄 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

Common Patterns

Alert with OK callback:

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

Confirm with Yes / No:

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

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

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

Quick Start

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;

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

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

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)

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)

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

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)

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)

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

API Reference

📄 Read: references/api.md

• All properties, methods, and events with types and defaults
• TooltipAnimationSettings, TooltipEventArgs types
• Position and TipPointerPosition enum values

Common Patterns

Tooltip on a Button

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

Multi-Target Tooltip in a Container

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

Click-Triggered Sticky Tooltip

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

Programmatic Open/Close

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

<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