syncfusion-wpf-gridsplitter

Syncfusion WPF GridSplitter の実装

このスキルでは、Syncfusion® WPF GridSplitter（SfGridSplitter）コントロールの実装方法を説明します。このコントロールは、移動可能なスプリッターで利用可能な領域を水平または垂直に分割し、視覚要素を動的にサイズ変更できるコンテナーコントロールです。

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

次のような場合にこのスキルを使用してください。

• パネル間に移動可能なスプリッターを配置し、サイズ変更可能なレイアウトを作成する
• WPF アプリケーションに分割パネルを実装する（水平または垂直）
• グリッドセクションの折りたたみ／展開機能を追加する
• ユーザー操作でグリッドの行や列を動的にサイズ変更できるようにする
• スプリッターの移動時のドラッグ動作を設定する
• テンプレートやスタイルを使ってスプリッターの外観をカスタマイズする
• 増分値を設定してキーボードによるサイズ変更に対応する
• 独立してサイズ変更できるセクションを備えた複数ペインのレイアウトを作成する

このスキルでは、基本設定から高度なカスタマイズまで、GridSplitter の実装全般を扱います。

コンポーネントの概要

SfGridSplitter は、操作可能なスプリッターバーで Grid 内の利用可能な領域を分割するレイアウトコントロールです。主な機能は次のとおりです。

• 動的なサイズ変更： 移動可能なスプリッターで、必要に応じてグリッドの行や列の領域を再配分します
• 方向のサポート： グリッド内の配置に応じて、水平または垂直に分割します
• 折りたたみ／展開： パネルを対話的に非表示／表示にするボタンを標準で備えています
• プレビュー モード： 適用前にサイズ変更操作をプレビューできます
• カスタマイズ可能なテンプレート： グリッパー、折りたたみボタン、プレビューの外観を細かく制御できます
• キーボードのサポート： 増分値を設定してキーボードでサイズ変更できます
• 結合セルのサポート： 結合されたグリッドの行や列でも動作します

一般的な用途：

• サイズ変更可能なセクションを備えたマスター／詳細ビュー
• 折りたたみ可能なサイドパネルを備えたコードエディター
• 分割位置を調整できるツリー／グリッドを備えたデータエクスプローラー
• サイズ変更可能なペインを備えた複数ドキュメントインターフェイス

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

はじめに

📄 参照： references/getting-started.md

SfGridSplitter の追加と設定の基本を学びます。

• アセンブリの配置と NuGet パッケージのインストール
• 名前空間をインポートして XAML にコントロールを追加する方法
• C# でプログラムからコントロールを追加する方法
• 行／列レイアウトでの基本的なグリッドスプリッターの設定
• 初期設定と配置要件

このリファレンスを使用する場面： GridSplitter を初めて設定するとき、必要なアセンブリを追加するとき、または基本的な分割レイアウトを作成するとき。

サイズ変更とレイアウト操作

📄 参照： references/resize-and-layout.md

グリッドのサイズ変更機能とレイアウト設定を習得します。

• 水平スプリッターによるグリッド行のサイズ変更
• 垂直スプリッターによるグリッド列のサイズ変更
• ResizeBehavior プロパティ（PreviousAndNext、PreviousAndCurrent など）
• ピクセル単位で精密にサイズ変更するための DragIncrement と KeyboardIncrement
• プログラムからサイズ変更する MoveSplitter() メソッド
• 結合された列や行の操作
• 方向の処理と配置方法

このリファレンスを使用する場面： サイズ変更動作を設定するとき、プログラムによるサイズ変更を実装するとき、結合セルを操作するとき、またはドラッグ／キーボードの増分値を細かく調整するとき。

折りたたみ／展開機能

📄 参照： references/collapse-expand-features.md

対話的な折りたたみ／展開機能を実装します。

• ボタンの表示／非表示を切り替える EnableCollapseButton プロパティ
• グリッドの行や列の折りたたみと展開
• カスタム折りたたみボタンテンプレート（Up、Down、Left、Right）
• 水平スプリッター用の UpButtonTemplate と DownButtonTemplate
• 垂直スプリッター用の LeftButtonTemplate と RightButtonTemplate
• パネルの表示／非表示を切り替えるユーザー操作のパターン

このリファレンスを使用する場面： 折りたたみ／展開ボタンを追加するとき、ボタンの外観をカスタマイズするとき、またはパネルの表示／非表示機能を実装するとき。

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

📄 参照： references/customization-styling.md

外観と動作をカスタマイズします。

• スプリッターの色を指定する Background プロパティ
• 水平方向のスプリッターグリッパー用 HorizontalGripperTemplate
• 垂直方向のスプリッターグリッパー用 VerticalGripperTemplate
• 遅延リサイズのプレビュー用 PreviewStyle
• プレビューモード用 ShowsPreview プロパティ
• テンプレートを使ったカスタムドラッグプレビュー UI
• 高度なスタイル設定のシナリオとテーマの統合

このリファレンスは次の場合に使用します： スプリッターの外観をカスタマイズする場合、カスタムグリッパーデザインを作成する場合、プレビュースタイルを実装する場合、またはアプリケーションのテーマに合わせる場合。

クイックスタート

水平方向のスプリッターの場合：RowDefinitions（*, Auto, ）を含む Grid を作成し、中央の行に Height="5" と ResizeBehavior="PreviousAndNext" を指定した SfGridSplitter を配置します。垂直方向のスプリッターの場合：ColumnDefinitions（, Auto, *）を作成し、代わりに Width を設定します。完全な例については、はじめにを参照してください。

よくあるパターン

主なパターンには、折りたたみボタン（EnableCollapseButton）、プレビューモード（ShowsPreview）、プログラムによるリサイズ（MoveSplitter）、複数のスプリッターを使ったレイアウト、DragIncrement/KeyboardIncrement による制約付きリサイズがあります。実装例と使用するタイミングについては、各リファレンスファイルを参照してください。

主なプロパティ

プロパティ	型	目的	使用するタイミング
ResizeBehavior	ResizeBehavior	リサイズの影響を受ける行／列を制御します	リサイズ対象のパネルに応じて、PreviousAndNext（最も一般的）、PreviousAndCurrent、または CurrentAndNext を設定します
EnableCollapseButton	bool	折りたたみ／展開ボタンを表示または非表示にします	ユーザーがパネルを一時的に非表示にする必要がある場合に有効にします
ShowsPreview	bool	適用前のリサイズプレビューを表示します	レイアウトが複雑な場合や、視覚的な確認が必要な場合に有効にします
DragIncrement	double	マウス操作によるリサイズのピクセル間隔です	リサイズを特定の間隔に制限する場合に設定します（既定値：1）
KeyboardIncrement	double	キーボード操作によるリサイズのピクセル間隔です	矢印キーによるリサイズの刻み幅を設定します（既定値：20）
HorizontalAlignment	HorizontalAlignment	水平方向のスプリッターの配置です	行をリサイズする場合は Stretch を使用します
VerticalAlignment	VerticalAlignment	垂直方向のスプリッターの配置です	列をリサイズする場合は Stretch を使用します
Background	Brush	スプリッターバーの色です	アプリケーションのテーマに合わせてカスタマイズします
Height	double	水平方向のスプリッターバーの高さです	水平方向のスプリッターには、明示的な高さ（例：5～10 ピクセル）を設定します
Width	double	垂直方向のスプリッターバーの幅です	垂直方向のスプリッターには、明示的な幅（例：5～10 ピクセル）を設定します

よくあるユースケース

• コードエディター： EnableCollapseButton とカスタムボタンテンプレートを使用した、折りたたみ可能なサイドパネルを備える IDE スタイルのレイアウト。
• データエクスプローラー： ShowsPreview と ResizeBehavior を使用した、クエリビューと結果ビューのサイズを調整できるデータベースツール。
• マスター詳細： 基本的なリサイズと DragIncrement を使用した、サイズを変更できるリスト詳細インターフェース。
• マルチドキュメントインターフェース： 複数のスプリッターとセル結合のサポートを使用した、複数のリサイズ可能なドキュメントペイン。
• ダッシュボードウィジェット： DragIncrement とプリセット設定を使用した、サイズを調整できるウィジェットコンテナーを備える分析ダッシュボード。

トラブルシューティングのクイックリファレンス

スプリッターでパネルをリサイズできない場合

• Grid.Row/Grid.Column の配置を確認します
• HorizontalAlignment/VerticalAlignment の設定を確認します
• ResizeBehavior が適切に設定されていることを確認します

折りたたみボタンが表示されない場合

• EnableCollapseButton="True" を設定します
• ボタンを表示するのに十分なサイズがスプリッターにあることを確認します

プレビューが表示されない場合

• ShowsPreview="True" を設定します
• カスタムスタイルを使用している場合は PreviewStyle を確認します

リサイズがぎくしゃくする場合

• DragIncrement を調整して、動きを滑らかにします
• レイアウトが複雑な場合は ShowsPreview の使用を検討します

実装方法の詳細な説明と高度なシナリオについては、上記の詳細なリファレンスファイルを参照してください。