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

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

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

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.