syncfusion-wpf-splitbutton

Syncfusion WPF SplitButton の実装

Syncfusion WPF SplitButton（SplitButtonAdv）は、ボタンとメニューコントロールを組み合わせたものです。ボタンは既定のアクションを実行し、矢印をクリックすると、追加の選択肢を含むドロップダウンリストが表示されます。このコントロールは、主要なアクションと代替オプションの両方が必要なシナリオに最適です。

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

次のことを行う必要がある場合に、このスキルを使用してください。

• WPF スプリットボタンコントロールを実装する：既定のアクションとドロップダウンメニューを設定します
• ボタンとドロップダウンを組み合わせる：複数のアクションから選択できるようにします
• データバインディングされたドロップダウンメニューを作成する：ItemsSource バインディングを使用します
• コマンドパターンを実装する：ICommand と MVVM アーキテクチャを使用します
• ドロップダウンメニュー項目を設定する：アイコン、チェックボックス、カスタム項目を使用します
• スプリットボタンのイベントを処理する：ドロップダウンの開閉や項目のクリックなどを処理します
• サイズモードを適用する：カスタムアイコンを使って Small、Normal、Large を設定します
• スプリットボタンの外観をカスタマイズする：テーマとテンプレートを使用します
• 複数行テキストに対応する：大きなボタンモードで複数行のテキストを表示します
• アクションを有効／無効にする：CanExecute コマンドロジックを使用します

コンポーネントの概要

主な機能

• 2 種類のアクション：メインボタンのアクションと、代替アクション用のドロップダウンメニュー
• データバインディング：MVVM 向けの ItemsSource と DataTemplate を完全にサポートします
• コマンドバインディング：ボタンとメニュー項目で、CanExecute による ICommand のサポートを提供します
• サイズモード：Small（アイコンのみ）、Normal（アイコンとテキスト）、Large（大きなアイコンとテキスト）
• アイコンテンプレート：パスデータ、フォントアイコン、カスタムテンプレートをサポートします
• カスタマイズ可能なメニュー項目：アイコン、チェックボックス、スクロールバー、カスタムコンテンツに対応します
• ドロップダウンの方向：ポップアップの位置を制御します（Left、Right、BottomLeft など）
• イベント：Opening、Opened、Closing、Closed、Click、IsCheckedChanged
• テーマ設定：SfSkinManager による組み込みテーマとカスタムテーマをサポートします
• 複数行テキスト：大きいサイズモードで複数行のラベルを表示します

コントロールの構造

SplitButtonAdv
├── Primary Button (default action)
│   ├── Label (text)
│   ├── Icon (SmallIcon/LargeIcon/IconTemplate)
│   └── Command (ICommand binding)
└── Dropdown Arrow (opens menu)
    └── DropDownMenuGroup (container)
        ├── DropDownMenuItem (standard items)
        │   ├── Header (text)
        │   ├── Icon (image)
        │   ├── IsCheckable (checkbox support)
        │   └── Command (ICommand binding)
        └── MoreItems (custom UIElement items)

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

このスキルでは、必要な情報を段階的に開示します。実装のニーズに応じて、適切なリファレンスファイルを参照してください。

はじめに

📄 参照先： references/getting-started.md

参照する場面：新しいスプリットボタンを設定する場合、基本的な設定が必要な場合

取り上げるトピック：

• インストールとアセンブリの配置（Syncfusion.Shared.WPF）
• デザイナー、XAML、または C# コードでコントロールを追加する方法
• ラベルテキストと基本プロパティの設定
• サイズモード：Small（アイコンのみ）、Normal（アイコンとテキスト）、Large（大きなアイコンとテキスト）
• カスタムアイコン用のアイコンテンプレートとアイコンテンプレートセレクター
• SmallIcon プロパティと LargeIcon プロパティを使用した画像の設定
• アイコンの幅と高さの設定
• Enter キーでアクティブ化する IsDefault モード
• DropDownMenuGroup へのメニュー項目の追加

ドロップダウンメニュー項目の設定

📄 参照先： references/dropdown-menu-items.md

参照する場面：メニュー項目の外観を設定する場合、カスタム項目を追加する場合、スクロールバーを有効にする場合

取り上げるトピック：

• ドロップダウンメニュー項目のアイコン設定
• アイコンバーの表示（IconBarEnabled プロパティ）
• メニュー項目が多い場合のスクロールバーの表示
• チェック可能なドロップダウンメニュー項目（IsCheckable／IsChecked）
• グリッパーによるドロップダウンメニューのサイズ変更（IsResizable）
• MoreItems プロパティによるカスタムドロップダウンメニュー項目の追加
• カスタム項目のアイコンバーの表示（IsMoreItemsIconTrayEnabled）

データバインディング

📄 参照先： references/data-binding.md

参照する場面：MVVM パターンを実装する場合、コレクションをドロップダウン項目にバインドする場合

取り上げるトピック：

• メニュー項目データ用のモデルクラスの作成
• オブザーバブルコレクションを持つビューモデルの作成
• ItemsSource の DropDownMenuGroup へのバインド
• メニュー項目に ItemTemplate と DataTemplate を使用する方法
• データバインディング用の DataContext の設定
• ビューモデルからメニュー項目へのコマンドのバインド
• MVVM 実装の完全な例
• ICommand 用の DelegateCommand パターン

コマンドのバインド

📄 参照先: references/command-binding.md

読むタイミング：コマンドパターンを実装する場合、ボタンやメニュー項目のアクションを処理する場合

説明する内容:

• Command プロパティの概要と ICommand インターフェイス
• CommandParameter を使ったコマンドハンドラーへのデータの受け渡し
• DelegateCommand の実装パターン
• コマンドを SplitButtonAdv のプライマリボタンにバインドする方法
• コマンドをドロップダウンメニュー項目にバインドする方法
• アクションを有効化／無効化するための CanExecute ロジック
• 動的なコマンド状態を実現する RaiseCanExecuteChanged
• NotificationObject を使用したコマンドバインドの完全な例

ドロップダウンの設定とイベント

📄 参照先: references/dropdown-configuration.md

読むタイミング：ドロップダウンの位置を制御する場合、イベントを処理する場合、複数行テキストを有効にする場合

説明する内容:

• ドロップダウンの方向オプション（Left、Right、BottomLeft、BottomRight、TopLeft、TopRight）
• DropDownOpening イベントと DropDownOpened イベント
• DropDownClosing イベントと DropDownClosed イベント
• ボタンおよびメニュー項目の Click イベント
• チェック可能な項目の IsCheckedChanged イベント
• 複数行テキストのサポート（IsMultiLine プロパティ）
• イベントハンドラーの実装パターン

カスタマイズとテーマ設定

📄 参照先: references/customization.md

読むタイミング：テーマを適用する場合、外観をカスタマイズする場合、テンプレートを作成する場合

説明する内容:

• WPF のスタイルとテンプレートの概要
• Expression Blend で外観を編集する方法
• Visual Studio で外観を編集する方法
• ControlTemplate リソースの作成
• SfSkinManager で組み込みテーマを適用する方法
• ThemeStudio を使ったカスタムテーマの作成
• テンプレートリソースの配置先の選択肢

クイックスタートの例

ドロップダウンメニュー付きの基本的な SplitButton

<Window xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:syncfusion="http://schemas.syncfusion.com/wpf">
    <Grid>
        <syncfusion:SplitButtonAdv Label="Colors" 
                                    SizeMode="Normal" 
                                    Click="SplitButton_Click">
            <syncfusion:DropDownMenuGroup>
                <syncfusion:DropDownMenuItem Header="Red" 
                                             Click="MenuItem_Click"/>
                <syncfusion:DropDownMenuItem Header="Green" 
                                             Click="MenuItem_Click"/>
                <syncfusion:DropDownMenuItem Header="Blue" 
                                             Click="MenuItem_Click"/>
            </syncfusion:DropDownMenuGroup>
        </syncfusion:SplitButtonAdv>
    </Grid>
</Window>

using Syncfusion.Windows.Tools.Controls;

private void SplitButton_Click(object sender, RoutedEventArgs e)
{
    MessageBox.Show("Primary action executed");
}

private void MenuItem_Click(object sender, RoutedEventArgs e)
{
    var menuItem = sender as DropDownMenuItem;
    MessageBox.Show($"Selected: {menuItem.Header}");
}

よくあるパターン

パターン 1：MVVM を使用したデータバインド SplitButton

<syncfusion:SplitButtonAdv Label="Country" SizeMode="Normal">
    <syncfusion:DropDownMenuGroup ItemsSource="{Binding Countries}">
        <syncfusion:DropDownMenuGroup.ItemTemplate>
            <DataTemplate>
                <syncfusion:DropDownMenuItem 
                    Header="{Binding Name}"
                    Command="{Binding DataContext.SelectCountryCommand, 
                             RelativeSource={RelativeSource AncestorType=syncfusion:SplitButtonAdv}}"
                    CommandParameter="{Binding}">
                    <syncfusion:DropDownMenuItem.Icon>
                        <Image Source="{Binding FlagIcon}"/>
                    </syncfusion:DropDownMenuItem.Icon>
                </syncfusion:DropDownMenuItem>
            </DataTemplate>
        </syncfusion:DropDownMenuGroup.ItemTemplate>
    </syncfusion:DropDownMenuGroup>
</syncfusion:SplitButtonAdv>

パターン 2：CanExecute を使用したコマンドのバインド

public class ViewModel : NotificationObject
{
    private bool _canPerformAction = true;
    
    public DelegateCommand<object> ClickCommand { get; set; }
    
    public bool CanPerformAction
    {
        get => _canPerformAction;
        set
        {
            _canPerformAction = value;
            ClickCommand.RaiseCanExecuteChanged();
            RaisePropertyChanged(nameof(CanPerformAction));
        }
    }
    
    public ViewModel()
    {
        ClickCommand = new DelegateCommand<object>(
            ExecuteAction, 
            CanExecuteAction);
    }
    
    private bool CanExecuteAction(object parameter) => CanPerformAction;
    
    private void ExecuteAction(object parameter)
    {
        MessageBox.Show($"Action executed: {parameter}");
    }
}

<syncfusion:SplitButtonAdv Label="Action" 
                            Command="{Binding ClickCommand}"
                            CommandParameter="Primary Action">
    
</syncfusion:SplitButtonAdv>

パターン 3：アイコンテンプレート付きの大型ボタン

<Window.Resources>
    <DataTemplate x:Key="customIconTemplate">
        <Grid Width="32" Height="32">
            <Path Data="M10,0 L20,10 L10,20 L0,10 Z" 
                  Fill="#FF3A3A38" 
                  Stretch="Fill"/>
        </Grid>
    </DataTemplate>
</Window.Resources>

<syncfusion:SplitButtonAdv Label="Custom Icon" 
                            SizeMode="Large"
                            IconTemplate="{StaticResource customIconTemplate}">
    
</syncfusion:SplitButtonAdv>

パターン 4：チェック可能な項目を含むスクロール可能なドロップダウン

<syncfusion:SplitButtonAdv Label="Options" SizeMode="Normal">
    <syncfusion:DropDownMenuGroup MaxHeight="200" 
                                    ScrollBarVisibility="Visible"
                                    IconBarEnabled="True">
        <syncfusion:DropDownMenuItem Header="Option 1" 
                                     IsCheckable="True" 
                                     IsChecked="True"/>
        <syncfusion:DropDownMenuItem Header="Option 2" 
                                     IsCheckable="True"/>
        <syncfusion:DropDownMenuItem Header="Option 3" 
                                     IsCheckable="True"/>
        
    </syncfusion:DropDownMenuGroup>
</syncfusion:SplitButtonAdv>

主なプロパティ

SplitButtonAdv のプロパティ

プロパティ	型	説明
Label	string	ボタンに表示されるテキスト
SizeMode	SizeMode	サイズモード：Small、Normal、Large
SmallIcon	ImageSource	Small／Normal モード用のアイコン
LargeIcon	ImageSource	Large モード用のアイコン
IconTemplate	DataTemplate	カスタムアイコンテンプレート（SmallIcon／LargeIcon を上書き）
IconTemplateSelector	DataTemplateSelector	アイコンテンプレートの動的な選択
IconWidth	double	アイコンの幅
IconHeight	double	アイコンの高さ
Command	ICommand	プライマリボタンのクリック時に実行するコマンド
CommandParameter	object	Command に渡すパラメーター
DropDirection	DropDirection	ポップアップの位置：Left、Right、BottomLeft など
IsMultiLine	bool	Large モードで複数行テキストを有効化
IsDefault	bool	Enter キーでボタンをアクティブ化

DropDownMenuGroup のプロパティ

プロパティ	型	説明
ItemsSource	IEnumerable	メニュー項目のデータソース
ItemTemplate	DataTemplate	メニュー項目の表示テンプレート
IconBarEnabled	bool	縦型アイコンバーの表示／非表示
ScrollBarVisibility	ScrollBarVisibility	長いリストのスクロールバーの表示設定
IsResizable	bool	ポップアップのサイズ変更用グリッパーを有効化
MaxHeight	double	ドロップダウンポップアップの最大の高さ
MoreItems	ObservableCollection	メニューの下部に表示するカスタム項目
IsMoreItemsIconTrayEnabled	bool	カスタム項目用のアイコンバー

DropDownMenuItem のプロパティ

プロパティ	型	説明
Header	object	メニュー項目のテキストまたはコンテンツ
Icon	object	ヘッダーの前に表示されるアイコン
IsCheckable	bool	項目のチェックボックスを有効にします
IsChecked	bool	項目のチェック状態
Command	ICommand	メニュー項目のクリック時に実行するコマンド
CommandParameter	object	Command に渡されるパラメーター

一般的なユースケース

ユースケース 1：形式オプション付きの保存ボタン

主な操作では既定の形式で保存し、ドロップダウンには別の形式（PDF、Excel、CSV）が表示されます。

ユースケース 2：宛先オプション付きの送信ボタン

主な操作では既定の宛先に送信し、ドロップダウンには別の宛先が表示されます。

ユースケース 3：プリセットフィルター付きのフィルターボタン

主な操作では最後に使用したフィルターを適用し、ドロップダウンには利用可能なフィルターのプリセットが表示されます。

ユースケース 4：エクスポート形式付きのエクスポートボタン

主な操作では既定の形式でエクスポートし、ドロップダウンにはさまざまなエクスポート形式が表示されます。

トラブルシューティングのヒント

問題： アイコンが正しく表示されない
解決策： アイコンの優先順位（IconTemplate > LargeIcon > SmallIcon）を確認してください。正しいサイズモードが設定されていることを確認してください。

問題： コマンドが実行されない
解決策： CanExecute が true を返すことを確認してください。RelativeSource の DataContext バインディングを確認してください。

問題： ドロップダウン項目が表示されない
解決策： DropDownMenuGroup に DropDownMenuItem 要素が含まれていることを確認してください。ItemTemplate のバインディングを確認してください。

問題： イベントが発生しない
解決策： コードビハインド内のイベントハンドラー名が一致していることを確認してください。Opening/Closing イベントでキャンセルされていないか確認してください。

追加リソース

• GitHub のサンプル
• Syncfusion WPF ドキュメント
• コントロールの依存関係