C#中PropertyGrid控件使用方法详解(添加控件、绑定对象、自定义属性显示及分组等)

PropertyGrid 是 WinForms 中用于浏览和编辑对象属性的内置控件，常用于配置面板、参数设置、调试工具等场景。它会自动读取对象的公共属性，并以网格形式展示，同时支持分组、描述、只读、隐藏等自定义配置。

一、添加 PropertyGrid 控件

在 Visual Studio 中，可以先在工具箱中找到 PropertyGrid 控件并拖放到窗体上；如果工具箱中未显示，可在工具箱中右键选择“选择项”，确认 System.Windows.Forms.PropertyGrid 已勾选。

也可以完全通过代码创建：

PropertyGrid propertyGrid1 = new PropertyGrid();
propertyGrid1.Dock = DockStyle.Fill;
this.Controls.Add(propertyGrid1);

常用显示属性包括：ToolbarVisible 控制工具栏是否显示，HelpVisible 控制底部描述栏是否显示，PropertySort 控制按分类或字母排序。

二、绑定对象到 PropertyGrid

PropertyGrid 通过 SelectedObject 属性绑定对象。绑定后，控件会显示该对象的所有可浏览公共属性。

var settings = new AppSettings();
propertyGrid1.SelectedObject = settings;

若需要同时编辑多个对象，可使用 SelectedObjects，但只有这些对象共有的属性才会显示。 绑定后如果属性值在代码中被修改，界面不会立即刷新，通常需要重新赋值 SelectedObject 或调用 Refresh()。

三、自定义属性显示

默认情况下，PropertyGrid 会显示所有公共属性。可以通过 System.ComponentModel 命名空间中的特性进行精细控制：

1. [Browsable(false)]：隐藏属性，不显示在网格中。

2. [ReadOnly(true)]：属性可见但不可编辑。

3. [DisplayName("显示名称")]：修改属性在网格中的显示文本。

4. [Description("说明文字")]：鼠标选中属性时，在底部描述栏显示说明。

5. [DefaultValue(10)]：指定默认值，当前值与默认值不同时属性名会以粗体显示。

6. [DefaultProperty("Name")]：标注在类上，指定打开时默认选中的属性。

示例：

public class AppSettings
{
    [Browsable(false)]
    public string InternalId { get; set; }

    [ReadOnly(true)]
    public string Version => "1.0.0";

    [DisplayName("服务器地址")]
    [Description("应用程序连接的服务器地址")]
    [DefaultValue("localhost")]
    public string Server { get; set; } = "localhost";
}

四、属性分组与高级配置

使用 [Category] 可以对属性进行分组，未设置分组的属性会归入“杂项”。

[Category("连接设置")]
public string Server { get; set; }

[Category("连接设置")]
public int Port { get; set; }

[Category("界面设置")]
public bool EnableDarkMode { get; set; }

如果属性是自定义类或结构体，可以配合 [TypeConverter(typeof(ExpandableObjectConverter))] 使其在网格中展开为子属性。 对于需要特殊编辑界面的属性，可使用 [Editor] 指定自定义 UITypeEditor；对于需要下拉选项或字符串转换的属性，可使用 [TypeConverter] 自定义转换逻辑。

属性变化时可通过 PropertyValueChanged 事件处理验证、联动刷新或持久化保存：

propertyGrid1.PropertyValueChanged += (s, e) =>
{
    // 保存配置或刷新相关界面
};

PropertyGrid 的使用流程可以概括为：添加控件、通过 SelectedObject 绑定对象、使用特性控制显示和分组、按需处理属性变化事件。实际开发中，应优先通过 [Browsable]、[DisplayName]、[Description]、[Category]、[ReadOnly]、[DefaultValue] 等特性完善属性元数据；对复杂类型再考虑 ExpandableObjectConverter 或自定义编辑器。这样既能快速搭建配置界面，也能保持代码与 UI 表现之间的清晰分离。

声明：所有来源为“聚合数据”的内容信息，未经本网许可，不得转载！如对内容有异议或投诉，请与我们联系。邮箱：marketing@think-land.com