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、サイズ変更イベント
• キーボードナビゲーション：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
• フックを使った関数コンポーネントのパターン
• 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 など）
• ミリ秒単位の duration
• アニメーション開始前の delay
• アニメーションの無効化（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：アニメーション付きダイアログ

ズームアニメーションを使ったダイアログ：

<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[]	フッターのアクションボタン	-	OK／キャンセル、アクションの確認
footerTemplate	JSX	カスタムフッターコンテンツ	-	buttons プロパティが適さない場合
showCloseIcon	boolean	ヘッダーに閉じるボタンを表示します	false	ユーザーが閉じられるようにします
position	PositionData	X／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 (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. 設定／環境設定 - タブ付きダイアログでアプリケーションの設定を整理します

---

次へ： 実装する内容に応じてリファレンスを選択してください。すべてのリファレンスに、動作するコード例、ベストプラクティス、トラブルシューティングのガイダンスが含まれています。