syncfusion-winui-dropdown-color-picker

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion WinUI DropDown Color Picker

实现Syncfusion WinUI DropDown Color Picker

The WinUI DropDown Color Picker (

SfDropDownColorPicker

) is a versatile control for color selection and editing. It displays a color spectrum as a dropdown button with support for multiple color channel modes, opacity adjustment, and extensive customization options.

WinUI DropDown Color Picker（

SfDropDownColorPicker

）是一款多功能的颜色选择与编辑控件。它以下拉按钮形式显示颜色光谱，支持多种颜色通道模式、透明度调整以及丰富的自定义选项。

When to Use This Skill

何时使用本技能

User needs: Interactive color selection UI with dropdown behavior
User needs: Support for multiple color formats (RGB, HSV, HSL, CMYK, Hexadecimal)
User needs: Customizable dropdown placement and split button mode
User needs: Embedded color picker customization within a dropdown
User needs: Color change event handling and color binding
User needs: Custom header UI or dropdown button styling

用户需求：带下拉行为的交互式颜色选择UI
用户需求：支持多种颜色格式（RGB、HSV、HSL、CMYK、十六进制）
用户需求：可自定义的下拉位置和拆分按钮模式
用户需求：在下拉菜单中嵌入自定义颜色选择器
用户需求：颜色变更事件处理与颜色绑定
用户需求：自定义头部UI或下拉按钮样式

Component Overview

组件概述

Key Features

核心功能

Color Editing: Drag to select colors or enter values manually in RGB, HSV, HSL, CMYK, or Hex formats
Hue Spectrum Slider: Quickly select hue values
Color Channel Modes: Switch between RGB, HSV, HSL, and CMYK color spaces
Split Mode: Optional button + dropdown arrow separation
Dropdown Customization: Control placement (full, center, left, right, top, bottom)
Opacity Control: Adjust alpha/transparency values
Event Handling: SelectedBrushChanged, DropDownOpened, DropDownClosed events
Custom Templates: Customize header and dropdown button UI

颜色编辑：拖动选择颜色，或手动输入RGB、HSV、HSL、CMYK或Hex格式的数值
色相光谱滑块：快速选择色相值
颜色通道模式：在RGB、HSV、HSL和CMYK颜色空间之间切换
拆分模式：可选的按钮与下拉箭头分离模式
下拉自定义：控制下拉位置（全屏、居中、左对齐、右对齐、顶部、底部）
透明度控制：调整alpha/透明度值
事件处理：SelectedBrushChanged、DropDownOpened、DropDownClosed事件
自定义模板：自定义头部和下拉按钮UI

Required NuGet Package

所需NuGet包

```
Syncfusion.Editors.WinUI
```

Note: Ensure you update the

Syncfusion.Editors.WinUI

NuGet package to the latest available version via the NuGet package manager before building or releasing your application.

```
Syncfusion.Editors.WinUI
```

注意： 在构建或发布应用前，请确保通过NuGet包管理器将

Syncfusion.Editors.WinUI

NuGet包更新至最新版本。

Namespace

命名空间

```
Syncfusion.UI.Xaml.Editors
```

```
Syncfusion.UI.Xaml.Editors
```

Documentation and Navigation Guide

文档与导航指南

Choose the reference guide based on your task:

根据你的任务选择参考指南：

Getting Started

入门指南

📄 Read: references/getting-started.md

Installation and NuGet setup
Creating projects with DropDown Color Picker
Basic XAML and C# implementation
Programmatic color selection
Interactive color selection
Color channel switching (RGB, HSV, HSL, CMYK)
Opacity and alpha value adjustment
Hexadecimal color editor usage

📄 阅读： references/getting-started.md

安装与NuGet设置
创建包含DropDown Color Picker的项目
基础XAML和C#实现
程序化颜色选择
交互式颜色选择
颜色通道切换（RGB、HSV、HSL、CMYK）
透明度与alpha值调整
十六进制颜色编辑器使用

Color Picker Customization

颜色选择器自定义

📄 Read: references/color-picker-customization.md

Customizing the embedded color picker
Using AttachedFlyout and DropDownFlyout
Brush type options (SolidColorBrush, LinearGradientBrush, etc.)
Size and appearance customization
Embedded color picker examples

📄 阅读： references/color-picker-customization.md

嵌入颜色选择器的自定义
使用AttachedFlyout和DropDownFlyout
画笔类型选项（SolidColorBrush、LinearGradientBrush等）
尺寸与外观自定义
嵌入颜色选择器示例

Dropdown Modes and Placement

下拉模式与位置

📄 Read: references/dropdown-modes-and-placement.md

Dropdown placement modes
DropDownPlacement property usage
Split mode (button + dropdown arrow)
Command binding in split mode
Dropdown vs. full dropdown behavior
Custom header UI styling

📄 阅读： references/dropdown-modes-and-placement.md

下拉位置模式
DropDownPlacement属性的使用
拆分模式（按钮+下拉箭头）
拆分模式下的命令绑定
下拉与全下拉行为对比
自定义头部UI样式

Events and Commands

事件与命令

📄 Read: references/events-and-commands.md

SelectedBrushChanged event
OldBrush and NewBrush properties
DropDownOpened and DropDownClosed events
Command binding patterns
Event handling code examples

📄 阅读： references/events-and-commands.md

SelectedBrushChanged事件
OldBrush和NewBrush属性
DropDownOpened和DropDownClosed事件
命令绑定模式
事件处理代码示例

Header and UI Customization

头部与UI自定义

📄 Read: references/header-and-ui-customization.md

ContentTemplate for selected color button
DropDownButtonTemplate for dropdown button
Custom UI styling in XAML
Split mode custom headers
DataContext binding patterns
Complete template examples

📄 阅读： references/header-and-ui-customization.md

选中颜色按钮的ContentTemplate
下拉按钮的DropDownButtonTemplate
XAML中的自定义UI样式
拆分模式下的自定义头部
DataContext绑定模式
完整模板示例

Quick Start Example

快速入门示例

Basic Implementation (XAML)

基础实现（XAML）

xaml

<Page xmlns:editors="using:Syncfusion.UI.Xaml.Editors">
    <Grid>
        <editors:SfDropDownColorPicker x:Name="colorPicker" 
                                       SelectedBrush="Blue" />
    </Grid>
</Page>

xaml

<Page xmlns:editors="using:Syncfusion.UI.Xaml.Editors">
    <Grid>
        <editors:SfDropDownColorPicker x:Name="colorPicker" 
                                       SelectedBrush="Blue" />
    </Grid>
</Page>

Basic Implementation (C#)

基础实现（C#）

csharp

using Syncfusion.UI.Xaml.Editors;

public sealed partial class MainPage : Page
{
    public MainPage()
    {
        this.InitializeComponent();
        
        SfDropDownColorPicker colorPicker = new SfDropDownColorPicker();
        colorPicker.SelectedBrush = new SolidColorBrush(Colors.Blue);
        
        grid.Children.Add(colorPicker);
    }
}

csharp

using Syncfusion.UI.Xaml.Editors;

public sealed partial class MainPage : Page
{
    public MainPage()
    {
        this.InitializeComponent();
        
        SfDropDownColorPicker colorPicker = new SfDropDownColorPicker();
        colorPicker.SelectedBrush = new SolidColorBrush(Colors.Blue);
        
        grid.Children.Add(colorPicker);
    }
}

Listening to Color Changes

监听颜色变更

csharp

// Subscribe to color change event
colorPicker.SelectedBrushChanged += ColorPicker_SelectedBrushChanged;

private void ColorPicker_SelectedBrushChanged(object sender, SelectedBrushChangedEventArgs e)
{
    var oldColor = e.OldBrush;
    var newColor = e.NewBrush;
    
    // Apply the selected color
    myElement.Background = newColor;
}

csharp

// 订阅颜色变更事件
colorPicker.SelectedBrushChanged += ColorPicker_SelectedBrushChanged;

private void ColorPicker_SelectedBrushChanged(object sender, SelectedBrushChangedEventArgs e)
{
    var oldColor = e.OldBrush;
    var newColor = e.NewBrush;
    
    // 应用选中的颜色
    myElement.Background = newColor;
}

Common Use Cases

常见用例

1. Theme Color Selector

1. 主题颜色选择器

Allow users to select application theme colors:

csharp

// User selects a color → apply to app background
SfDropDownColorPicker themeColorPicker = new SfDropDownColorPicker();
themeColorPicker.SelectedBrushChanged += (s, e) => 
{
    Window.Current.Content.Background = e.NewBrush;
};

允许用户选择应用主题颜色：

csharp

// 用户选择颜色 → 应用到应用背景
SfDropDownColorPicker themeColorPicker = new SfDropDownColorPicker();
themeColorPicker.SelectedBrushChanged += (s, e) => 
{
    Window.Current.Content.Background = e.NewBrush;
};

2. Split Button Mode for Direct Application

2. 拆分按钮模式用于直接应用

Apply last selected color with button click, open dropdown to change:

xaml

<editors:SfDropDownColorPicker DropDownMode="Split"
                               Command="{x:Bind ApplyColorCommand}" />

点击按钮应用上次选中的颜色，打开下拉菜单更改颜色：

xaml

<editors:SfDropDownColorPicker DropDownMode="Split"
                               Command="{x:Bind ApplyColorCommand}" />

3. Custom Color Editor Interface

3. 自定义颜色编辑器界面

Embed specific color picker configuration:

xaml

<editors:SfDropDownColorPicker>
    <FlyoutBase.AttachedFlyout>
        <editors:DropDownFlyout>
            <editors:SfColorPicker BrushTypeOptions="LinearGradientBrush" 
                                   Width="250" />
        </editors:DropDownFlyout>
    </FlyoutBase.AttachedFlyout>
</editors:SfDropDownColorPicker>

嵌入特定的颜色选择器配置：

xaml

<editors:SfDropDownColorPicker>
    <FlyoutBase.AttachedFlyout>
        <editors:DropDownFlyout>
            <editors:SfColorPicker BrushTypeOptions="LinearGradientBrush" 
                                   Width="250" />
        </editors:DropDownFlyout>
    </FlyoutBase.AttachedFlyout>
</editors:SfDropDownColorPicker>

4. Positioned Dropdown (Top-Right)

4. 定位下拉菜单（右上）

Control where the color picker opens:

xaml

<editors:SfDropDownColorPicker DropDownPlacement="TopEdgeAlignedRight" />

控制颜色选择器的打开位置：

xaml

<editors:SfDropDownColorPicker DropDownPlacement="TopEdgeAlignedRight" />

Key Properties

关键属性

Property	Type	Purpose	Common Values
`SelectedBrush`	`Brush`	Currently selected color	`Colors.Blue` , `new SolidColorBrush()`
`DropDownMode`	`enum`	Dropdown behavior	`Dropdown` , `Split`
`DropDownPlacement`	`FlyoutPlacementMode`	Position of dropdown	`Full` , `Top` , `Bottom` , `Left` , `Right`
`Command`	`ICommand`	Command triggered on button click	Custom ICommand implementation

属性	类型	用途	常用值
`SelectedBrush`	`Brush`	当前选中的颜色	`Colors.Blue` , `new SolidColorBrush()`
`DropDownMode`	`enum`	下拉行为	`Dropdown` , `Split`
`DropDownPlacement`	`FlyoutPlacementMode`	下拉位置	`Full` , `Top` , `Bottom` , `Left` , `Right`
`Command`	`ICommand`	按钮点击时触发的命令	自定义ICommand实现

Common Patterns

常见模式

Pattern 1: Color Binding to UI Element

模式1：颜色绑定到UI元素

csharp

// When color is selected, immediately apply to target element
void ColorPicker_SelectedBrushChanged(object sender, SelectedBrushChangedEventArgs e)
{
    targetRectangle.Fill = e.NewBrush;
}

csharp

// 选中颜色后，立即应用到目标元素
void ColorPicker_SelectedBrushChanged(object sender, SelectedBrushChangedEventArgs e)
{
    targetRectangle.Fill = e.NewBrush;
}

Pattern 2: Validating Color Selection

模式2：验证颜色选择

csharp

void ColorPicker_SelectedBrushChanged(object sender, SelectedBrushChangedEventArgs e)
{
    // Validate color meets requirements
    if (IsValidColor(e.NewBrush))
    {
        ApplyColor(e.NewBrush);
    }
    else
    {
        colorPicker.SelectedBrush = e.OldBrush; // Revert
    }
}

csharp

void ColorPicker_SelectedBrushChanged(object sender, SelectedBrushChangedEventArgs e)
{
    // 验证颜色是否符合要求
    if (IsValidColor(e.NewBrush))
    {
        ApplyColor(e.NewBrush);
    }
    else
    {
        colorPicker.SelectedBrush = e.OldBrush; // 恢复原颜色
    }
}

Pattern 3: Split Mode with Custom Command

模式3：带自定义命令的拆分模式

csharp

public ICommand QuickApplyCommand => new RelayCommand(() =>
{
    // Apply current selected color without opening dropdown
    ApplySelectedColorToTextSelection();
});

csharp

public ICommand QuickApplyCommand => new RelayCommand(() =>
{
    // 不打开下拉菜单，直接应用当前选中的颜色
    ApplySelectedColorToTextSelection();
});

Next Steps

后续步骤

Start with: getting-started.md to set up basic DropDown Color Picker
Then explore: Other reference guides based on your specific needs
For production: Review all guides for complete customization capabilities

开始： 阅读getting-started.md以设置基础的DropDown Color Picker
然后探索： 根据你的具体需求查看其他参考指南
生产环境： 查看所有指南以掌握完整的自定义能力