syncfusion-wpf-propertygrid

PropertyGrid の実装

Syncfusion® WPF PropertyGrid コントロールを実装するためのガイドです。カスタムエディター、カテゴリエディター、コレクション編集、グループ化、並べ替え、フィルタリング、ネストされたプロパティに対応した、オブジェクトのプロパティを参照および編集するための強力なプロパティインスペクターです。

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

次のような場合にこのスキルを使用します。

• オブジェクトのプロパティを表示して参照および編集する
• Visual Studio のプロパティウィンドウに似たプロパティインスペクターを作成する
• 特定のプロパティ型に対応するカスタム値エディターを作成する
• プロパティを整理しやすくするためにグループ化および分類する
• 追加、削除、編集機能を備えたコレクションプロパティを編集する
• プロパティを動的にフィルタリングおよび検索する
• 展開可能なプロパティ項目でネストされたプロパティに対応する
• 説明、表示名、ツールチップを使ってプロパティの表示をカスタマイズする
• ビジュアル構成ツール向けのデザイン時エディターを実装する
• アプリケーション設定用の構成パネルを構築する

このスキルでは、基本的な設定、プロパティのバインド、エディター、整理、高度なカスタマイズを含む、PropertyGrid の実装全体を扱います。

コンポーネントの概要

必要なアセンブリ：

• Syncfusion.PropertyGrid.WPF
• Syncfusion.SfInput.WPF
• Syncfusion.SfShared.WPF
• Syncfusion.Shared.WPF
• Syncfusion.Tools.WPF

XAML 名前空間：

xmlns:syncfusion="http://schemas.syncfusion.com/wpf"

PropertyGrid コントロールは、あらゆるオブジェクトのプロパティを参照および編集するためのインターフェイスを、次の機能とともに提供します。

• プロパティの自動検出 - あらゆるオブジェクトのプロパティを自動的にリフレクションで取得します
• カスタム値エディター - 特定のプロパティを編集するためのカスタムコントロールを割り当てます
• カテゴリエディター - 関連するプロパティをカスタム編集 UI でグループ化します
• コレクションエディター - コレクションプロパティ（List、ObservableCollection）を編集するための組み込みダイアログです
• グループ化と並べ替え - 複数の並べ替えオプションを使って、プロパティをカテゴリ別に整理します
• フィルタリング - プロパティを非表示にし、組み込みの SearchBox で検索します
• ネストされたプロパティ - 複雑なオブジェクトを展開して、ネストされたプロパティを表示します
• Blend 対応 - Blend および Visual Studio でのデザイン時サポート
• テーマ - 一貫したスタイル設定のための組み込みテーマサポート
• MVVM サポート - 完全なデータバインディングとプロパティ変更通知

コントロールの構造

PropertyGrid
├── SearchBox (optional) - Filter properties by name
├── Sort/Group Buttons - Toggle between sorted and categorized views
├── Property List
│   ├── Property Name Column
│   └── Value Editor Column (context-sensitive editors)
└── Description Panel (optional) - Shows property description

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

はじめに

📄 参照： references/getting-started.md

• インストールとアセンブリの配置
• デザイナー、XAML、C# による PropertyGrid の追加
• SelectedObject によるバインド
• プロパティの自動設定
• 基本的な構成と設定
• テーマのサポート

📄 参照： references/overview.md

• コントロールの構造とアーキテクチャ
• 機能の概要と能力
• ユースケースとシナリオ
• PropertyGrid を使用する場面

📄 参照： references/property-binding.md

• SelectedObject のバインド
• データコンテキストの構成
• INotifyPropertyChanged の実装
• ObservableCollection の使用
• 動的なプロパティの更新
• 複数オブジェクトのバインド

エディターとカスタマイズ

📄 参照： references/custom-editors.md

• カスタムエディターの作成（ITypeEditor インターフェイス）
• Editor 属性を使用したエディターの割り当て
• CustomEditorCollection の使用方法
• プロパティ名またはプロパティ型による割り当て
• EditorType プロパティと Editor プロパティ
• パラメーターを受け取るコンストラクター
• Attach/Create/Detach メソッド
• カスタムエディターコントロール

📄 参照： references/category-editors.md

• CategoryEditor の概念
• 関連するプロパティのグループ化
• EditorTemplate のカスタマイズ
• 複数のプロパティの分類
• 可視性コンバーター
• カスタムカテゴリーレイアウト

📄 参照： references/collection-editor.md

• コレクションプロパティ（List、ObservableCollection）の編集
• 項目の追加／削除ダイアログ
• SelectedObject としてのコレクションの編集
• ネストされたコレクションの編集
• 読み取り専用モードの設定
• CollectionEditorOpening イベント
• IList 型の要件

📄 参照： references/custom-property-definition.md

• PropertyItem の手動定義
• PropertyGridItem の設定
• AutoGenerateItems プロパティ
• 実行時の項目の追加／削除
• DisplayName、Description、CategoryName のカスタマイズ
• カスタムエディターとネストされたプロパティ
• 説明パネルのテンプレート

整理機能

📄 参照： references/grouping.md

• EnableGrouping プロパティ
• Category 属性によるグループ化
• グループの外観のカスタマイズ
• グループの展開／折りたたみ動作
• グループボタンの表示設定

📄 参照： references/sorting.md

• SortDirection プロパティ（Ascending、Descending、Null）
• プロパティ名による並べ替え
• カテゴリーの並べ替え
• カスタム順序指定のための Order 属性
• 並べ替えボタン用の ButtonPanelVisibility
• 並べ替えの無効化

📄 参照： references/filtering.md

• プロパティを非表示にする HidePropertiesCollection
• Browsable 属性（false で非表示）
• Bindable 属性（false で非表示）
• Display.AutoGenerateField 属性
• AutoGeneratingPropertyGridItem イベント
• 名前で絞り込む SearchBox
• SearchBoxVisibility プロパティ

📄 参照： references/nested-properties.md

• PropertyExpandMode（FlatMode と NestedMode）
• NestedPropertyDisplayMode プロパティ
• 複雑なオブジェクトのプロパティの展開
• フォーカスを失ったときに値を更新
• ネストされたプロパティの手動定義

外観と動作

📄 参照： references/appearance.md

• ビジュアルスタイルとテーマ
• プロパティ名／値の外観
• 説明パネルのカスタマイズ
• DescriptionPanelVisibility プロパティ
• グリッド線と間隔
• 色のカスタマイズ

📄 参照： references/attached-properties.md

• WPF 添付プロパティの使用
• PropertyGrid 固有の添付プロパティ
• 設定例

📄 参照： references/keyboard-navigation.md

• キーボードショートカット
• プロパティ間のタブ移動
• Enter／Escape キーの動作
• フォーカス管理

📄 参照： references/localization.md

• ローカライズのサポート
• リソースファイルの設定
• カルチャ固有の文字列
• 組み込みテキストのカスタマイズ

📄 参照： references/virtualization.md

• VirtualizingMode プロパティ
• 大量のプロパティセットに対するパフォーマンス最適化
• メモリ管理
• スクロール動作

クイックスタートの例

基本的な PropertyGrid の設定

<Window x:Class="PropertyGridSample.MainWindow"
        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:PropertyGrid Name="propertyGrid1" 
                                 SelectedObject="{Binding SelectedEmployee}"
                                 Width="400" Height="500">
            <syncfusion:PropertyGrid.DataContext>
                <local:ViewModel/>
            </syncfusion:PropertyGrid.DataContext>
        </syncfusion:PropertyGrid>
    </Grid>
</Window>

// Employee class to be explored in PropertyGrid
public class Employee : INotifyPropertyChanged
{
    private string name;
    public string Name 
    { 
        get => name; 
        set { name = value; OnPropertyChanged(nameof(Name)); } 
    }
    
    [Display(Name = "Employee ID")]
    [Description("Unique identifier for the employee")]
    public string ID { get; set; }
    
    [Category("Personal Info")]
    [DisplayName("Date of Birth")]
    public DateTime DOB { get; set; }
    
    [Category("Personal Info")]
    [Range(18, 65)]
    public int Age { get; set; }
    
    [Browsable(false)] // Hide this property
    public string InternalCode { get; set; }
    
    public event PropertyChangedEventHandler PropertyChanged;
    protected void OnPropertyChanged(string propertyName) =>
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
}

// ViewModel
public class ViewModel
{
    public object SelectedEmployee { get; set; }
    
    public ViewModel()
    {
        SelectedEmployee = new Employee
        {
            Name = "Johnson",
            Age = 25,
            ID = "EMP001",
            DOB = new DateTime(1999, 5, 15)
        };
    }
}

よくあるパターン

パターン 1：Email プロパティ用のカスタムエディター

// Custom Editor with email validation mask
public class EmailEditor : ITypeEditor
{
    SfMaskedEdit maskedEdit;
    
    public object Create(PropertyInfo propertyInfo)
    {
        maskedEdit = new SfMaskedEdit
        {
            MaskType = MaskType.RegEx,
            Mask = "[A-Za-z0-9._%-]+@[A-Za-z0-9]+.[A-Za-z]{2,3}"
        };
        return maskedEdit;
    }
    
    public void Attach(PropertyViewItem property, PropertyItem info)
    {
        var binding = new Binding("Value")
        {
            Mode = BindingMode.TwoWay,
            Source = info,
            ValidatesOnExceptions = true,
            ValidatesOnDataErrors = true
        };
        BindingOperations.SetBinding(maskedEdit, SfMaskedEdit.ValueProperty, binding);
    }
    
    public void Detach(PropertyViewItem property) { }
}

// Apply to property
public class Employee
{
    [Editor("EmailID", typeof(EmailEditor))]
    public string EmailID { get; set; }
}

パターン 2：カテゴリー別のプロパティのグループ化

public class Employee
{
    [Category("Basic Info")]
    public string Name { get; set; }
    
    [Category("Basic Info")]
    public string ID { get; set; }
    
    [Category("Contact Details")]
    public string Email { get; set; }
    
    [Category("Contact Details")]
    public string Phone { get; set; }
}

<syncfusion:PropertyGrid SelectedObject="{Binding Employee}"
                         EnableGrouping="True"/>

パターン 3：コレクションプロパティの編集

public class Product
{
    public string ProductName { get; set; }
    
    // Collection property - automatically gets collection editor
    public ObservableCollection<Customer> Customers { get; set; }
    
    public Product()
    {
        Customers = new ObservableCollection<Customer>
        {
            new Customer { ID = 1, Name = "John" },
            new Customer { ID = 2, Name = "Jane" }
        };
    }
}

public class Customer
{
    public int ID { get; set; }
    public string Name { get; set; }
}

パターン 4：実行時の PropertyItem の上書き

private void PropertyGrid_AutoGeneratingPropertyGridItem(
    object sender, AutoGeneratingPropertyGridItemEventArgs e)
{
    // Hide specific properties
    if (e.DisplayName == "InternalCode")
    {
        e.Cancel = true;
    }
    
    // Make property readonly
    if (e.DisplayName == "ID")
    {
        e.ReadOnly = true;
    }
    
    // Change display name
    if (e.DisplayName == "DOB")
    {
        e.DisplayName = "Date of Birth";
    }
    
    // Change category
    if (e.DisplayName == "Age")
    {
        e.Category = "Personal Information";
    }
}

パターン 5：プロパティ値変更の通知

private void PropertyGrid_ValueChanged(object sender, ValueChangedEventArgs e)
{
    var changedProperty = e.Property;
    var oldValue = e.OldValue;
    var newValue = e.NewValue;
    
    // Log the change
    Console.WriteLine($"{changedProperty.Name} changed from {oldValue} to {newValue}");
    
    // React to specific property changes
    if (changedProperty.Name == "Age")
    {
        // Validate or update related properties
    }
}

主なプロパティ

コアプロパティ

プロパティ	型	説明
SelectedObject	object	プロパティを表示するオブジェクト
SelectedObjects	object[]	共通のプロパティ編集を行う複数のオブジェクト
EnableGrouping	bool	プロパティをカテゴリ別にグループ化します
SortDirection	ListSortDirection?	プロパティを並べ替えます（Ascending、Descending、null）
PropertyExpandMode	PropertyExpandModes	複雑なオブジェクトのFlatModeまたはNestedMode
AutoGenerateItems	bool	プロパティ項目を自動生成します（デフォルト：true）

UI の設定

プロパティ	型	説明
SearchBoxVisibility	Visibility	検索ボックスを表示／非表示にします
ButtonPanelVisibility	Visibility	並べ替え／グループ化ボタンを表示／非表示にします
DescriptionPanelVisibility	Visibility	説明パネルを表示／非表示にします
EnableToolTip	bool	プロパティ項目のツールチップを有効にします
DisableAnimationOnObjectSelection	bool	読み込みアニメーションを無効にします

コレクション

プロパティ	型	説明
HidePropertiesCollection	ObservableCollection	非表示にするプロパティ名
CustomEditorCollection	CustomEditorCollection	プロパティ用のカスタムエディター
Items	PropertyGridItemCollection	手動で定義したプロパティ項目

イベント

イベント	説明
AutoGeneratingPropertyGridItem	プロパティ項目の作成時に発生します（キャンセルまたは変更できます）
ValueChanged	プロパティ値の変更時に発生します
SelectedPropertyItemChanged	選択中のプロパティの変更時に発生します
CollectionEditorOpening	コレクションエディターを開く前に発生します（キャンセルまたは読み取り専用に設定できます）

一般的なユースケース

1. アプリケーション設定エディター

カテゴリ（外観、動作、パフォーマンス）ごとにグループ化して、アプリケーションの設定を表示および編集します。

2. デザイン時プロパティインスペクター

カスタムコントロールやコンポーネントのビジュアルデザイナーを作成し、プロパティを編集します。

3. 開発ツールのオブジェクトインスペクター

実行時にオブジェクトのプロパティを表示および変更するデバッグツールや検査ツールを構築します。

4. 動的な設定パネル

手動でフォームを設計することなく、データモデルクラスから設定 UI を自動生成します。

5. 複雑なオブジェクトを扱うデータ入力フォーム

コレクションを含むネストされたオブジェクトのプロパティを表示し、階層データを編集できるようにします。

6. レポートパラメーターの設定

ユーザーが各データ型に適したエディターを使って、レポートのパラメーターを設定できるようにします。

7. ゲーム／アプリケーションのアセットエディター

ベクトル、色、リソース用のカスタムエディターを使って、ゲームオブジェクト、シーン、アセットのプロパティを編集します。

8. ビジネスルールの設定

プロパティベースの設定と検証を使って、ビジネスルールを定義および編集します。

関連コンポーネント

• PropertyGridItem - 個々のプロパティ項目の表現
• CustomEditor - カスタム値エディターの設定
• CategoryEditor - カテゴリベースのプロパティのグループ化
• Collection Editor - 組み込みのコレクション編集ダイアログ

ベストプラクティス

1. メタデータには属性を使用する

   • プロパティに [Category]、[Description]、[DisplayName] 属性を適用します
   • コードによるフィルタリングではなく、[Browsable(false)] を使用してプロパティを非表示にします

2. INotifyPropertyChanged を実装する

   • データオブジェクトがプロパティ変更通知を実装していることを確認します
   • コレクションプロパティには ObservableCollection を使用します

3. 複合型にはカスタムエディターを使用する

   • 適切な既定のエディターがない型には、カスタムエディターを作成します
   • カスタムエディターの UI を設計する際は、ユーザーエクスペリエンスを考慮します

4. 大きなオブジェクトのパフォーマンス

   • プロパティが多いオブジェクトには仮想化を使用します
   • 入れ子になったプロパティには遅延読み込みを検討します
   • 不要なプロパティは早い段階でフィルタリングします

5. 検証

   • 検証にはデータ注釈（[Required]、[Range] など）を使用します
   • カスタムエディターでは検証エラーを適切に処理します

6. アクセシビリティ

   • カスタムエディターがキーボード操作に対応していることを確認します
   • スクリーンリーダー向けに、意味のある説明を提供します
   • ハイコントラストテーマでテストします

トラブルシューティング

プロパティが表示されない

• [Browsable] 属性が false になっていないことを確認します
• プロパティが HidePropertiesCollection に含まれているか確認します
• プロパティに public getter があることを確認します
• AutoGenerateItems が true であることを確認します

カスタムエディターが適用されない

• エディターが CustomEditorCollection に正しく登録されていることを確認します
• プロパティ名／型が一致していることを確認します
• エディターが ITypeEditor を正しく実装していることを確認します
• Create メソッドが有効なコントロールを返すことを確認します

コレクションエディターが開かない

• コレクション型が IList を継承していることを確認します
• コレクションプロパティに setter があることを確認します
• コレクション型に引数なしコンストラクターがあることを確認します
• CollectionEditorOpening イベントでキャンセルされていないことを確認します

パフォーマンスの問題

• プロパティの数が多い場合は仮想化を有効にします
• 入れ子になったプロパティの深さを減らします
• 不要なプロパティをフィルタリングします
• 自動生成ではなく、手動でプロパティを定義することを検討します

---

次のステップ： 実装のニーズに応じて、上記のリファレンスドキュメントを参照してください。初期設定については getting-started.md から始め、その後、必要に応じてエディターや整理機能を確認してください。