syncfusion-winforms-color-picker

实现颜色选取器（ColorPickerUIAdv）

Windows Forms 应用程序中 Syncfusion ColorPickerUIAdv 控件的实现指南。

概述

ColorPickerUIAdv 控件为 Windows Forms 应用程序提供 Microsoft Word 2007 风格的颜色选择界面。它提供井然有序的颜色组（最近使用、标准、主题）、可自定义的调色板、多种视觉样式，以及可选的“更多颜色”对话框，供用户进行高级颜色选择。

主要功能：

• 颜色组： 最近使用的颜色、标准颜色、主题颜色
• 自定义组： 添加用户定义的颜色集合
• 视觉样式： Office2007、Office2010、Office2016、Metro
• 颜色对话框： “更多颜色”按钮，供用户进行高级选择
• 子项： 颜色变体和色调
• 事件： Picked（选择时）、ItemSelection（悬停时）
• 自动颜色： 可配置的默认颜色按钮
• 运行时选择： 通过对话框动态添加颜色

何时使用此技能

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

• 在 Windows Forms 应用程序中实现颜色选择
• 提供 Microsoft Word 风格的颜色选取器界面
• 将颜色整理到各个组中（最近使用、标准、主题、自定义）
• 允许用户从预定义调色板中选择颜色
• 支持基于主题的颜色选择
• 添加带有 Office 样式的颜色输入控件
• 实现“更多颜色”对话框以进行高级选择
• 在桌面应用程序中处理颜色选择事件
• 为特定领域创建自定义颜色集合

组件功能摘要

功能	说明
颜色组	最近使用、标准、主题和自定义组
子项	每种基色对应的颜色变体／色调
视觉样式	Office2007、Office2010、Office2016、Metro
事件	Picked（选择）、ItemSelection（悬停）
对话框	用于高级选择的“更多颜色”选项
自定义	项目尺寸、间距、标题、边框
运行时	通过对话框动态添加颜色
主题	Office 配色方案（蓝色、银色、黑色）

文档与导航指南

入门

📄 阅读： references/getting-started.md
适用于以下需求：

• 程序集依赖项和 NuGet 包
• 通过设计器或代码添加 ColorPickerUIAdv
• 导入命名空间（Syncfusion.Windows.Forms.Tools）
• 使用 SelectedColor 属性进行基本颜色选择
• 初始设置和配置
• 最小可运行示例

颜色组与组织方式

📄 阅读： references/color-groups.md
适用于以下需求：

• 了解默认组（最近使用、标准、主题）
• 使用 CustomGroups 属性创建自定义颜色组
• 向组中添加颜色项和子项
• 使用 GroupColorItem 和 ColorItem 类
• 配置 IsSubItemsVisible 和 SubItemsDepth
• 设置组名称和标题高度
• 按类别或主题整理颜色

外观与样式

📄 阅读： references/appearance-styling.md
适用于以下需求：

• 应用视觉样式（Office2007、Office2010、Office2016、Metro）
• 配置 Office2007 配色方案（蓝色、银色、黑色）
• 在 Managed 主题中使用自定义颜色
• 使用 ApplyManagedColors 方法设置整个应用的主题
• 边框样式（Fixed3D、FixedSingle、None）
• BorderStyle 和 BorderOffset 属性
• 配置 UseOffice2007Style 属性

事件与运行时选择

📄 阅读： references/events-selection.md
适用于以下需求：

• 在选择颜色时处理 Picked 事件
• 使用 ItemSelection 事件处理悬停交互
• ColorPickedEventArgs 和事件属性
• 运行时颜色选择对话框（“更多颜色”）
• 配置 AutomaticColor 属性
• 使用 ButtonHeight 设置自动按钮尺寸
• 事件驱动的颜色处理模式

自定义和布局

📄 阅读： references/customization.md
适用于以下需求：

• 使用 ColorItemSize 属性设置颜色项大小
• 设置项之间的水平和垂直间距
• 设置 HorizontalItemsSpacing 和 VerticalItemsSpacing
• 使用 TextAlignment 设置标题文本对齐方式
• 自定义组标题字体
• 在属性网格中于设计时编辑颜色
• 使用高级布局和间距选项

快速入门

ColorPickerUIAdv 基本实现

using System;
using System.Drawing;
using System.Windows.Forms;
using Syncfusion.Windows.Forms.Tools;

public partial class ColorPickerForm : Form
{
    private ColorPickerUIAdv colorPickerUIAdv1;
    
    public ColorPickerForm()
    {
        InitializeComponent();
        
        // Create ColorPickerUIAdv
        colorPickerUIAdv1 = new ColorPickerUIAdv();
        colorPickerUIAdv1.Size = new Size(200, 180);
        colorPickerUIAdv1.Location = new Point(20, 20);
        
        // Set initial selected color
        colorPickerUIAdv1.SelectedColor = Color.Blue;
        
        // Apply Office2016 style
        colorPickerUIAdv1.Style = ColorPickerUIAdv.visualstyle.Office2016Colorful;
        
        // Handle color selection
        colorPickerUIAdv1.Picked += ColorPickerUIAdv1_Picked;
        
        // Add to form
        this.Controls.Add(colorPickerUIAdv1);
    }
    
    private void ColorPickerUIAdv1_Picked(object sender, 
                                          ColorPickerUIAdv.ColorPickedEventArgs args)
    {
        // Update form background with selected color
        this.BackColor = args.Color;
        MessageBox.Show($"Selected Color: {args.Color.Name}");
    }
}

程序集要求

必需程序集：

• Syncfusion.Grid.Base
• Syncfusion.Grid.Windows
• Syncfusion.Shared.Base
• Syncfusion.Shared.Windows
• Syncfusion.Tools.Base
• Syncfusion.Tools.Windows

NuGet 包：

Install-Package Syncfusion.Tools.Windows

常见模式

模式 1：使用事件处理程序选择颜色

// Setup
private void SetupColorPicker()
{
    colorPickerUIAdv1.SelectedColor = Color.White;
    colorPickerUIAdv1.Picked += OnColorPicked;
}

// Event handler
private void OnColorPicked(object sender, ColorPickerUIAdv.ColorPickedEventArgs e)
{
    // Apply color to target control
    targetLabel.ForeColor = e.Color;
    
    // Or update drawing operations
    currentBrush = new SolidBrush(e.Color);
    canvas.Invalidate();
}

模式 2：应用 Office2016 主题

// Office2016 Colorful style
colorPickerUIAdv1.Style = ColorPickerUIAdv.visualstyle.Office2016Colorful;

// Or Office2016 White
colorPickerUIAdv1.Style = ColorPickerUIAdv.visualstyle.Office2016White;

// Or Office2016 Black
colorPickerUIAdv1.Style = ColorPickerUIAdv.visualstyle.Office2016Black;

// Or Office2016 DarkGray
colorPickerUIAdv1.Style = ColorPickerUIAdv.visualstyle.Office2016DarkGray;

模式 3：创建自定义颜色组

// Create custom color group
ColorUIAdvGroup customGroup = new ColorUIAdvGroup();
customGroup.Name = "Brand Colors";
customGroup.HeaderHeight = 25;

// Create color items
GroupColorItem primaryColor = new GroupColorItem(customGroup, Color.FromArgb(0, 120, 215));
primaryColor.Index = 0;

// Add tint variations as sub-items
primaryColor.SubItems.Add(new ColorItem(primaryColor, Color.FromArgb(204, 228, 247)));
primaryColor.SubItems.Add(new ColorItem(primaryColor, Color.FromArgb(153, 204, 239)));
primaryColor.SubItems.Add(new ColorItem(primaryColor, Color.FromArgb(102, 163, 224)));

// Add to group and control
customGroup.Items.Add(primaryColor);
customGroup.SubItemsDepth = 1;
customGroup.IsSubItemsVisible = true;

colorPickerUIAdv1.CustomGroups.Add(customGroup);

模式 4：使用自定义颜色的 Office2007 主题

// Set Managed theme
colorPickerUIAdv1.UseOffice2007Style = true;
colorPickerUIAdv1.Office2007Theme = Office2007Theme.Managed;

// Apply custom color scheme
Office2007Colors.ApplyManagedColors(this, Color.Teal);

模式 5：使用 ItemSelection 事件预览悬停项

// Setup hover event
colorPickerUIAdv1.ItemSelection += ColorPickerUIAdv1_ItemSelection;

// Event handler for hover preview
private void ColorPickerUIAdv1_ItemSelection(object sender, 
                                              ColorPickerUIAdv.ColorPickedEventArgs e)
{
    // Show preview without committing
    previewPanel.BackColor = e.Color;
    statusLabel.Text = $"Preview: {e.Color.Name} (RGB: {e.Color.R}, {e.Color.G}, {e.Color.B})";
}

模式 6：配置自动颜色按钮

// Set automatic color (shown when "Automatic" button is clicked)
colorPickerUIAdv1.AutomaticColor = Color.Black;

// Adjust button height
colorPickerUIAdv1.ButtonHeight = 30;

关键属性

颜色选择

• SelectedColor - 获取或设置当前选中的颜色
• SelectedItem - 获取选中的颜色项对象
• AutomaticColor - “自动”按钮的默认颜色

颜色组

• RecentGroup - 最近使用的颜色集合
• StandardGroup - 标准颜色集合
• ThemeGroup - 主题颜色集合
• CustomGroups - 用户定义的颜色组集合

视觉样式

• Style - 视觉样式（Default、Office2007、Office2010、Office2016*、Metro）
• UseOffice2007Style - 启用或禁用 Office2007 样式
• Office2007Theme - Office2007 配色方案（Blue、Silver、Black、Managed）

布局和外观

• ColorItemSize - 单个颜色项的大小（默认值：13x13）
• HorizontalItemsSpacing - 项之间的水平间距（默认值：4）
• VerticalItemsSpacing - 项之间的垂直间距（默认值：0）
• BorderStyle - 边框外观（None、FixedSingle、Fixed3D）
• BorderOffset - 边框高度（默认值：3）
• TextAlign - 标题文本对齐方式（默认值：MiddleLeft）
• ButtonHeight - 自动按钮的高度（默认值：23）

事件

• Picked - 选中颜色时触发
• ItemSelection - 鼠标悬停在颜色项上时触发

常见用例

用例 1：文本编辑器中的颜色选择

实现颜色选取器，用于在文本编辑器中更改文本颜色或背景颜色。

private void SetupTextColorPicker()
{
    textColorPicker.Style = ColorPickerUIAdv.visualstyle.Office2016Colorful;
    textColorPicker.SelectedColor = richTextBox.SelectionColor;
    textColorPicker.Picked += (s, e) => richTextBox.SelectionColor = e.Color;
}

用例 2：绘图应用程序中的调色板

为绘图工具提供颜色选择功能，并在悬停时进行预览。

private void SetupDrawingColorPicker()
{
    colorPicker.Style = ColorPickerUIAdv.visualstyle.Office2016Black;
    colorPicker.ItemSelection += (s, e) => ShowColorPreview(e.Color);
    colorPicker.Picked += (s, e) => SetActiveBrushColor(e.Color);
}

用例 3：主题颜色自定义

允许用户通过有序的分组自定义应用程序主题颜色。

private void SetupThemeColorPicker()
{
    // Add custom theme colors group
    ColorUIAdvGroup themeGroup = new ColorUIAdvGroup();
    themeGroup.Name = "Theme Colors";
    
    // Add primary, accent, background colors
    themeGroup.Items.Add(CreateColorItem(primaryColor, "Primary"));
    themeGroup.Items.Add(CreateColorItem(accentColor, "Accent"));
    themeGroup.Items.Add(CreateColorItem(backgroundColor, "Background"));
    
    colorPicker.CustomGroups.Add(themeGroup);
    colorPicker.Picked += ApplyThemeColor;
}

用例 4：表单设计器属性编辑器

在表单设计器工具中集成颜色选取器，以编辑属性。

private void ShowColorPickerForProperty(Control control, string propertyName)
{
    ColorPickerUIAdv picker = new ColorPickerUIAdv();
    picker.SelectedColor = (Color)control.GetType()
                                   .GetProperty(propertyName)
                                   .GetValue(control);
    
    picker.Picked += (s, e) => {
        control.GetType()
               .GetProperty(propertyName)
               .SetValue(control, e.Color);
    };
    
    ShowPickerInPopup(picker);
}

用例 5：条件格式颜色选择

为数据网格中的条件格式规则提供颜色选取器。

private void SetupConditionalFormatColorPicker()
{
    // Create custom group with warning/info/success colors
    ColorUIAdvGroup formatGroup = new ColorUIAdvGroup();
    formatGroup.Name = "Formatting Colors";
    
    formatGroup.Items.Add(new GroupColorItem(formatGroup, Color.Red));      // Error
    formatGroup.Items.Add(new GroupColorItem(formatGroup, Color.Orange));   // Warning
    formatGroup.Items.Add(new GroupColorItem(formatGroup, Color.Yellow));   // Caution
    formatGroup.Items.Add(new GroupColorItem(formatGroup, Color.LightGreen)); // Success
    
    colorPicker.CustomGroups.Add(formatGroup);
    colorPicker.Picked += ApplyConditionalFormatting;
}

故障排除

问题：控件未出现在工具箱中

**解决方案：**安装 Syncfusion.Tools.WinForms NuGet 包并重新生成解决方案。

问题：颜色显示不正确

**解决方案：**确保在将颜色组添加到窗体之前正确初始化。检查 SubItemsDepth 和 IsSubItemsVisible 属性。

问题：主题未应用

**解决方案：**对于 Office2007 主题，将 UseOffice2007Style 设置为 true。对于其他样式，直接使用 Style 属性。

问题：事件未触发

**解决方案：**确认在控件初始化后、窗体加载前附加事件处理程序。检查控件是否已添加到窗体的 Controls 集合中。

问题：自定义组未显示

**解决方案：**确保在创建并填充 ColorUIAdvGroup 后调用 CustomGroups.Add()。确认已适当设置 HeaderHeight。

后续步骤

1. 阅读 getting-started.md 进行初始设置
2. 探索 color-groups.md，有效地整理颜色
3. 阅读 appearance-styling.md，自定义视觉样式
4. 使用 events-selection.md 实现事件处理
5. 使用 customization.md 微调布局