syncfusion-react-dashboard-layout

Syncfusion React Dashboard Layout の実装

Syncfusion React Dashboard Layout は、ドラッグやサイズ変更が可能なパネルを備えた、レスポンシブでインタラクティブなダッシュボードインターフェイスを構築するための強力なコンポーネントです。コンテンツを整理するための柔軟なグリッドベースのシステム、自動フローティング配置、包括的な状態管理を提供します。

主な機能：

• セルサイズを柔軟に設定できる複数列のグリッドレイアウト
• ドラッグ＆ドロップによるパネルの再配置
• サイズ制約を設定できるパネルのサイズ変更
• 自動フローティング配置（空きスペースを埋めます）
• メディアクエリによるレスポンシブデザイン
• パネルの動的な追加／削除／更新操作
• セッションをまたいだ状態の永続化
• 変更を監視する包括的なイベントシステム
• アクセシビリティ対応と RTL レンダリング

ドキュメントとナビゲーションガイド

現在のタスクに合ったリファレンスを選択してください。

🚀 はじめに

📄 参照： references/getting-started.md

• インストールとパッケージのセットアップ
• CSS テーマのインポートと設定
• 最初のダッシュボードの作成
• 基本的なパネルの実装
• よくあるセットアップ上の問題と解決策

🎯 コアコンセプト

📄 参照： references/core-functionality.md

• パネルの作成と設定（PanelModel インターフェイス）
• 基本的なドラッグと配置
• 制約付きの基本的なサイズ変更
• グリッド設定の基礎
• コンポーネントの全体像

📄 参照： references/properties-reference.md

• 15 個のコンポーネントプロパティすべての解説
• レイアウトプロパティ（columns、cellSpacing、cellAspectRatio）
• カスタマイズオプション（enableRtl、enablePersistence、showGridLines）
• 高度なプロパティ（mediaQuery、draggableHandle、resizableHandles）
• パターンを含むプロパティの完全なリファレンス

🎨 ユーザーインターフェイスとカスタマイズ

📄 参照： references/panel-templates.md

• パネルの構造と構成
• ヘッダーテンプレート（テキスト、HTML、インタラクティブ）
• コンテンツテンプレート（HTML 文字列、JSX、Syncfusion コンポーネント）
• チャート、グリッド、ウィジェットの埋め込み
• コンテンツの動的な更新
• テンプレートのベストプラクティスと最適化

📄 参照： references/styling-customization.md

• CSS セレクターの完全なリファレンス
• テーマシステムとの統合（Tailwind、Bootstrap、Material、Fluent）
• ヘッダーとコンテンツ領域のスタイル設定
• リサイズハンドルのスタイル設定とカスタマイズ
• パネルの背景、境界線、グラデーション
• ドラッグ時およびインタラクション状態のスタイル設定
• 高度なカスタマイズパターン

🎮 インタラクションと動作

📄 参照： references/dragging-behavior.md

• ドラッグ機能の有効化と設定
• ドラッグイベント（dragStart、drag、dragStop）
• 衝突検出とパネルの押し出し
• カスタムドラッグハンドル（ヘッダーのみ、アイコンのみ、複数）
• 特定のパネルのドラッグを禁止
• 視覚的なフィードバックとプレースホルダーのスタイル設定
• パネルのプログラムによる移動
• 元に戻す／やり直しの実装

📄 参照： references/resizing-floating.md

• サイズ変更機能の有効化と設定
• リサイズハンドルの方向（SE、E、W、N、S、NW、NE、SW）
• サイズ制約（minSizeX、minSizeY、maxSizeX、maxSizeY）
• リサイズイベント（resizeStart、resize、resizeStop）
• フローティング動作と隙間の充填
• プログラムによるサイズ変更（resizePanel メソッド）
• レスポンシブなサイズ変更とアスペクト比の維持
• サイズ変更のベストプラクティス

⚙️ 設定とレイアウト

📄 参照： references/cell-configuration.md

• グリッドの列とセルの配置
• セルサイズの基本（sizeX、sizeY）
• セルのアスペクト比の設定
• セル間隔とギャップの管理
• セル計算の例
• レスポンシブなセル設定
• Masonry、ヒーロー、ネストされたグリッドのパターン

📄 参照： references/responsive-design.md

• 組み込みのレスポンシブ動作
• メディアクエリの設定とカスタムブレークポイント
• 標準的なブレークポイントシステム
• さまざまな画面サイズに対応するアダプティブレイアウト
• モバイルファーストのアプローチ
• タッチデバイスのサポートと最適化
• レスポンシブレイアウトのテスト
• レスポンシブ対応のパフォーマンス最適化

💾 高度な機能

📄 参照： references/state-persistence.md

• レイアウト保存用のserializeメソッド
• 状態の保存と復元のパターン
• localStorageとの連携
• sessionStorageとの連携
• データベースAPIとの連携
• 高度な状態管理（Redux、Context API）
• バージョン管理と移行
• エラー復旧とバックアップ

📄 参照： references/methods-reference.md

• 9つのコンポーネントメソッドすべてを解説
• パネル管理：addPanel、removePanel、removeAll、updatePanel
• レイアウト操作：movePanel、resizePanel
• シリアライズ：serializeメソッド
• ユーティリティメソッド：refreshDraggableHandle、destroy
• メソッドの完全な使用例とユースケース

📄 参照： references/events-reference.md

• 10個のコンポーネントイベントすべてを解説
• ライフサイクルイベント：created、destroyed
• 操作イベント：dragStart、drag、dragStop、resizeStart、resize、resizeStop
• 変更イベント：パネルの追加、削除、位置変更の監視
• イベントの引数とプロパティ
• イベント処理の完全なパターン

♿ 準拠とアクセシビリティ

📄 参照： references/accessibility-wcag.md

• WCAG 2.2 レベルAAへの準拠
• Section 508規格への準拠
• WAI-ARIAの実装（ロール、プロパティ、状態）
• キーボード操作とアクセシビリティ
• スクリーンリーダーのサポート
• RTL（右から左へ記述する言語）のサポート
• テストおよび検証手順
• アクセシビリティ監査チェックリスト

クイックスタートの例

数分でインタラクティブなダッシュボードを作成できます。

import React, { useRef } from 'react';
import { DashboardLayoutComponent } from '@syncfusion/ej2-react-layouts';
import '@syncfusion/ej2-base/styles/tailwind3.css';
import '@syncfusion/ej2-react-layouts/styles/tailwind3.css';

function Dashboard() {
  const dashboardRef = useRef<DashboardLayoutComponent>(null);

  const panels = [
    {
      id: 'sales',
      header: 'Sales',
      content: '<div style="padding: 20px;">Sales data</div>',
      row: 0,
      col: 0,
      sizeX: 2,
      sizeY: 2
    },
    {
      id: 'users',
      header: 'Users',
      content: '<div style="padding: 20px;">User analytics</div>',
      row: 0,
      col: 2,
      sizeX: 2,
      sizeY: 2
    },
    {
      id: 'reports',
      header: 'Reports',
      content: '<div style="padding: 20px;">Report metrics</div>',
      row: 2,
      col: 0,
      sizeX: 4,
      sizeY: 1
    }
  ];

  return (
    <div style={{ padding: '20px' }}>
      <h1>Dashboard</h1>
      <DashboardLayoutComponent
        ref={dashboardRef}
        id='dashboard'
        columns={5}
        cellSpacing={[10, 10]}
        panels={panels}
        allowDragging={true}
        allowResizing={true}
        allowFloating={true}
        enablePersistence={true}
      >
      </DashboardLayoutComponent>
    </div>
  );
}

export default Dashboard;

よくあるパターン

パターン1：モバイル対応のレスポンシブダッシュボード

📖 参照： モバイルへの適応パターンの詳細については、responsive-design.mdを参照してください。

<DashboardLayoutComponent
  id='responsive-dashboard'
  columns={5}
  mediaQuery='max-width:768px'  // Single column on tablets/mobile
  cellSpacing={[10, 10]}
  allowDragging={true}
  allowResizing={true}
  panels={panels}
>
</DashboardLayoutComponent>

主な機能：

• 画面サイズに応じたレスポンシブな列数の調整
• メディアクエリを使用したモバイルファースト設計
• モバイルデバイス向けのタッチ操作の最適化
• ブレークポイントの設定とテストについては、responsive-design.mdを参照してください

パターン2：ユーザーレイアウトの保存と復元

📖 参照： 状態のシリアライズとストレージオプションの詳細については、state-persistence.mdを参照してください。

const handleSaveLayout = () => {
  const layout = dashboardRef.current?.serialize();
  localStorage.setItem('userDashboard', JSON.stringify(layout));
};

const handleRestoreLayout = () => {
  const saved = localStorage.getItem('userDashboard');
  if (saved) {
    const layout = JSON.parse(saved);
    dashboardRef.current?.removeAll();
    layout.forEach(panel => {
      dashboardRef.current?.addPanel(panel);
    });
  }
};

主な機能：

• serialize()メソッドで現在のレイアウト状態をエクスポート
• クライアント側での永続化にlocalStorageを使用
• API連携、Redux／Contextのパターン、自動保存については、state-persistence.mdを参照してください

パターン3：動的なパネル管理

📖 参照： パネルの追加・削除と実行時の管理については、core-functionality.mdを参照してください。

const handleAddPanel = () => {
  dashboardRef.current?.addPanel({
    id: `panel-${Date.now()}`,
    header: 'New Panel',
    content: 'Panel content',
    row: 0,
    col: 0,
    sizeX: 2,
    sizeY: 1
  });
};

const handleRemovePanel = (panelId: string) => {
  dashboardRef.current?.removePanel(panelId);
};

主な機能：

• 実行時のパネル作成と削除
• 一意のパネルIDと配置
• パネル変更時のイベント処理
• 利用可能なすべてのパネルメソッドについては、methods-reference.mdを参照してください

パターン4：パネルサイズの制約

📖 参照： サイズ制約とリサイズ動作については、cell-configuration.mdおよびresizing-floating.mdを参照してください。

const constrainedPanels = [
  {
    id: 'fixed-panel',
    header: 'Fixed Size',
    row: 0,
    col: 0,
    sizeX: 2,
    sizeY: 1,
    minSizeX: 2,  // Cannot shrink
    maxSizeX: 2,  // Cannot expand
    minSizeY: 1,
    maxSizeY: 1
  },
  {
    id: 'flexible-panel',
    header: 'Flexible',
    row: 0,
    col: 2,
    sizeX: 2,
    sizeY: 1,
    minSizeX: 1,  // Can shrink to 1 cell
    maxSizeX: 4   // Can expand to 4 cells
  }
];

主な機能：

• minSizeX/YおよびmaxSizeX/Yによる制約
• 固定サイズと可変サイズのパネル
• resizePanel()によるプログラムからのサイズ更新
• グリッドの計算については、cell-configuration.mdを、高度なリサイズパターンについては、resizing-floating.mdを参照してください

パターン 5：レイアウト変更の監視

📖 参照： 利用可能なすべてのイベントとハンドラーについては、events-reference.md をご覧ください。

const handleChange = (args: ChangeEventArgs) => {
  console.log('Panels added:', args.addedPanels);
  console.log('Panels removed:', args.removedPanels);
  console.log('Panels position changed:', args.changedPanels);
  console.log('User interaction:', args.isInteracted);
};

<DashboardLayoutComponent
  panels={panels}
  change={handleChange}
>
</DashboardLayoutComponent>

主な機能：

• レイアウトが変更されるたびに変更イベントが発生します
• 追加、削除、再配置されたパネルにアクセスできます
• ユーザー操作を検出できます
• ドラッグ、サイズ変更、その他のイベントハンドラーについては、events-reference.md をご覧ください

主要な API の概要

コンポーネントのプロパティ

📖 詳細なリファレンス： properties-reference.md

• columns - グリッドの列数（デフォルト：1）→ cell-configuration.md をご覧ください
• cellSpacing - パネル間の間隔［水平、垂直］→ cell-configuration.md をご覧ください
• panels - レイアウトを定義する PanelModel オブジェクトの配列 → panel-templates.md をご覧ください
• allowDragging - パネルのドラッグ＆ドロップを有効にします（デフォルト：true）→ dragging-behavior.md をご覧ください
• allowResizing - パネルのサイズ変更を有効にします（デフォルト：false）→ resizing-floating.md をご覧ください
• allowFloating - 空きスペースを自動的に埋めます（デフォルト：true）→ resizing-floating.md をご覧ください
• enablePersistence - レイアウト状態を保存します（デフォルト：false）→ state-persistence.md をご覧ください
• mediaQuery - モバイルレイアウトのレスポンシブブレークポイント → responsive-design.md をご覧ください
• draggableHandle - カスタムのドラッグハンドルセレクター → dragging-behavior.md をご覧ください
• resizableHandles - サイズ変更ハンドルの方向 → resizing-floating.md をご覧ください
• cssClass - カスタム CSS クラス → styling-customization.md をご覧ください

主なメソッド

📖 詳細なリファレンス： methods-reference.md

• addPanel(panel) - 実行時に新しいパネルを追加します → core-functionality.md をご覧ください
• removePanel(id) - ID でパネルを削除します → core-functionality.md をご覧ください
• removeAll() - すべてのパネルをクリアします → core-functionality.md をご覧ください
• updatePanel(panel) - 既存のパネルを変更します → core-functionality.md をご覧ください
• movePanel(id, row, col) - パネルの位置を変更します → dragging-behavior.md をご覧ください
• resizePanel(id, sizeX, sizeY) - パネルの寸法を調整します → resizing-floating.md をご覧ください
• serialize() - 現在のレイアウト状態を取得します → state-persistence.md をご覧ください

重要なイベント

📖 詳細なリファレンス： events-reference.md

• created - コンポーネントが初期化されました
• dragStart / drag / dragStop - ドラッグ操作 → dragging-behavior.md をご覧ください
• resizeStart / resize / resizeStop - サイズ変更操作 → resizing-floating.md をご覧ください
• change - レイアウトが変更されました（追加、削除、移動）→ events-reference.md をご覧ください

スタイル設定とカスタマイズ

📖 詳細なリファレンス： styling-customization.md

• すべてのパネル要素に対応する CSS セレクター
• テーマのカスタマイズ（Tailwind、Bootstrap、Material、Fluent）
• レスポンシブスタイルのパターン
• アクセシビリティに配慮したスタイル設定（WCAG 2.2）

一般的なユースケース

🎯 ダッシュボードの作成： グリッドに整理された複数のコンテンツパネルを備えた、カスタマイズ可能なダッシュボードレイアウトを実装します。

• 参照：core-functionality.md、panel-templates.md

🎯 ユーザーがカスタマイズできるレイアウト： ダッシュボードのパネルをユーザーの好みに合わせて並べ替えたり、サイズを変更したりできるようにし、自動保存にも対応します。

• 参照：dragging-behavior.md、resizing-floating.md、state-persistence.md

🎯 レスポンシブなインターフェース： 複数列のデスクトップ表示から単一列のモバイル表示まで適応するレイアウトを構築します。

• 参照：responsive-design.md、cell-configuration.md

🎯 リアルタイム監視： ライブ更新に対応した、サイズ変更可能なパネルに複数のリアルタイムデータソースを表示します。

• 参照：panel-templates.md（コンポーネントの埋め込み）、events-reference.md

🎯 管理パネル： システムの監視や制御に使う、ドラッグ可能なウィジェットを備えた管理インターフェースを作成します。

• 参照：dragging-behavior.md、styling-customization.md、accessibility-wcag.md

🎯 データの可視化： 複数のチャート、テーブル、メトリクスを、柔軟でレスポンシブなパネルレイアウトに整理します。

• 参照：panel-templates.md（チャート／グリッドの埋め込み）、styling-customization.md

パネルモデルインターフェース

interface PanelModel {
  id: string;              // Unique identifier (required)
  row: number;             // Row position (required)
  col: number;             // Column position (required)
  sizeX: number;           // Width in cells (default: 1)
  sizeY: number;           // Height in cells (default: 1)
  header?: string | HTMLElement | Function;
  content?: string | HTMLElement | Function;
  cssClass?: string;       // Custom CSS classes
  enabled?: boolean;       // Enable/disable (default: true)
  minSizeX?: number;       // Minimum width (default: 1)
  minSizeY?: number;       // Minimum height (default: 1)
  maxSizeX?: number;       // Maximum width
  maxSizeY?: number;       // Maximum height
  zIndex?: number;         // Stacking order
}

クイックリファレンスガイド

タスク	参照するドキュメント
使い始める	getting-started.md - インストール、セットアップ、テーマ
パネル管理を学ぶ	core-functionality.md - パネルの作成、更新、削除
パネルの内容をカスタマイズする	panel-templates.md - ヘッダー、テンプレート、コンポーネントの埋め込み
ドラッグ可能にする	dragging-behavior.md - ドラッグイベント、衝突、カスタムハンドル
サイズ変更可能にする	resizing-floating.md - サイズ変更ハンドル、制約、フローティング
グリッドシステムを設定する	cell-configuration.md - 列、間隔、アスペクト比、レスポンシブグリッド
レスポンシブにする	responsive-design.md - ブレークポイント、モバイル、タッチ操作の最適化
ユーザーレイアウトを保存する	state-persistence.md - serialize()、localStorage、API、Redux、Context
スタイルとテーマ	styling-customization.md - CSS セレクター、テーマ、レスポンシブスタイル
アクセシビリティに対応する	accessibility-wcag.md - WCAG 2.2、WAI-ARIA、スクリーンリーダー、RTL
API リファレンス	properties-reference.md、methods-reference.md、events-reference.md
高度なパターン	advanced-features.md - カスタム統合、パフォーマンスの最適化

実装ロードマップ

フェーズ 1 - 基盤（ここから開始）：

1. セットアップについては、getting-started.md をお読みください
2. パネルの基本については、core-functionality.md をご確認ください
3. 利用可能なすべてのオプションについては、properties-reference.md をご確認ください

フェーズ 2 - インタラクション（機能を構築）： 4. ドラッグ機能を実装します：dragging-behavior.md 5. サイズ変更機能を実装します：resizing-floating.md 6. グリッドを設定します：cell-configuration.md

フェーズ 3 - コンテンツ（ビジュアルをカスタマイズ）： 7. パネルテンプレートを作成します：panel-templates.md 8. スタイリングを適用します：styling-customization.md

フェーズ 4 - 仕上げ（本番環境への準備）： 9. モバイル向けに最適化します：responsive-design.md 10. アクセシビリティを追加します：accessibility-wcag.md 11. 永続化機能を実装します：state-persistence.md

フェーズ 5 - 高度な機能（エキスパート向け）： 12. パターンを確認します：advanced-features.md 13. イベント／メソッド API を参照します：events-reference.md、methods-reference.md