WrapPanel Layout

WrapPanel は子要素を水平または垂直方向に並べ、コンテナの端に達したら次の行（または列）に折り返すパネルです。タグクラウド・フォトギャラリー・ツールパレットなどに使われます。

概要

WPF の WrapPanel は子要素を一方向に並べ、コンテナのサイズを超えたら次の行（または列）に折り返すパネルです。StackPanel が折り返しなしの線形配置なのに対し、WrapPanel は自動折り返しを提供します。

Orientation が Horizontal（デフォルト）では子要素を左から右に並べ、行が一杯になったら次の行に移動します。Vertical では上から下に並べ、列が一杯になったら次の列に移動します。

ItemWidth と ItemHeight を設定すると、すべての子要素が同じ幅・高さに統一されます。設定しない場合（デフォルト NaN）は、各子要素が自然なサイズを使用します。

WrapPanel は動的なコンテンツサイズ変化に自動対応するため、ウィンドウリサイズ時にレイアウトが自動調整されます。ただし、StackPanel に比べてレイアウトの計算コストが高いため、パフォーマンスが重要な大量アイテムの表示には仮想化との組み合わせを検討します。

画面キャプチャ

デモしているプロパティ

以下のプロパティが WPF 標準コントロールデモアプリでインタラクティブにデモされています。

プロパティ	設定値	説明
`Orientation`	`Horizontal / Vertical`	タグクラウドやツールパレットのように要素を左から右に並べて折り返したい場合は Horizontal（デフォルト）、縦方向に並べて次の列に折り返したい場合は Vertical を使います。Horizontal では行が一杯になると次の行に移動し、Vertical では列が一杯になると次の列に移動します。WrapPanel の幅が 0 または無限大（ScrollViewer の水平方向など）の場合、折り返しが意図通りに動作しないことがあります。必ず有限の幅（または高さ）が与えられるコンテナ内に配置してください。
`ItemWidth`	`double (NaN = 自動)`	ツールパレットやカラーパレットのようにすべての子要素を同じ幅で均等に並べたいときに設定します。設定すると各子要素が指定した幅にクリップまたは引き伸ばされ、均等な列幅のタイルレイアウトになります。NaN（デフォルト）は各子要素の自然な幅を使用するため、要素ごとにサイズが異なります。子要素のコンテンツが ItemWidth より広い場合はクリップされてコンテンツが見切れることがあります。
`ItemHeight`	`double (NaN = 自動)`	行の高さをすべて揃えたいサムネイルギャラリーなどで使います。設定するとすべての子要素が指定した高さで表示され、行ごとの高さがバラつかなくなります。NaN（デフォルト）は各子要素の自然な高さを使用します。ItemWidth と同様に、コンテンツが ItemHeight より高い場合はクリップされる点に注意してください。

XAML 使用例

<!-- タグクラウド -->
<WrapPanel Margin="8">
  <Border Background="CornflowerBlue" CornerRadius="12"
          Padding="8,4" Margin="4">
    <TextBlock Text="WPF" Foreground="White" />
  </Border>
  <Border Background="MediumSeaGreen" CornerRadius="12"
          Padding="8,4" Margin="4">
    <TextBlock Text=".NET 10" Foreground="White" />
  </Border>
</WrapPanel>

<!-- 均等幅のボタンパレット -->
<WrapPanel ItemWidth="80" ItemHeight="32">
  <Button Content="赤" Background="Red" />
  <Button Content="青" Background="Blue" />
  <Button Content="緑" Background="Green" />
  <Button Content="黄" Background="Yellow" />
</WrapPanel>

主な使用例

タグクラウド — 記事のタグや検索キーワードのリストをバッジ形式で自動折り返し表示します。
フォトサムネイルギャラリー — 写真のサムネイルをコンテナ幅に応じて自動で折り返して表示するギャラリーを実装します。
ツールパレット — 絵描きツールや書式ボタンを WrapPanel に並べて、ウィンドウ幅に合わせて自動整列します。
カテゴリタグフィルター — 複数のフィルタータグを CheckBox や ToggleButton で表示し、折り返しながら列挙するフィルター UI に使用します。
アイコン一覧 — アイコンやシンボルのコレクションを均等サイズ（ItemWidth/ItemHeight）で折り返し表示するパレットを作成します。

ヒントとベストプラクティス

ScrollViewer でラップする — WrapPanel のコンテンツが多い場合に縦スクロールを追加するには ScrollViewer で囲みます。
ItemWidth/ItemHeight で均等サイズに — サイズの揃ったタイルグリッドには ItemWidth と ItemHeight を設定して各要素を均等にします。
UniformGrid との使い分け — 行・列数を明示的に指定する場合は UniformGrid が簡単です。コンテナ幅に応じて動的に折り返したい場合は WrapPanel が適しています。
大量アイテムのパフォーマンス — WrapPanel は仮想化をサポートしません。アイテム数が多い（100以上）場合は VirtualizingStackPanel や WrapPanel の仮想化実装（サードパーティ）を検討します。
Margin でアイテム間のスペーシング — WrapPanel には Gap プロパティがないため、各子要素に Margin を設定してスペーシングを管理します。
WrapPanel を ScrollViewer の水平スクロール内に入れない — 水平スクロールが有効な ScrollViewer の中に Horizontal WrapPanel を置くと、ScrollViewer が無限幅を与えるため折り返しが発生しません。縦スクロールの ScrollViewer（VerticalScrollBarVisibility=Auto）の中に Horizontal WrapPanel を入れる構成が一般的です。
Background とヒットテスト — WrapPanel も Panel を継承しているため、Background が null（デフォルト）の状態では空き領域でのマウスイベントが発生しません。パネル全体にマウスイベントを受け取らせる場合は Background="Transparent" を設定してください。

ソースコード

このデモ画面のソースコードは GitHub で公開しています。

GitHub で WrapPanel のソースコードを見る →