syncfusion-angular-dashboard-layout

Syncfusion Angular Dashboard Layout の実装

Dashboard Layout コンポーネントは、動的なパネルを備えたレスポンシブでインタラクティブなダッシュボードを作成できる、強力なグリッド構造のレイアウトコントロールです。パネルはドラッグ、サイズ変更、追加、削除が可能で、その状態を保持できます。このスキルでは、Angular でダッシュボードレイアウトを実装、構成、カスタマイズするあらゆる方法を説明します。

このスキルを使用する場面

• 複数のパネルを備えたカスタマイズ可能なダッシュボードレイアウトを作成する
• ドラッグ＆ドロップによるパネルの位置変更を実装する
• 複数方向へのパネルのサイズ変更を有効にする
• ダッシュボードのパネルを動的に追加または削除する
• さまざまなデバイスサイズに対応するレスポンシブなダッシュボードを作成する
• ダッシュボードレイアウトの構成を保存および復元する
• CSS のカスタマイズでダッシュボードコンポーネントのスタイルを設定する
• Syncfusion のチャート、グリッド、その他のコンポーネントをパネルのコンテンツとして統合する

コンポーネントの概要

Dashboard Layout コンポーネントには、次の機能があります。

• グリッドベースのレイアウトシステム。列数とセルの寸法を構成できます
• ドラッグ＆ドロップ。視覚的なフィードバックを提供しながらパネルを並べ替えられます
• サイズ変更。複数の方向（東、西、北、南など）に対応します
• フローティングパネル。空いたスペースを自動的に埋めます
• レスポンシブ動作。メディアクエリのブレークポイントをカスタマイズできます
• 状態の保持。シリアライズ／デシリアライズメソッドを使用します
• 動的なパネル管理。追加、削除、移動の各操作に対応します
• イベント駆動型アーキテクチャ。ユーザー操作を追跡できます

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

はじめに

📄 参照: references/getting-started.md

• Angular CLI のセットアップとプロジェクトの初期化
• Dashboard Layout パッケージのインストール（Ivy 版と ngcc 版）
• CSS のインポートとテーマの構成
• 2 種類のパネル定義方法（HTML 属性とプロパティバインディング）
• 基本的なコンポーネントのレンダリングと最初のダッシュボードの作成
• セル間隔とレイアウトの初期化

パネルの追加と削除

📄 参照: references/adding-removing-panels.md

• addPanel() メソッドによる動的なパネル管理
• removePanel(id) による個別パネルの削除
• removeAll() メソッドによる一括削除
• 動的生成に使用するパネル構成プロパティ
• ライフサイクル管理のためのイベント処理とコールバック

パネルヘッダーの設定

📄 参照: references/panel-headers.md

• header プロパティによるパネルヘッダーの構成
• ヘッダーへのタイトル、ラベル、HTML コンテンツの追加
• CSS のカスタマイズによるヘッダーのスタイル設定
• パネルヘッダーへの Syncfusion コンポーネントの埋め込み
• ヘッダーとのインタラクションとユーザーエクスペリエンスのパターン

パネルのドラッグとドロップ

📄 参照: references/dragging-and-dropping.md

• デフォルトのドラッグ＆ドロップ動作とパネルの衝突処理
• ドラッグイベント：dragStart、drag、dragStop
• draggableHandle プロパティによるドラッグハンドルのカスタマイズ
• movePanel(id, row, col) によるプログラムからのパネル移動
• allowDragging によるドラッグ機能の無効化
• タッチ操作への対応とユーザー操作のパターン

プログラムからのパネル移動

📄 参照: references/moving-panels.md

• movePanel(id, row, col) を使用したパネルの位置変更
• ユーザー操作を介さないパネルの移動
• change イベントによるパネルの移動の追跡
• プログラムからのパネル位置の入れ替え
• パネル再配置のパターンとユースケース

パネルのサイズ変更とフローティング

📄 参照: references/resizing-and-floating.md

• allowResizing によるパネルのサイズ変更の有効化
• さまざまな方向のサイズ変更ハンドル（e-south-east、e-east、e-west、e-north、e-south）
• サイズ変更イベント：resizeStart、resize、resizeStop
• resizePanel(id, sizeX, sizeY) によるプログラムからのサイズ変更
• 最小および最大サイズの制約（minSizeX、minSizeY、maxSizeX、maxSizeY）
• フローティング動作とパネルの自動位置変更
• 固定グリッドレイアウトでのフローティングの無効化

状態の保存と復元

📄 参照： references/save-restore-state.md

• serialize() を使用したダッシュボードレイアウトのシリアル化
• localStorage、sessionStorage、またはバックエンドへのレイアウト状態の保存
• 永続化された設定からのレイアウトの復元
• レイアウトテンプレートとプリセットの実装
• 状態を永続化するパターンとベストプラクティス

レスポンシブデザインとアダプティブデザイン

📄 参照： references/responsive-and-adaptive.md

• 組み込みのレスポンシブ動作と自動適応
• mediaQuery を使用したレスポンシブブレークポイントのカスタマイズ
• モバイルデバイスでの縦積みレイアウト（縦方向の列）
• cellAspectRatio を使用したセルのアスペクト比の設定
• さまざまな解像度でのレスポンシブレイアウトのテスト
• 親要素のサイズ設定（パーセンテージと固定サイズ）

セル間隔の設定

📄 参照： references/cell-spacing-configuration.md

• cellSpacing プロパティを使用した [水平、垂直] 間隔の設定
• コンパクトなレイアウトやゆったりとしたレイアウトに合わせた間隔の調整
• レスポンシブデザインに合わせた動的な間隔調整
• 視覚的な階層を作る非対称な間隔パターン
• 実践例：コンパクトなダッシュボード、エグゼクティブ向けレイアウト

グラフィカル表現とグリッド線

📄 参照： references/grid-lines-and-visualization.md

• showGridLines プロパティを使用したグリッド構造の可視化
• グリッドセル、行、列、間隔についての理解
• レイアウト計画に役立つ設計時のグリッド表示
• パネルの位置とサイズのデバッグ
• グリッド線の使用に関するベストプラクティス

右から左に記述する言語のサポート

📄 参照： references/rtl-support.md

• enableRtl プロパティを使用した RTL 表示の有効化
• アラビア語、ヘブライ語、ペルシア語、ウルドゥー語のサポート
• 言語切り替えに合わせた動的な RTL の切り替え
• HTML の dir 属性との連携
• RTL を考慮したスタイル設定のための CSS 論理プロパティ
• ドラッグ＆ドロップ操作における RTL の考慮事項

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

📄 参照： references/styling-and-customization.md

• パネル、ヘッダー、コンテンツをカスタマイズする CSS セレクター
• パネルのヘッダーとコンテンツのスタイル設定（.e-panel-header、.e-panel-content）
• リサイズハンドルのカスタマイズ（.e-resize）
• ダッシュボードの背景のスタイル設定
• row、col、sizeX、sizeY プロパティを使用したパネルの位置とサイズの設定
• 最小／最大サイズの制約とグリッド構造
• Syncfusion コンポーネント（Charts、Grids、Gauges）のパネルコンテンツへの統合
• レガシーな Angular 環境向けの SystemJS 設定

詳しい例とコードサンプルについては、次を参照してください：

• getting-started.md - クイックスタートと基本的なセットアップ例
• 各リファレンスファイルに記載された一般的なパターンと実装例

API リファレンス

コンポーネントのプロパティ（合計14個）

レイアウト設定

プロパティ	型	デフォルト	説明
columns	number	5	グリッドレイアウトの列数です。パネルは、この列ベースのグリッド内に配置されます。
cellSpacing	number[]	[10, 10]	パネル間の間隔：[水平、垂直]（ピクセル単位）です。パネルの周囲に視覚的な区切りと余白を作ります。
cellAspectRatio	number	Auto (1:1)	セルの幅と高さの比率です。例：100/50 の場合、幅が高さの2倍のセルになります。
mediaQuery	string	'max-width: 600px'	レスポンシブな縦積みレイアウトに使用する CSS メディアクエリのブレークポイントです。このブレークポイントより画面幅が狭い場合、パネルは縦に積み重ねられます。
showGridLines	boolean	false	true の場合、設計時のデバッグやレイアウト計画のために、グリッドセルと構造を可視化します。

インタラクション機能

プロパティ	型	デフォルト	説明
allowDragging	boolean	true	パネルのドラッグ＆ドロップ機能を有効または無効にします。true の場合、ユーザーはドラッグしてパネルの順序を変更できます。
allowResizing	boolean	false	パネルのサイズ変更を有効または無効にします。true の場合、パネルの端にサイズ変更ハンドルが表示されます。
allowFloating	boolean	true	フローティング動作を有効または無効にします。true の場合、移動またはサイズ変更されたパネルによって空いたスペースを埋めるため、パネルが自動的に上へ移動します。
resizableHandles	string[]	['e-south-east']	サイズ変更ハンドルの方向を指定する配列です。指定できる値は 'e-south-east'、'e-east'、'e-west'、'e-north'、'e-south'、'e-south-west' です。ユーザーがパネルのサイズを変更できる方向を制御します。
draggableHandle	string	null	ドラッグハンドル要素を指定する CSS セレクター文字列です。設定すると、ユーザーがこの特定の要素（例：'.e-panel-header'）をつかんだ場合にのみドラッグできます。

コンテンツとスタイル

プロパティ	型	デフォルト	説明
panels	PanelModel[]	[]	ダッシュボードのレイアウト構造とコンテンツを定義する、パネル設定の配列です。
enableRtl	boolean	false	RTL 言語（アラビア語、ヘブライ語、ペルシア語、ウルドゥー語）向けの右から左への表示を有効にします。
enableHtmlSanitizer	boolean	true	XSS 攻撃を防ぐため、パネル内の HTML コンテンツをサニタイズします。信頼できるコンテンツである場合にのみ false に設定してください。
enablePersistence	boolean	false	true の場合、ページを再読み込みしてもダッシュボードの状態が維持されるよう、ブラウザーのストレージに自動的に保存および復元します。

パネルのプロパティ（全13項目）

プロパティ	型	デフォルト	説明
位置とサイズ
row	number	0	グリッド内の開始行位置（0 から始まるインデックス）です。垂直方向の配置を指定します。
col	number	0	グリッド内の開始列位置（0 から始まるインデックス）です。水平方向の配置を指定します。
sizeX	number	1	セル単位で指定するパネルの幅です。例：sizeX=2 の場合、グリッドの列を2列分占めます。
sizeY	number	1	セル単位で指定するパネルの高さです。例：sizeY=2 の場合、グリッドの行を2行分占めます。
サイズ制約
minSizeX	number	1	セル単位で指定する最小幅です。この値より小さくなるようにパネルのサイズを変更できないようにします。
minSizeY	number	1	セル単位で指定する最小高さです。この値より小さくなるようにパネルのサイズを変更できないようにします。
maxSizeX	number	null	セル単位で指定する最大幅です。null の場合、上限はありません。この値より大きくなるようにパネルのサイズを変更できないようにします。
maxSizeY	number	null	セル単位で指定する最大高さです。null の場合、上限はありません。この値より大きくなるようにパネルのサイズを変更できないようにします。
コンテンツ
id	string	''	パネルの一意な識別子です。movePanel()、resizePanel()、removePanel() などのメソッドで必要です。
header	string | HTMLElement | Function	undefined	ヘッダーまたはタイトルのコンテンツです。HTML 文字列、DOM 要素、またはコンテンツを返す関数を指定できます。
content	string | HTMLElement | Function	undefined	本文のコンテンツです。HTML 文字列、DOM 要素、またはコンテンツを返す関数（例：チャート、グリッド）を指定できます。
スタイルと状態
cssClass	string	''	パネルに適用するカスタム CSS クラス名です。スタイルやテーマの設定に使用します。
enabled	boolean	true	false の場合、パネルを無効にし、操作できないようにします。
zIndex	number	1000	レイヤーの順序を指定する CSS の z-index です。値が大きいほど前面に表示されます。

イベント（全9項目）

ドラッグイベント

イベント	引数	説明
dragStart	DragStartArgs	ユーザーがパネルのドラッグを開始したときに発生します。引数：cancel（ドラッグを防止する bool）、element（HTMLElement）、event（MouseEvent|TouchEvent）。特定のドラッグ操作を検証または防止するために使用します。
drag	DraggedEventArgs	ドラッグ中に継続的に発生します。引数：element（ドラッグ中の HTMLElement）、event（MouseEvent|TouchEvent）、target（カーソルの下にある HTMLElement）。ドラッグ中の視覚的なフィードバックに使用します。1 秒あたり 60 回以上発生するため、負荷の高い処理はスロットリングしてください。
dragStop	DragStopArgs	ドラッグが完了または終了したときに発生します。引数：cancel（位置を元に戻すための bool）、element、event、panels（影響を受けるパネルの PanelModel[]）、target。最終的な位置の保存やドロップ位置の検証に使用します。

サイズ変更イベント

イベント	引数	説明
resizeStart	ResizeArgs	サイズ変更が開始されたときに発生します。引数：element（HTMLElement）、event（MouseEvent|TouchEvent）、isInteracted（true＝ユーザー操作、false＝プログラムによる操作）、panels（影響を受ける PanelModel[]）。
resize	ResizeArgs	サイズ変更中に継続的に発生します。引数は resizeStart と同じです。リアルタイムの検証や新しい寸法の表示に使用します。頻繁に発生するため、負荷の高い処理はスロットリングしてください。
resizeStop	ResizeArgs	サイズ変更が完了したときに発生します。引数は resize と同じです。パネルサイズの確定や状態の保存に使用します。

レイアウト変更イベント

イベント	引数	説明
change	ChangeEventArgs	レイアウトが変更されたとき（パネルの追加、削除、移動、サイズ変更）に発生します。引数：addedPanels（追加された PanelModel[]）、changedPanels（変更された PanelModel[]）、isInteracted（bool）、removedPanels（削除された PanelModel[]）。すべてのレイアウト変更を検出して対応するために使用します。
created	Object	ダッシュボードコンポーネントの初期化とレンダリングが完全に完了したときに発生します。初期化後のセットアップに使用します。
destroyed	Object	ダッシュボードコンポーネントが破棄されたときに発生します。後処理に使用します。

メソッド

パネル管理

メソッド	シグネチャ	戻り値	説明
addPanel	addPanel(panel: PanelModel)	void	ダッシュボードに新しいパネルを動的に追加します。パネルは row/col プロパティに従って配置されます。change イベントが発生します。
removePanel	removePanel(panelId: string)	void	ID を指定して特定のパネルを削除します。change イベントが発生します。allowFloating=true の場合、他のパネルが上に詰められることがあります。
removeAll	removeAll()	void	ダッシュボードからすべてのパネルを削除します。レイアウト全体がクリアされます。
movePanel	movePanel(panelId: string, row: number, col: number)	void	パネルを新しいグリッド位置に移動します。有効な場合は、フローティングを伴うドラッグと同様の動作が発生します。change イベントが発生します。
resizePanel	resizePanel(panelId: string, sizeX: number, sizeY: number)	void	パネルのサイズを新しい寸法（セル単位）に変更します。minSize/maxSize の制約が適用されます。isInteracted=false のサイズ変更イベントが発生します。change イベントが発生します。

状態管理

メソッド	シグネチャ	戻り値	説明
serialize	serialize()	PanelModel[]	現在のダッシュボードレイアウトの状態を取得し、PanelModel オブジェクトの配列として返します。ユーザー設定を永続化するには、localStorage またはデータベースと併用します。レイアウトテンプレートやプリセットの作成にも使用できます。

コンポーネントのライフサイクル

メソッド	シグネチャ	戻り値	説明
updatePanel	updatePanel(panelId: string, panelModel: PanelModel)	void	既存のパネルのプロパティを更新します。パネルを削除して再追加することなく、ヘッダー、コンテンツ、その他のパネルプロパティを変更する場合に便利です。変更されたパネルを含む change イベントを発生させます。
refreshDraggableHandle	refreshDraggableHandle()	void	ドラッグ可能なハンドルのセレクターを更新します。DOM 構造が変更された場合や、draggableHandle の CSS セレクターを再評価する必要がある場合に呼び出します。外部から DOM を変更した後に便利です。
destroy	destroy()	void	Dashboard Layout コンポーネントを破棄し、すべてのリソースをクリーンアップします。destroyed イベントを発生させます。メモリリークを防ぐため、コンポーネントのアンマウント前に呼び出してください。

イベント引数のリファレンス

DragStartArgs

{
  cancel: boolean;              // Set to true to prevent the drag operation
  element: HTMLElement;         // The panel element being dragged
  event: MouseEvent | TouchEvent; // The original browser event
}

DraggedEventArgs

{
  element: HTMLElement;         // The panel element being dragged
  event: MouseEvent | TouchEvent; // The original browser event (fires 60+ times/sec)
  target: HTMLElement;          // The element currently under the cursor
}

DragStopArgs

{
  cancel: boolean;              // Set to true to cancel/revert the drag
  element: HTMLElement;         // The panel element that was dragged
  event: MouseEvent | TouchEvent; // The drop/release event
  panels: PanelModel[];         // Array of panels affected by the drag (position changed)
  target: HTMLElement;          // The element at the drop location
}

ResizeArgs

{
  element: HTMLElement;         // The panel element being resized
  event: MouseEvent | TouchEvent; // The original browser event
  isInteracted: boolean;        // true = user resize, false = programmatic resize
  panels: PanelModel[];         // Array of panels affected by the resize
}

ChangeEventArgs

{
  addedPanels: PanelModel[];    // Panels added in this change
  changedPanels: PanelModel[];  // Panels whose position/size changed
  isInteracted: boolean;        // true = user action, false = programmatic
  removedPanels: PanelModel[];  // Panels removed in this change
}

メソッドの詳細な例とセキュリティ設定については、以下を参照してください。

• adding-removing-panels.md - パネル管理のメソッドの例
• styling-and-customization.md - セキュリティと設定の例

一般的なユースケース

1. 分析ダッシュボード： データを監視するため、サイズ変更可能なパネルにチャートとメトリクスを表示します
2. 管理パネル： 追加・削除やドラッグ＆ドロップに対応する動的なウィジェットシステム
3. リアルタイム監視： レイアウトの状態を維持しながらパネルのコンテンツを更新します
4. モバイル対応ポータル： モバイルではパネルを縦に並べ、デスクトップではグリッドレイアウトにします
5. ユーザーがカスタマイズできるレイアウト： ユーザーが好みのダッシュボード配置を保存できるようにします
6. ウィジェットストア： ウィジェットライブラリから新しいパネルを動的に追加します

関連トピック

コンポーネントのセットアップと設定

• Angular モジュールのセットアップ： スタンドアロンコンポーネントへの DashboardLayoutModule のインポート
• CSS テーマ： 利用可能なテーマ（material3、bootstrap5、fabric、tailwind）
• 親要素のレスポンシブなサイズ設定： 流動的なレイアウトでのパーセント指定と固定寸法の使い分け
• 永続化とストレージ： enablePersistence と手動の serialize() アプローチの比較

イベント処理とインタラクション

• ドラッグイベント： dragStart（ドラッグのキャンセル）、drag（視覚的フィードバック）、dragStop（確定）
• サイズ変更イベント： resizeStart、resize（連続的な変更）、resizeStop（制約の検証を伴う）
• 変更検出： (change) イベントを使用してすべてのレイアウト変更（追加・削除・移動・サイズ変更）を追跡します
• イベントのスロットリング： ドラッグ（毎秒60回以上）とサイズ変更イベントのパフォーマンスを最適化します
• isInteracted プロパティ： ユーザー操作とプログラムによる変更を区別します

高度な機能

• 動的なパネル管理： addPanel()、removePanel()、removeAll() メソッド
• プログラムによる移動： movePanel(id, row, col) による自動的な再配置
• プログラムによるサイズ変更： 制約を適用する resizePanel(id, sizeX, sizeY)
• 状態のシリアル化： レイアウトの保存・復元に使用する serialize() メソッド
• サイズ制約： パネルの境界を指定する minSizeX、minSizeY、maxSizeX、maxSizeY
• フローティング動作： allowFloating による空きスペースの自動補完

コンポーネントの統合

• チャートの埋め込み： パネルのコンテンツとして Syncfusion Charts（Column、Line、Pie など）を使用します
• グリッドの埋め込み： パネル内でデータ、並べ替え、フィルタリングに対応する Syncfusion Grids を使用します
• ゲージの埋め込み： メトリクスと KPI に Linear Gauges と Radial Gauges を使用します
• カスタム HTML コンテンツ： 動的なコンテンツ生成に Function 型を使用します
• Content Function 型： 遅延読み込みまたはリアクティブなコンテンツに content/header を (Function) として使用します

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

• CSS クラス： .e-panel-header、.e-panel-content、.e-resize、.e-dashboardlayout
• パネルのスタイル設定： パネルごとにカスタムテーマを設定する cssClass プロパティ
• ヘッダーのカスタマイズ： 動的なヘッダーに対応する Function／HTMLElement 型
• ドラッグハンドルのカスタマイズ： ドラッグ可能な領域を制限する draggableHandle CSS セレクター
• RTL サポート： 右から左に記述するレイアウトでの enableRtl と resizableHandles の動作

パフォーマンスと最適化

• 大規模なダッシュボードのレンダリング： 100 個を超えるパネルに対応する手法
• 仮想スクロール： 大規模なダッシュボードで代替レイアウトを検討するタイミング
• イベントのスロットリング： ドラッグ（毎秒 60 回以上）とサイズ変更のイベント頻度の管理
• メモリ管理： destroy イベント発生時のパネルのクリーンアップ
• 変更イベントのフィルタリング： 関連する変更（addedPanels、changedPanels、removedPanels）のみを追跡