syncfusion-wpf-color-picker-palette

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing WPF ColorPickerPalette

实现WPF ColorPickerPalette控件

The ColorPickerPalette is a rich color selection control providing a visual palette interface with theme colors, standard colors, custom colors, and extended color options. Use this skill when you need to implement color selection functionality with flexible customization options.

ColorPickerPalette是一款功能丰富的颜色选择控件，提供可视化调色板界面，包含主题色、标准色、自定义色及扩展颜色选项。当你需要实现具备灵活自定义选项的颜色选择功能时，可使用本控件。

When to Use This Skill

适用场景

Use ColorPickerPalette when you need to:

Allow users to select colors from predefined palettes (theme, standard, custom)
Display recently used colors
Provide "More Colors" options for extended selection
Customize color panels and visibility
Handle color selection events
Support RTL flow direction
Enable transparent or "No Color" options

在以下场景中使用ColorPickerPalette：

允许用户从预定义调色板（主题、标准、自定义）中选择颜色
显示最近使用的颜色
提供“更多颜色”选项以扩展选择范围
自定义颜色面板及其可见性
处理颜色选择事件
支持RTL（从右到左）流向
启用透明或“无颜色”选项

Component Overview

组件概述

ColorPickerPalette provides:

Multiple color sources: Theme colors, standard colors, custom colors, recently used
Flexible modes: Dropdown (default), Palette (expanded), Split (button + dropdown)
Rich customization: Panel visibility, sizing, icons, headers, themes
Event support: SelectedBrushChanged event and SelectedCommand binding
Accessibility: Tooltip support, keyboard navigation, RTL support

ColorPickerPalette具备以下特性：

多颜色来源：主题色、标准色、自定义色、最近使用颜色
灵活模式：下拉（默认）、调色板（展开）、拆分（按钮+下拉）
丰富自定义：面板可见性、尺寸、图标、标题、主题
事件支持：SelectedBrushChanged事件与SelectedCommand绑定
可访问性：提示框支持、键盘导航、RTL支持

Documentation Navigation Guide

文档导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Installation and assembly references
Adding ColorPickerPalette via designer, XAML, and C#
Control structure and key properties
Setting initial colors programmatically
Theme and localization support

📄 阅读：references/getting-started.md

安装及程序集引用
通过设计器、XAML和C#添加ColorPickerPalette
控件结构与关键属性
以编程方式设置初始颜色
主题与本地化支持

Color Management

颜色管理

📄 Read: references/color-management.md

Accessing and changing colors programmatically
Working with color brushes
Automatic color defaults
Transparent color selection
Theme color variants and standard colors
Custom colors collection
Recently used color panel

📄 阅读：references/color-management.md

以编程方式访问和修改颜色
颜色画笔的使用
自动颜色默认值
透明颜色选择
主题色变体与标准色
自定义颜色集合
最近使用颜色面板

Appearance & Customization

外观与自定义

📄 Read: references/appearance-customization.md

Flow direction (RTL) support
Panel visibility options (theme, standard, custom, recently used)
Display modes (Dropdown, Palette, Split)
Resizing color items and palette
Icon customization and sizing
Header template customization

📄 阅读：references/appearance-customization.md

RTL流向支持
面板可见性选项（主题、标准、自定义、最近使用）
显示模式（下拉、调色板、拆分）
颜色项与调色板的尺寸调整
图标自定义与尺寸设置
标题模板自定义

Events & Interactions

事件与交互

📄 Read: references/events-interactions.md

SelectedBrushChanged event handling
SelectedCommand binding patterns
"No Color" button functionality
Tooltip support for color names
More Colors window interaction
Header template customization

📄 阅读：references/events-interactions.md

SelectedBrushChanged事件处理
SelectedCommand绑定模式
“无颜色”按钮功能
颜色名称提示框支持
“更多颜色”窗口交互
标题模板自定义

Quick Start Example

快速入门示例

xaml

<!-- Basic ColorPickerPalette setup -->
<Window xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:syncfusion="http://schemas.syncfusion.com/wpf" 
        Title="ColorPickerPalette Sample">
    <Grid>
        <!-- Default dropdown mode with theme and standard colors -->
        <syncfusion:ColorPickerPalette x:Name="colorPickerPalette" 
                                       Color="Red"
                                       GenerateThemeVariants="True"
                                       GenerateStandardVariants="True"
                                       RecentlyUsedPanelVisibility="Visible"
                                       Width="60" 
                                       Height="40" />
    </Grid>
</Window>

C# Code-Behind:

csharp

using Syncfusion.Windows.Tools.Controls;

public partial class MainWindow : Window {
    public MainWindow() {
        InitializeComponent();

        // Handle color selection
        colorPickerPalette.SelectedBrushChanged += ColorPickerPalette_SelectedBrushChanged;
    }

    private void ColorPickerPalette_SelectedBrushChanged(object sender, SelectedBrushChangedEventArgs e) {
        var newColor = e.NewColor;
        var newBrush = e.NewBrush;
        // Apply color to UI elements
    }
}

xaml

<!-- 基础ColorPickerPalette配置 -->
<Window xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:syncfusion="http://schemas.syncfusion.com/wpf" 
        Title="ColorPickerPalette Sample">
    <Grid>
        <!-- 带主题色和标准色的默认下拉模式 -->
        <syncfusion:ColorPickerPalette x:Name="colorPickerPalette" 
                                       Color="Red"
                                       GenerateThemeVariants="True"
                                       GenerateStandardVariants="True"
                                       RecentlyUsedPanelVisibility="Visible"
                                       Width="60" 
                                       Height="40" />
    </Grid>
</Window>

C#后台代码：

csharp

using Syncfusion.Windows.Tools.Controls;

public partial class MainWindow : Window {
    public MainWindow() {
        InitializeComponent();

        // 处理颜色选择事件
        colorPickerPalette.SelectedBrushChanged += ColorPickerPalette_SelectedBrushChanged;
    }

    private void ColorPickerPalette_SelectedBrushChanged(object sender, SelectedBrushChangedEventArgs e) {
        var newColor = e.NewColor;
        var newBrush = e.NewBrush;
        // 将颜色应用到UI元素
    }
}

Common Patterns

常见模式

Pattern 1: Color Panel Customization

模式1：颜色面板自定义

When: You want specific color panels visible

xaml

<syncfusion:ColorPickerPalette 
    Themes="Metro"
    GenerateThemeVariants="True" 
    GenerateStandardVariants="True"
    ThemePanelVisibility="Visible"
    StandardPanelVisibility="Visible"
    RecentlyUsedPanelVisibility="Visible"
    MoreColorOptionVisibility="Visible"
    NoColorVisibility="Visible" />

场景：需要显示特定颜色面板时

xaml

<syncfusion:ColorPickerPalette 
    Themes="Metro"
    GenerateThemeVariants="True" 
    GenerateStandardVariants="True"
    ThemePanelVisibility="Visible"
    StandardPanelVisibility="Visible"
    RecentlyUsedPanelVisibility="Visible"
    MoreColorOptionVisibility="Visible"
    NoColorVisibility="Visible" />

Pattern 2: Custom Colors Collection

模式2：自定义颜色集合

When: You want users to select from custom predefined colors

csharp

var customColors = new ObservableCollection<CustomColor>
{
    new CustomColor { Color = Color.FromArgb(255, 17, 235, 248), ColorName = "Aqua" },
    new CustomColor { Color = Color.FromArgb(255, 248, 15, 166), ColorName = "Deep Pink" }
};

colorPickerPalette.CustomColorsCollection = customColors;
colorPickerPalette.SetCustomColors = true;
colorPickerPalette.CustomHeaderText = "Brand Colors";

场景：希望用户从预定义的自定义颜色中选择时

csharp

var customColors = new ObservableCollection<CustomColor>
{
    new CustomColor { Color = Color.FromArgb(255, 17, 235, 248), ColorName = "Aqua" },
    new CustomColor { Color = Color.FromArgb(255, 248, 15, 166), ColorName = "Deep Pink" }
};

colorPickerPalette.CustomColorsCollection = customColors;
colorPickerPalette.SetCustomColors = true;
colorPickerPalette.CustomHeaderText = "Brand Colors";

Pattern 3: Split Mode with Command

模式3：带命令的拆分模式

When: You want button and dropdown behavior with command execution

xaml

<syncfusion:ColorPickerPalette 
    Mode="Split"
    SelectedCommand="{Binding ApplyColorCommand}"
    Color="{Binding SelectedColor, Mode=TwoWay}" />

场景：需要按钮+下拉行为并执行命令时

xaml

<syncfusion:ColorPickerPalette 
    Mode="Split"
    SelectedCommand="{Binding ApplyColorCommand}"
    Color="{Binding SelectedColor, Mode=TwoWay}" />

Pattern 4: Expanded Palette Mode

模式4：展开调色板模式

When: You want the palette always visible without dropdown

xaml

<syncfusion:ColorPickerPalette 
    Mode="Palette"
    BorderWidth="30"
    BorderHeight="30" />

场景：希望调色板始终可见，无需下拉时

xaml

<syncfusion:ColorPickerPalette 
    Mode="Palette"
    BorderWidth="30"
    BorderHeight="30" />

Key Properties

关键属性

Property	Type	Purpose
`Color`	`Color`	Gets/sets the selected color (default: Black)
`SelectedBrush`	`Brush`	Gets/sets the selected brush
`Mode`	`PickerMode`	Dropdown, Palette, or Split mode
`Themes`	`PaletteTheme`	Office, Apex, Metro, etc.
`GenerateThemeVariants`	`bool`	Show/hide theme color variants
`GenerateStandardVariants`	`bool`	Show/hide standard color variants
`CustomColorsCollection`	`ObservableCollection<CustomColor>`	Custom color items
`SetCustomColors`	`bool`	Enable custom colors display
`BorderWidth` / `BorderHeight`	`double`	Color item dimensions
`PopupWidth` / `PopupHeight`	`double`	Palette popup size
`RecentlyUsedPanelVisibility`	`Visibility`	Show recently selected colors
`ThemePanelVisibility`	`Visibility`	Show theme colors
`StandardPanelVisibility`	`Visibility`	Show standard colors
`MoreColorOptionVisibility`	`Visibility`	Show "More Colors" button
`NoColorVisibility`	`Visibility`	Show transparent/no color button
`AutomaticColor`	`Color`	Default reset color

属性	类型	用途
`Color`	`Color`	获取/设置选中颜色（默认值：黑色）
`SelectedBrush`	`Brush`	获取/设置选中画笔
`Mode`	`PickerMode`	下拉、调色板或拆分模式
`Themes`	`PaletteTheme`	Office、Apex、Metro等主题
`GenerateThemeVariants`	`bool`	显示/隐藏主题色变体
`GenerateStandardVariants`	`bool`	显示/隐藏标准色变体
`CustomColorsCollection`	`ObservableCollection<CustomColor>`	自定义颜色项
`SetCustomColors`	`bool`	启用自定义颜色显示
`BorderWidth` / `BorderHeight`	`double`	颜色项尺寸
`PopupWidth` / `PopupHeight`	`double`	调色板弹出窗口大小
`RecentlyUsedPanelVisibility`	`Visibility`	显示最近选中的颜色
`ThemePanelVisibility`	`Visibility`	显示主题色
`StandardPanelVisibility`	`Visibility`	显示标准色
`MoreColorOptionVisibility`	`Visibility`	显示“更多颜色”按钮
`NoColorVisibility`	`Visibility`	显示透明/无颜色按钮
`AutomaticColor`	`Color`	默认重置颜色

Common Use Cases

常见用例

Use Case 1: Text Color Picker User needs to apply text formatting colors. Use dropdown mode with standard and theme colors, handle SelectedBrushChanged to apply color to selected text.

Use Case 2: Shape Fill Selector Designer needs to set fill colors for shapes. Use Split mode with custom brand colors, trigger SelectedCommand to apply color to selected shapes.

Use Case 3: Theme Color Picker User needs to pick a color that matches application theme. Use Palette mode with GenerateThemeVariants enabled to show base and variant colors.

Use Case 4: Color History Panel Application tracks recently used colors. Enable RecentlyUsedPanelVisibility and let users quickly reselect previously used colors.

用例1：文本颜色选择器 用户需要为文本设置格式颜色。使用下拉模式搭配标准色和主题色，处理SelectedBrushChanged事件将颜色应用到选中文本。

用例2：形状填充选择器 设计师需要为形状设置填充色。使用拆分模式搭配自定义品牌色，触发SelectedCommand将颜色应用到选中形状。

用例3：主题颜色选择器 用户需要选择与应用主题匹配的颜色。使用调色板模式并启用GenerateThemeVariants，以显示基础色及其变体。

用例4：颜色历史面板 应用需追踪最近使用的颜色。启用RecentlyUsedPanelVisibility，让用户快速重新选择之前使用过的颜色。

Next Steps

后续步骤

Start with basics: Read getting-started.md to set up ColorPickerPalette
Customize colors: Use color-management.md to manage color sources
Style the control: Apply customizations from appearance-customization.md
Handle interactions: Implement event handling from events-interactions.md

从基础开始：阅读getting-started.md完成ColorPickerPalette的设置
自定义颜色：使用color-management.md管理颜色来源
控件样式设置：应用appearance-customization.md中的自定义配置
处理交互：实现events-interactions.md中的事件处理逻辑