syncfusion-winforms-group-view

实现 GroupView 控件

GroupView 控件是 Windows Forms 的列表类型控件，用于显示带有文本和图像的项。它提供丰富的外观、行为和交互功能自定义选项，非常适合创建 VS.NET 工具箱风格的界面、OutlookBar 克隆版和导航面板。

何时使用此技能

在以下情况下使用此技能：

• 在 Windows Forms 中显示带有文本和图像的项列表
• 创建 VS.NET 工具箱风格的界面
• 克隆 Microsoft OutlookBar 或 Visual Studio 工具箱窗口
• 实现支持拖放的项列表
• 构建带有突出显示选中项的导航面板
• 将 GroupView 添加为 GroupBar 的客户端控件
• 配置项的外观、颜色和偏移量
• 处理项选择、突出显示和重命名事件
• 创建带有工具提示和上下文菜单的交互式项列表

组件概述

GroupView 控件显示一组 GroupViewItems，每个项都支持：

• 带格式和突出显示的文本标签
• 来自 ImageList 的小图像和大图像
• 交互状态（已选中、已突出显示、正在选择）
• 拖放重新排序
• 就地重命名
• 工具提示和上下文菜单
• 不同状态下的自定义颜色和偏移量
• 水平和垂直方向

主要功能：

• 平面或 3D 外观
• ButtonView，用于显示按下状态
• FlowView，适用于以图像为主的布局
• 集成滚动，适用于大量项
• 提供选择、突出显示、重命名和重新排序事件通知

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 程序集部署（Syncfusion.Shared.Base）
• 通过设计器添加 GroupView
• 通过代码添加 GroupView
• 向 GroupViewItems 集合添加项
• 为小图像和大图像设置 ImageList
• 配置选中项

控件配置

📄 阅读： references/control-settings.md

• 外观设置（FlatLook、BorderStyle）
• 拖放行为
• 项与边框之间的间距
• 集成滚动
• 方向和 FlowView 模式

项自定义

📄 阅读： references/item-customization.md

• 文本突出显示、偏移量和格式
• 项和文本的颜色设置（突出显示、选中状态）
• 图像突出显示、偏移量和间距
• 就地重命名功能

交互功能

📄 阅读： references/interactive-features.md

• ButtonView 和 ClipSelectionBounds
• 工具提示配置
• 上下文菜单实现
• 选择行为

事件

📄 阅读： references/events.md

• GroupViewItemSelected 事件
• GroupViewItemHighlighted 事件
• GroupViewItemRenamed 事件
• GroupViewItemsReordered 事件
• GroupViewItemDoubleClick 事件
• ShowContextMenu 事件

GroupBar 集成

📄 阅读： references/groupbar-integration.md

• 将 GroupView 添加到 GroupBar
• 创建 VS.NET 工具箱界面
• 附加客户端控件

快速入门

基本 GroupView 设置

using Syncfusion.Windows.Forms.Tools;

public class MyForm : Form
{
    private GroupView groupView1;
    private ImageList imageList1;
    
    public MyForm()
    {
        InitializeComponent();
        
        // Create GroupView
        this.groupView1 = new GroupView();
        this.groupView1.Location = new Point(10, 10);
        this.groupView1.Size = new Size(200, 300);
        this.groupView1.FlatLook = true;
        
        // Setup ImageList
        this.imageList1 = new ImageList();
        this.imageList1.Images.Add(Image.FromFile("icon1.png"));
        this.imageList1.Images.Add(Image.FromFile("icon2.png"));
        this.imageList1.Images.Add(Image.FromFile("icon3.png"));
        
        // Assign ImageList
        this.groupView1.SmallImageList = this.imageList1;
        this.groupView1.SmallImageView = true;
        
        // Add items
        this.groupView1.GroupViewItems.AddRange(new GroupViewItem[] {
            new GroupViewItem("My Computer", 0, true, null, "Item0"),
            new GroupViewItem("Network", 1, true, null, "Item1"),
            new GroupViewItem("Recycle Bin", 2, true, null, "Item2")
        });
        
        // Handle selection event
        this.groupView1.GroupViewItemSelected += GroupView1_ItemSelected;
        
        // Add to form
        this.Controls.Add(this.groupView1);
    }
    
    private void GroupView1_ItemSelected(object sender, EventArgs e)
    {
        int selectedIndex = this.groupView1.SelectedItem;
        string selectedText = this.groupView1.GroupViewItems[selectedIndex].Text;
        MessageBox.Show($"Selected: {selectedText}");
    }
}

VS.NET 工具箱风格的界面

// Create toolbox-style GroupView
this.groupView1.FlatLook = true;
this.groupView1.FlowView = true;
this.groupView1.ShowFlowViewItemText = true;
this.groupView1.IntegratedScrolling = true;
this.groupView1.SmallImageView = true;
this.groupView1.AllowDragDrop = true;

// Configure highlighting
this.groupView1.HighlightText = true;
this.groupView1.HighlightImage = true;
this.groupView1.HighlightItemColor = Color.LightBlue;
this.groupView1.HighlightTextColor = Color.DarkBlue;

常见模式

模式 1：动态添加项

// Add single item
GroupViewItem newItem = new GroupViewItem(
    text: "New Item",
    imageIndex: 3,
    visible: true,
    toolTipText: null,
    name: "NewItem1"
);
this.groupView1.GroupViewItems.Add(newItem);

// Add multiple items
this.groupView1.GroupViewItems.AddRange(new GroupViewItem[] {
    new GroupViewItem("Item 1", 0, true, null, "Item1"),
    new GroupViewItem("Item 2", 1, true, null, "Item2"),
    new GroupViewItem("Item 3", 2, true, null, "Item3")
});

模式 2：配置突出显示和选择

// Enable highlighting
this.groupView1.HighlightText = true;
this.groupView1.HighlightImage = true;

// Set highlight colors
this.groupView1.HighlightItemColor = Color.LightGray;
this.groupView1.HighlightTextColor = Color.Black;

// Set selection colors
this.groupView1.SelectedItemColor = Color.Navy;
this.groupView1.SelectedTextColor = Color.White;
this.groupView1.SelectedHighlightItemColor = Color.Blue;
this.groupView1.SelectedHighlightTextColor = Color.Yellow;

模式 3：拖放配置

// Enable drag-and-drop
this.groupView1.AllowDragDrop = true;
this.groupView1.AllowDragAnyObject = true;

// Handle reorder event
this.groupView1.GroupViewItemsReordered += (sender, e) => {
    // Items have been reordered
    UpdateItemPositions();
};

模式 4：就地重命名

// Enable in-place renaming for specific item
int itemIndexToRename = 2;
this.groupView1.InplaceRenameItem(itemIndexToRename);

// Handle rename event
this.groupView1.GroupViewItemRenamed += (sender, e) => {
    GroupItemRenamedEventArgs args = (GroupItemRenamedEventArgs)e;
    MessageBox.Show($"Renamed from '{args.OldLabel}' to '{args.NewLabel}'");
};

模式 5：上下文菜单实现

// Handle ShowContextMenu event
this.groupView1.ShowContextMenu += GroupView1_ShowContextMenu;

private void GroupView1_ShowContextMenu(object sender, EventArgs e)
{
    ContextMenuStrip menu = new ContextMenuStrip();
    
    // Add menu items
    menu.Items.Add("Add New Item", null, AddNewItem_Click);
    menu.Items.Add("Remove Item", null, RemoveItem_Click);
    menu.Items.Add(new ToolStripSeparator());
    menu.Items.Add("Properties", null, Properties_Click);
    
    // Check if mouse is over an item
    if (this.groupView1.ContextMenuItem != -1)
    {
        menu.Items[1].Enabled = true; // Enable Remove
    }
    else
    {
        menu.Items[1].Enabled = false; // Disable Remove
    }
    
    // Show context menu
    menu.Show(this.groupView1, this.groupView1.PointToClient(Cursor.Position));
}

主要属性

核心属性

• GroupViewItems - 控件中显示的项集合
• SelectedItem - 当前选中项的索引
• HighlightedItem - 当前突出显示项的索引
• ContextMenuItem - 鼠标下方项的索引，用于显示上下文菜单

外观属性

• FlatLook - 移除项的 3D 边缘效果
• BorderStyle - 控件的边框样式
• SmallImageView - 使用小图像显示项
• FlowView - 以流式布局模式显示项

行为属性

• AllowDragDrop - 启用拖放功能
• IntegratedScrolling - 启用溢出时的滚动
• Orientation - 水平或垂直排列项
• ButtonView - 以按下状态显示所选项

图像属性

• SmallImageList - 用于小图标（16x16）的 ImageList
• LargeImageList - 用于大图标（32x32）的 ImageList
• HighlightImage - 启用鼠标悬停时的图像高亮
• ImageSpacing - 图像边缘与项边缘之间的间距

文本属性

• HighlightText - 启用鼠标悬停时的文本高亮
• TextWrap - 换行显示长文本
• TextUnderline - 为项文本添加下划线
• TextSpacing - 文本与其他元素之间的间距

颜色属性

• HighlightItemColor - 鼠标悬停在项上时的颜色
• HighlightTextColor - 鼠标悬停时的文本颜色
• SelectedItemColor - 所选项的背景色
• SelectedTextColor - 所选项的文本颜色

常见用例

用例 1：导航面板

使用图标和文本显示应用程序的各个部分，用户可通过点击项进行导航。

用例 2：工具面板

创建类似 VS.NET 工具箱的面板，用户可从分类列表中选择工具或组件。

用例 3：文件浏览器

构建文件/文件夹浏览器，使用图标表示不同的文件类型，并支持拖放操作。

用例 4：设置菜单

显示带图标的分层设置类别，方便快速访问配置选项。

用例 5：仪表板小组件

展示仪表板小组件选项，用户可选择并将其拖到画布上。

故障排除

问题： 图像未显示

• 确认已将 ImageList 分配给 SmallImageList 或 LargeImageList
• 确保 SmallImageView 设置为 true，以显示小图像
• 检查 GroupViewItem.ImageIndex 是否与 ImageList 中的有效索引匹配

问题： 事件未触发

• 确认已正确订阅事件处理程序
• 检查控件是否已添加到窗体的 Controls 集合中
• 确保 GroupViewItems 集合中存在项

问题： 拖放不起作用

• 将 AllowDragDrop 设置为 true
• 对于外部对象，可考虑使用 AllowDragAnyObject
• 如果从外部源拖动，请确认窗体允许放置操作

问题： 选择状态不可见

• 配置 SelectedItemColor 和 SelectedTextColor
• 将 ButtonView 设置为 true，以显示按下状态
• 检查 ClipSelectionBounds 属性的选择边框设置