syncfusion-winforms-color-ui-control

实现 ColorUIControl

何时使用此技能

当你需要在 Windows Forms 应用程序中使用 Syncfusion 的 ColorUIControl 实现颜色选择功能时，请使用此技能。以下情况适用：

• 需要为 Windows Forms 应用程序添加颜色选择器 UI
• 希望提供类似 Visual Studio 的颜色选择界面
• 需要内嵌颜色选择控件（而不仅仅是对话框）
• 需要使用预定义颜色组自定义调色板
• 希望将颜色选择器集成到弹出菜单或下拉菜单中
• 需要通过 System、Standard、Custom 或用户定义的颜色实现颜色选择
• 正在开发 .NET Framework Windows Forms 应用程序
• 希望提供 ColorPickerButton 下拉功能

ColorUIControl 提供类似 Visual Studio 颜色选择器的调色板式界面，包含四种颜色分组（SystemColors、StandardColors、CustomColors、UserColors），可在应用程序中内嵌显示，也可作为下拉控件使用。

组件概览

ColorUIControl 是一种 Windows Forms 控件，提供包含预定义调色板的丰富颜色选择界面。与以模态对话框形式显示的标准 ColorDialog 不同，ColorUIControl 可以内嵌在应用程序布局中，也可以用作下拉控件。

主要功能：

• 四种预定义颜色组（System、Standard、Custom、User）
• 可内嵌在应用程序布局中
• 通过 PopupControlContainer 集成弹出菜单/下拉菜单
• 可自定义调色板和选项卡名称
• 类似 Visual Studio 的颜色选择器界面
• 支持编程方式和交互方式选择颜色
• 可自定义边框样式并拉伸面板

文档与导航指南

入门

📄 阅读： references/getting-started.md

适用于以下需求：

• 安装和设置 ColorUIControl 组件
• 通过设计器或代码添加 ColorUIControl
• 了解程序集依赖项（Syncfusion.Shared.Base）
• 在 C# 或 VB.NET 中初始化控件
• 设置初始选定颜色和颜色组
• 导入所需命名空间（Syncfusion.Windows.Forms）

颜色组与选择

📄 阅读： references/color-groups.md

适用于以下需求：

• 了解四种颜色组（System、Standard、Custom、User）
• 控制要显示的颜色组
• 以编程方式选择默认颜色组
• 自定义 UserColors 和 UserCustomColors 集合
• 添加或移除特定颜色组
• 以编程方式填充自定义颜色单元格

外观与自定义

📄 阅读： references/appearance-customization.md

适用于以下需求：

• 设置边框样式（FixedSingle、Fixed3D、None）
• 为 Custom 和 User 颜色组启用面板拉伸
• 自定义各颜色组选项卡的文本
• 更改选项卡文本的字体样式
• 将选项卡名称重置为默认值
• 调整控件的视觉外观

事件与交互

📄 阅读： references/events.md

适用于以下需求：

• 处理 ColorSelected 事件
• 选中颜色后关闭弹出窗口
• 在事件处理程序中获取选定颜色
• 在事件中使用 PopupControlContainer
• 实现颜色选择回调

高级场景

📄 阅读： references/popup-integration.md

适用于以下需求：

• 将 ColorUIControl 添加到弹出菜单
• 与 PopupMenu 和 PopupControlContainer 集成
• 配置用于颜色选择器的 DropDownBarItem
• 在鼠标单击时显示颜色选择器
• 使用 ColorPickerButton 实现下拉功能
• 创建完整的弹出式颜色选择工作流

快速入门示例

下面是一个在 Windows Forms 应用程序中添加 ColorUIControl 的最简示例：

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

public class ColorPickerForm : Form
{
    private ColorUIControl colorUIControl1;
    
    public ColorPickerForm()
    {
        InitializeComponent();
    }
    
    private void InitializeComponent()
    {
        // Create ColorUIControl instance
        this.colorUIControl1 = new ColorUIControl();
        
        // Set size
        this.colorUIControl1.Size = new Size(210, 200);
        this.colorUIControl1.Location = new Point(20, 20);
        
        // Set initial color and group
        this.colorUIControl1.SelectedColor = Color.OrangeRed;
        this.colorUIControl1.SelectedColorGroup = 
            ColorUISelectedGroup.StandardColors;
        
        // Handle color selection
        this.colorUIControl1.ColorSelected += ColorUIControl1_ColorSelected;
        
        // Add to form
        this.Controls.Add(this.colorUIControl1);
        
        // Form settings
        this.Text = "Color Picker Example";
        this.Size = new Size(300, 300);
    }
    
    private void ColorUIControl1_ColorSelected(object sender, EventArgs e)
    {
        Color selectedColor = this.colorUIControl1.SelectedColor;
        MessageBox.Show($"Selected Color: {selectedColor.Name}");
    }
}

VB.NET：

Imports System.Drawing
Imports System.Windows.Forms
Imports Syncfusion.Windows.Forms

Public Class ColorPickerForm
    Inherits Form
    
    Private colorUIControl1 As ColorUIControl
    
    Public Sub New()
        InitializeComponent()
    End Sub
    
    Private Sub InitializeComponent()
        ' Create ColorUIControl instance
        Me.colorUIControl1 = New ColorUIControl()
        
        ' Set size
        Me.colorUIControl1.Size = New Size(210, 200)
        Me.colorUIControl1.Location = New Point(20, 20)
        
        ' Set initial color and group
        Me.colorUIControl1.SelectedColor = Color.OrangeRed
        Me.colorUIControl1.SelectedColorGroup = _
            ColorUISelectedGroup.StandardColors
        
        ' Handle color selection
        AddHandler Me.colorUIControl1.ColorSelected, _
            AddressOf ColorUIControl1_ColorSelected
        
        ' Add to form
        Me.Controls.Add(Me.colorUIControl1)
        
        ' Form settings
        Me.Text = "Color Picker Example"
        Me.Size = New Size(300, 300)
    End Sub
    
    Private Sub ColorUIControl1_ColorSelected(sender As Object, e As EventArgs)
        Dim selectedColor As Color = Me.colorUIControl1.SelectedColor
        MessageBox.Show($"Selected Color: {selectedColor.Name}")
    End Sub
End Class

常见模式

模式 1：仅包含特定组的内嵌颜色选择器

仅显示 Standard 和 Custom 颜色，创建精简的颜色选择器：

// Display only Standard and Custom color groups
this.colorUIControl1.ColorGroups = 
    ColorUIGroups.StandardColors | ColorUIGroups.CustomColors;

// Enable panel stretching for better visual layout
this.colorUIControl1.CustomColorsStretchOnResize = true;

// Set border style
this.colorUIControl1.BorderStyle = BorderStyle.FixedSingle;

模式 2：自定义选项卡名称

自定义选项卡文本，以便更好地提供上下文：

// Customize tab names
this.colorUIControl1.StandardTabName = "Web Colors";
this.colorUIControl1.SystemTabName = "System";
this.colorUIControl1.UserTabName = "My Colors";
this.colorUIControl1.CustomTabName = "Theme Palette";

// Customize font
this.colorUIControl1.Font = new Font("Segoe UI", 9F);

模式 3：弹出式颜色选取器

将 ColorUIControl 集成到弹出菜单中：

// Setup: Create PopupMenu, PopupControlContainer, and ColorUIControl
private PopupMenu popupMenu1;
private PopupControlContainer popupContainer1;
private ColorUIControl colorUIControl1;
private Panel colorButton;

private void InitializePopupColorPicker()
{
    // Create and configure ColorUIControl
    colorUIControl1 = new ColorUIControl();
    colorUIControl1.Size = new Size(210, 200);
    
    // Create PopupControlContainer and add ColorUI
    popupContainer1 = new PopupControlContainer();
    popupContainer1.Controls.Add(colorUIControl1);
    
    // Create PopupMenu
    popupMenu1 = new PopupMenu();
    
    // Add DropDownBarItem to popup menu
    var dropDownItem = new DropDownBarItem();
    dropDownItem.PopupControlContainer = popupContainer1;
    popupMenu1.ParentBarItem.Items.Add(dropDownItem);
    
    // Handle panel click to show popup
    colorButton.MouseUp += ColorButton_MouseUp;
    
    // Close popup when color selected
    colorUIControl1.ColorSelected += ColorUIControl1_ColorSelected;
}

private void ColorButton_MouseUp(object sender, MouseEventArgs e)
{
    popupMenu1.Show(colorButton, new Point(e.X, e.Y));
}

private void ColorUIControl1_ColorSelected(object sender, EventArgs e)
{
    // Update UI with selected color
    colorButton.BackColor = colorUIControl1.SelectedColor;
    
    // Close the popup
    var cuiControl = sender as ColorUIControl;
    var pcc = cuiControl.Parent as PopupControlContainer;
    pcc.HidePopup(PopupCloseType.Done);
}

模式 4：自定义用户颜色调色板

以编程方式填充自定义颜色：

// Customize UserColors collection with blue gradient
for (int i = 0; i < colorUIControl1.UserColors.Count; i++)
{
    colorUIControl1.UserColors[i] = Color.FromArgb(0, 0, i * 5);
}

// Customize UserCustomColors collection with red gradient
for (int i = 0; i < colorUIControl1.UserCustomColors.Count; i++)
{
    colorUIControl1.UserCustomColors[i] = Color.FromArgb(i * 15, 0, 0);
}

// Make sure UserColors group is displayed
colorUIControl1.ColorGroups = 
    ColorUIGroups.StandardColors | 
    ColorUIGroups.CustomColors | 
    ColorUIGroups.UserColors;

// Select UserColors group by default
colorUIControl1.SelectedColorGroup = ColorUISelectedGroup.UserColors;

// Enable stretching
colorUIControl1.UserColorsStretchOnResize = true;

关键属性

选择属性

• SelectedColor（Color）：获取或设置当前选中的颜色
• SelectedColorGroup（ColorUISelectedGroup）：获取或设置当前激活的颜色组选项卡
  • 选项：SystemColors、StandardColors、CustomColors、UserColors、None

显示属性

• ColorGroups（ColorUIGroups）：控制可见的颜色组（标志枚举）
  • 组合使用：ColorUIGroups.StandardColors | ColorUIGroups.CustomColors
• BorderStyle（BorderStyle）：设置边框外观（FixedSingle、Fixed3D、None）

自定义属性

• CustomColorsStretchOnResize（bool）：启用自定义颜色面板的拉伸
• UserColorsStretchOnResize（bool）：启用用户颜色面板的拉伸
• StandardTabName（string）：标准颜色选项卡的自定义文本
• SystemTabName（string）：系统颜色选项卡的自定义文本
• CustomTabName（string）：自定义颜色选项卡的自定义文本
• UserTabName（string）：用户颜色选项卡的自定义文本
• Font（Font）：选项卡文本的字体样式

集合属性

• UserColors（ColorCollection）：用户颜色组中的颜色集合
• UserCustomColors（ColorCollection）：用户颜色组中的其他自定义颜色

事件

• ColorSelected：用户选中颜色时触发

常见用例

1. 文本编辑器颜色选择： 添加内嵌颜色选取器，用于选择字体颜色、背景颜色或突出显示颜色
2. 设计工具： 为绘图应用程序或设计工具提供调色板
3. 主题配置： 允许用户通过选择颜色来自定义应用程序主题
4. 图表自定义： 允许用户为图表中的数据系列选择颜色
5. 表单控件样式设置： 支持在运行时自定义表单控件的颜色
6. 颜色属性编辑器： 集成到属性网格中，用于设置基于颜色的选项
7. 弹出式颜色选取器： 为工具栏按钮创建类似 ColorPickerButton 的下拉菜单
8. 自定义配色方案： 允许用户定义并保存自定义调色板

提示和最佳实践

• 使用 SelectedColorGroup，根据用户上下文自动聚焦相应的颜色选项卡
• 启用面板拉伸（CustomColorsStretchOnResize、UserColorsStretchOnResize），以便在较大的容器中获得更好的视觉布局
• 自定义选项卡名称，使其符合应用程序的术语（例如“主题颜色”“品牌颜色”）
• 处理 ColorSelected 事件，在选中颜色时关闭弹出菜单或立即更新 UI
• 如需下拉功能，可考虑使用 ColorPickerButton，而不是手动创建弹出菜单基础结构
• 使用 ColorGroups 属性限制可见组，在用户只需要特定颜色类型时简化 UI
• 如果有预定义的配色方案或主题，可通过编程方式设置 UserColors
• 重置方法（ResetSelectedColor()、ResetSelectedColorGroup()）适用于“清除”或“默认”按钮

有关 ColorPickerButton 下拉功能，请参阅 Syncfusion 文档，了解如何将 ColorUIControl 用作下拉控件。