syncfusion-winui-color-picker

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion WinUI Color Picker (SfColorPicker)

实现Syncfusion WinUI颜色选择器（SfColorPicker）

When to Use This Skill

何时使用本技能

Use this skill immediately when the user:

Needs to implement a color picker UI in a WinUI application
Wants to select solid colors with multiple color models (RGB, HSV, HSL, CMYK)
Requires gradient brush creation (linear or radial)
Needs to customize the color spectrum shape (box or ring)
Wants to provide color editing with alpha/opacity control
Needs to switch between solid and gradient brush modes
Requires hexadecimal color input/output
Wants to handle color selection change events
Needs to customize color channel input options (sliders, text inputs)
Requires programmatic color brush selection

This skill is specifically for the Syncfusion WinUI Color Picker (

SfColorPicker

) control, not generic color picking solutions.

当用户有以下需求时，请立即使用本技能：

需要在WinUI应用中实现颜色选择器UI
希望通过多种颜色模型（RGB、HSV、HSL、CMYK）选择纯色
需要创建渐变画刷（线性或径向）
需要自定义色谱形状（矩形或环形）
希望提供带透明度/alpha通道控制的颜色编辑功能
需要在纯色和渐变画刷模式之间切换
需要十六进制颜色的输入/输出功能
希望处理颜色选择变更事件
需要自定义颜色通道输入选项（滑块、文本输入）
需要通过代码选择颜色画刷

本技能专门针对Syncfusion WinUI颜色选择器（

SfColorPicker

）控件，而非通用颜色选择解决方案。

Component Overview

组件概述

The SfColorPicker is a WinUI control for selecting and adjusting color values. It supports:

Solid Colors: RGB, HSV, HSL, CMYK color models with hexadecimal editor
Gradient Brushes: Linear and radial gradient color brushes with multiple stops
Color Spectrum: Interactive color selection with box or ring shape
Opacity Control: Alpha channel adjustment via sliders and text inputs
Mode Switching: Dynamic switching between solid and gradient modes
Event Notifications: Real-time color selection change events

Key Namespace:

csharp

using Syncfusion.UI.Xaml.Editors;

NuGet Package:

Syncfusion.Editors.WinUI

SfColorPicker是一款用于选择和调整颜色值的WinUI控件，支持：

纯色：RGB、HSV、HSL、CMYK颜色模型，搭配十六进制编辑器
渐变画刷：线性和径向渐变颜色画刷，支持多个颜色停止点
色谱：交互式颜色选择，支持矩形或环形形状
透明度控制：通过滑块和文本输入调整alpha通道
模式切换：在纯色和渐变模式之间动态切换
事件通知：实时颜色选择变更事件

关键命名空间：

csharp

using Syncfusion.UI.Xaml.Editors;

NuGet包：

Syncfusion.Editors.WinUI

Documentation and Navigation Guide

文档与导航指南

Getting Started with SfColorPicker

快速上手SfColorPicker

📄 Read: references/getting-started.md

Read this reference when you need:

Installation and NuGet package setup instructions
Basic
```
SfColorPicker
```
control implementation
Namespace and assembly references
First working XAML + C# example with event handling
Understanding the control structure and troubleshooting setup issues

Topics covered:

Creating a WinUI 3 desktop application
Adding
```
Syncfusion.Editors.WinUI
```
NuGet package
Importing the control namespace
Basic XAML and C# initialization
Control structure overview
Common initial configurations

📄 阅读： references/getting-started.md

当你有以下需求时阅读本参考文档：

安装和NuGet包设置说明
基础
```
SfColorPicker
```
控件实现
命名空间和程序集引用
第一个可运行的XAML + C#示例，包含事件处理
了解控件结构和设置问题排查

涵盖主题：

创建WinUI 3桌面应用
添加
```
Syncfusion.Editors.WinUI
```
NuGet包
导入控件命名空间
基础XAML和C#初始化
控件结构概述
常见初始配置

Solid Color Selection

纯色选择

📄 Read: references/solid-color-selection.md

Read this reference when you need:

Selecting solid color brushes programmatically or interactively
Working with different color models (RGB, HSV, HSL, CMYK)
Switching between color channels at runtime
Implementing hexadecimal color input/output
Controlling opacity/alpha values
Customizing color channel input options (sliders vs text)
Handling solid color selection change events

Topics covered:

```
SelectedBrush
```
property for programmatic and interactive selection
```
ColorChannelOptions
```
(RGB, HSV, HSL, CMYK) with usage examples
```
BrushTypeOptions
```
to restrict solid-only mode
```
AlphaInputOptions
```
for opacity control (All, TextInput, SliderInput)
```
IsHexInputVisible
```
for hexadecimal editor visibility
```
ColorChannelInputOptions
```
(TextInput, SliderInput, All)
```
ColorEditorsVisibilityMode
```
(Inline, Expandable, Collapsed)
```
SelectedBrushChanged
```
event handling

📄 阅读： references/solid-color-selection.md

当你有以下需求时阅读本参考文档：

通过代码或交互方式选择纯色画刷
使用不同颜色模型（RGB、HSV、HSL、CMYK）
在运行时切换颜色通道
实现十六进制颜色的输入/输出
控制透明度/alpha值
自定义颜色通道输入选项（滑块 vs 文本）
处理纯色选择变更事件

涵盖主题：

```
SelectedBrush
```
属性：用于代码和交互选择
```
ColorChannelOptions
```
（RGB、HSV、HSL、CMYK）及使用示例
```
BrushTypeOptions
```
：限制为仅纯色模式
```
AlphaInputOptions
```
：透明度控制（全部、文本输入、滑块输入）
```
IsHexInputVisible
```
：控制十六进制编辑器的可见性
```
ColorChannelInputOptions
```
（文本输入、滑块输入、全部）
```
ColorEditorsVisibilityMode
```
（内联、可展开、折叠）
```
SelectedBrushChanged
```
事件处理

Gradient Color Selection

渐变颜色选择

📄 Read: references/gradient-color-selection.md

Read this reference when you need:

Creating linear gradient brushes with multiple color stops
Creating radial gradient brushes with gradient origin and center
Programmatic gradient brush configuration
Interactive gradient editing at runtime
Adjusting gradient angles and directions
Modifying gradient offsets (start/end points, radius)
Controlling gradient opacity
Handling gradient color change events

Topics covered:

LinearGradientBrush

with

GradientStop

StartPoint

EndPoint

RadialGradientBrush

with

GradientOrigin

Center

RadiusX

RadiusY

Interactive gradient creation with
```
BrushTypeOptions
```
```
AxisInputOption
```
— Simple (angle/direction) vs Advanced (precise editors)
Adding, removing, and reordering gradient stops
Gradient opacity control
```
SelectedBrushChanged
```
event for gradient brushes

📄 阅读： references/gradient-color-selection.md

当你有以下需求时阅读本参考文档：

创建带多个颜色停止点的线性渐变画刷
创建带渐变原点和中心的径向渐变画刷
通过代码配置渐变画刷
在运行时交互式编辑渐变
调整渐变角度和方向
修改渐变偏移量（起点/终点、半径）
控制渐变透明度
处理渐变颜色变更事件

涵盖主题：

LinearGradientBrush

：包含

GradientStop

、

StartPoint

、

EndPoint

RadialGradientBrush

：包含

GradientOrigin

、

Center

、

RadiusX

、

RadiusY

使用
```
BrushTypeOptions
```
交互式创建渐变
```
AxisInputOption
```
— 简单模式（角度/方向） vs 高级模式（精确编辑器）
添加、移除和重新排序渐变停止点
渐变透明度控制
渐变画刷的
```
SelectedBrushChanged
```
事件

UI Customization and Modes

UI自定义与模式

📄 Read: references/ui-customization.md

Read this reference when you need:

Switching between solid, linear, and radial brush modes
Enabling or restricting specific brush types
Changing color spectrum shapes (box vs ring)
Customizing color spectrum components (hue, saturation, value)
Understanding
```
BrushTypeOptions
```
combinations
Runtime brush mode switching behavior

Topics covered:

```
BrushTypeOptions
```
configurations (SolidColorBrush, LinearGradientBrush, RadialGradientBrush, All)
Interactive brush mode dropdown behavior
```
ColorSpectrumShape
```
(Box vs Ring) with when-to-use guidance
```
ColorSpectrumComponents
```
(SaturationValue, HueSaturation, HueValue, etc.)
Common customization patterns for different app types

📄 阅读： references/ui-customization.md

当你有以下需求时阅读本参考文档：

在纯色、线性和径向画刷模式之间切换
启用或限制特定画刷类型
更改色谱形状（矩形 vs 环形）
自定义色谱组件（色相、饱和度、明度）
了解
```
BrushTypeOptions
```
的组合方式
运行时画刷模式切换行为

涵盖主题：

```
BrushTypeOptions
```
配置（SolidColorBrush、LinearGradientBrush、RadialGradientBrush、全部）
交互式画刷模式下拉菜单行为
```
ColorSpectrumShape
```
（矩形 vs 环形）及使用场景指导
```
ColorSpectrumComponents
```
（SaturationValue、HueSaturation、HueValue等）
针对不同应用类型的常见自定义模式

Best Practices and Troubleshooting

最佳实践与故障排除

📄 Read: references/best-practices.md

Read this reference when you need:

Guidance on when to use solid vs gradient colors
Performance optimization tips for gradients
Common use case implementation patterns
Troubleshooting color selection or rendering issues
Accessibility considerations
Integration patterns (flyout, dialog, property panel)

Topics covered:

Solid vs gradient decision matrix
Performance tips: gradient stop limits, caching brushes, debouncing events
Common use cases: theme picker, drawing tool, text highlighter, background editor
Flyout, dialog, and property panel integration patterns
Common mistakes (brush type mismatch, missing null checks)
Accessibility: keyboard navigation, ARIA attributes, screen reader support

📄 阅读： references/best-practices.md

当你有以下需求时阅读本参考文档：

关于何时使用纯色 vs 渐变颜色的指导
渐变性能优化技巧
常见用例实现模式
排查颜色选择或渲染问题
无障碍访问注意事项
集成模式（浮出控件、对话框、属性面板）

涵盖主题：

纯色vs渐变决策矩阵
性能技巧：渐变停止点限制、画刷缓存、事件防抖
常见用例：主题选择器、绘图工具、文本高亮器、背景编辑器
浮出控件、对话框和属性面板集成模式
常见错误（画刷类型不匹配、缺少空值检查）
无障碍访问：键盘导航、ARIA属性、屏幕阅读器支持

Quick Start Example

快速开始示例

XAML

xml

<Page
    x:Class="ColorPickerApp.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:editors="using:Syncfusion.UI.Xaml.Editors">

    <Grid>
        <editors:SfColorPicker
            x:Name="colorPicker"
            SelectedBrush="Blue"
            BrushTypeOptions="All"
            SelectedBrushChanged="ColorPicker_SelectedBrushChanged" />
    </Grid>
</Page>

xml

<Page
    x:Class="ColorPickerApp.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:editors="using:Syncfusion.UI.Xaml.Editors">

    <Grid>
        <editors:SfColorPicker
            x:Name="colorPicker"
            SelectedBrush="Blue"
            BrushTypeOptions="All"
            SelectedBrushChanged="ColorPicker_SelectedBrushChanged" />
    </Grid>
</Page>

C# Code-Behind

C#代码后置

csharp

using Syncfusion.UI.Xaml.Editors;
using Microsoft.UI.Xaml.Media;

private void ColorPicker_SelectedBrushChanged(object sender, SelectedBrushChangedEventArgs args)
{
    if (args?.NewBrush is SolidColorBrush solidBrush)
    {
        var color = solidBrush.Color; // Access R, G, B, A
    }
    else if (args?.NewBrush is LinearGradientBrush linearBrush)
    {
        var stops = linearBrush.GradientStops;
    }
    else if (args?.NewBrush is RadialGradientBrush radialBrush)
    {
        var stops = radialBrush.GradientStops;
    }
}

csharp

using Syncfusion.UI.Xaml.Editors;
using Microsoft.UI.Xaml.Media;

private void ColorPicker_SelectedBrushChanged(object sender, SelectedBrushChangedEventArgs args)
{
    if (args?.NewBrush is SolidColorBrush solidBrush)
    {
        var color = solidBrush.Color; // 访问R、G、B、A通道
    }
    else if (args?.NewBrush is LinearGradientBrush linearBrush)
    {
        var stops = linearBrush.GradientStops;
    }
    else if (args?.NewBrush is RadialGradientBrush radialBrush)
    {
        var stops = radialBrush.GradientStops;
    }
}

Common Patterns

常见模式

Pattern 1: Solid Color Picker Only

模式1：仅纯色选择器

xml

<editors:SfColorPicker
    BrushTypeOptions="SolidColorBrush"
    ColorChannelOptions="RGB"
    IsHexInputVisible="True" />

xml

<editors:SfColorPicker
    BrushTypeOptions="SolidColorBrush"
    ColorChannelOptions="RGB"
    IsHexInputVisible="True" />

Pattern 2: Gradient Editor Only

模式2：仅渐变编辑器

xml

<editors:SfColorPicker
    BrushTypeOptions="LinearGradientBrush,RadialGradientBrush"
    AxisInputOption="Simple" />

xml

<editors:SfColorPicker
    BrushTypeOptions="LinearGradientBrush,RadialGradientBrush"
    AxisInputOption="Simple" />

Pattern 3: Programmatic Color Selection

模式3：通过代码选择颜色

csharp

// Solid color
colorPicker.SelectedBrush = new SolidColorBrush(Colors.Red);

// Linear gradient
var linearGradient = new LinearGradientBrush();
linearGradient.StartPoint = new Point(0, 0);
linearGradient.EndPoint = new Point(1, 1);
linearGradient.GradientStops.Add(new GradientStop() { Color = Colors.Yellow, Offset = 0.0 });
linearGradient.GradientStops.Add(new GradientStop() { Color = Colors.Red, Offset = 1.0 });
colorPicker.SelectedBrush = linearGradient;

csharp

// 纯色
colorPicker.SelectedBrush = new SolidColorBrush(Colors.Red);

// 线性渐变
var linearGradient = new LinearGradientBrush();
linearGradient.StartPoint = new Point(0, 0);
linearGradient.EndPoint = new Point(1, 1);
linearGradient.GradientStops.Add(new GradientStop() { Color = Colors.Yellow, Offset = 0.0 });
linearGradient.GradientStops.Add(new GradientStop() { Color = Colors.Red, Offset = 1.0 });
colorPicker.SelectedBrush = linearGradient;

Pattern 4: Custom Spectrum Shape

模式4：自定义色谱形状

xml

<editors:SfColorPicker
    ColorSpectrumShape="Ring"
    ColorSpectrumComponents="HueSaturation" />

xml

<editors:SfColorPicker
    ColorSpectrumShape="Ring"
    ColorSpectrumComponents="HueSaturation" />

Key Properties Reference

关键属性参考

Property	Type	Default	Purpose
`SelectedBrush`	Brush	Blue	Gets/sets the selected color brush
`BrushTypeOptions`	BrushTypeOptions	All	Enables specific brush modes (Solid, Linear, Radial)
`ColorChannelOptions`	ColorChannelOptions	RGB	Sets color model (RGB, HSV, HSL, CMYK)
`ColorSpectrumShape`	ColorSpectrumShape	Box	Sets spectrum shape (Box or Ring)
`ColorSpectrumComponents`	ColorSpectrumComponents	SaturationValue	Defines spectrum axes
`AlphaInputOptions`	ColorInputOptions	All	Controls alpha/opacity input visibility
`IsHexInputVisible`	bool	true	Shows/hides hexadecimal editor
`ColorChannelInputOptions`	ColorInputOptions	All	Controls channel input type (Slider/Text/All)
`ColorEditorsVisibilityMode`	ColorEditorsVisibilityMode	Inline	Sets editor visibility (Inline/Expandable/Collapsed)
`AxisInputOption`	AxisInputOption	Simple	Controls gradient axis input complexity

属性	类型	默认值	用途
`SelectedBrush`	Brush	Blue	获取/设置选中的颜色画刷
`BrushTypeOptions`	BrushTypeOptions	All	启用特定画刷模式（纯色、线性、径向）
`ColorChannelOptions`	ColorChannelOptions	RGB	设置颜色模型（RGB、HSV、HSL、CMYK）
`ColorSpectrumShape`	ColorSpectrumShape	Box	设置色谱形状（矩形或环形）
`ColorSpectrumComponents`	ColorSpectrumComponents	SaturationValue	定义色谱坐标轴
`AlphaInputOptions`	ColorInputOptions	All	控制alpha/透明度输入的可见性
`IsHexInputVisible`	bool	true	显示/隐藏十六进制编辑器
`ColorChannelInputOptions`	ColorInputOptions	All	控制颜色通道输入类型（滑块/文本/全部）
`ColorEditorsVisibilityMode`	ColorEditorsVisibilityMode	Inline	设置编辑器可见性（内联/可展开/折叠）
`AxisInputOption`	AxisInputOption	Simple	控制渐变坐标轴输入的复杂度

Key Events

关键事件

Event	Args	Purpose
`SelectedBrushChanged`	SelectedBrushChangedEventArgs	Fired when selected brush changes

Event Args:

OldBrush

(previous selection) ·

NewBrush

(new selection)

事件	参数	用途
`SelectedBrushChanged`	SelectedBrushChangedEventArgs	当选中的画刷发生变化时触发

事件参数：

OldBrush

（之前的选择） ·

NewBrush

（新选择）

Common Use Cases

常见用例

Theme Color Selector — Let users customize app theme colors
Drawing Tool — Color selection for graphic/drawing applications
Style Editor — UI element color customization in design tools
Gradient Background Editor — Create gradient backgrounds or visual effects
Color Palette Manager — Manage color palettes in creative applications

主题颜色选择器 — 允许用户自定义应用主题颜色
绘图工具 — 图形/绘图应用中的颜色选择
样式编辑器 — 设计工具中UI元素的颜色自定义
渐变背景编辑器 — 创建渐变背景或视觉效果
颜色调色板管理器 — 在创意应用中管理颜色调色板