syncfusion-wpf-colorpicker

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing WPF ColorPicker

实现WPF ColorPicker

The ColorPicker is a WPF user interface control for selecting and adjusting color values. It supports multiple color specifications including RGB (Red Green Blue), HSV (Hue Saturation Value), and hexadecimal codes, with built-in gradient editor, eyedropper, color palette, and theming support.

ColorPicker是一款WPF用户界面控件，用于选择和调整颜色值。它支持多种颜色规格，包括RGB（红绿蓝）、HSV（色相饱和度明度）和十六进制代码，内置渐变编辑器、取色器、颜色调色板和主题支持。

When to Use This Skill

何时使用此技能

Use the ColorPicker when you need to:

Allow users to select solid colors in WPF applications
Create linear or radial gradient brushes with multiple color stops
Edit color values manually using RGB, HSV, or Hex input
Include an eyedropper tool for picking colors from anywhere in the app
Control color opacity/alpha channel
Provide a color palette for quick color selection
Handle color-changed and brush-changed events
Apply built-in or custom themes to match application design

在以下场景中使用ColorPicker：

允许用户在WPF应用中选择纯色
创建包含多个颜色停止点的线性或径向渐变画刷
使用RGB、HSV或十六进制输入手动编辑颜色值
集成取色器工具，以便从应用任意位置拾取颜色
控制颜色的透明度/Alpha通道
提供颜色调色板以快速选择颜色
处理颜色变更和画刷变更事件
应用内置或自定义主题以匹配应用设计

Navigation Guide

导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Assembly dependencies and NuGet package setup
Adding ColorPicker via Designer, XAML, and C#
Control structure overview
Basic configuration

📄 阅读： references/getting-started.md

程序集依赖和NuGet包设置
通过设计器、XAML和C#添加ColorPicker
控件结构概述
基础配置

Solid and Gradient Colors

纯色与渐变颜色

📄 Read: references/solid-gradient-colors.md

Selecting solid colors with Color property
Creating linear gradients with StartPoint, EndPoint, and GradientStops
Creating radial gradients with GradientOrigin, Center, RadiusX, RadiusY
Runtime color editing and selection
Managing opacity with alpha channel
Switching between solid, linear, and gradient modes

📄 阅读： references/solid-gradient-colors.md

使用Color属性选择纯色
通过StartPoint、EndPoint和GradientStops创建线性渐变
通过GradientOrigin、Center、RadiusX、RadiusY创建径向渐变
运行时颜色编辑与选择
通过Alpha通道管理透明度
在纯色、线性渐变和径向渐变模式间切换

Customization Options

自定义选项

📄 Read: references/customization.md

Enabling/disabling color palette visibility
Gradient brush display modes (Default vs Extended)
Inverted color calculation for contrast
ScRGB color support
Hiding or showing alpha value editors
Restricting brush mode transitions

📄 阅读： references/customization.md

启用/禁用颜色调色板可见性
渐变画刷显示模式（默认 vs 扩展）
计算对比色的反转颜色
ScRGB颜色支持
隐藏或显示Alpha值编辑器
限制画刷模式切换

Appearance and Theming

外观与主题

📄 Read: references/appearance-theming.md

Built-in theme support
SfSkinManager integration for theme application
ThemeStudio custom theme creation
Theme-based appearance customization

📄 阅读： references/appearance-theming.md

内置主题支持
集成SfSkinManager以应用主题
使用ThemeStudio创建自定义主题
基于主题的外观自定义

Events and Integration

事件与集成

📄 Read: references/events-integration.md

ColorChanged event handling
SelectedBrushChanged event handling
Runtime color change notifications
Integration patterns with other controls

📄 阅读： references/events-integration.md

ColorChanged事件处理
SelectedBrushChanged事件处理
运行时颜色变更通知
与其他控件的集成模式

Quick Start

快速开始

Basic XAML Setup

基础XAML配置

xaml

<Window xmlns:syncfusion="http://schemas.syncfusion.com/wpf">
    <Grid>
        <syncfusion:ColorPicker Name="colorPicker" 
                                Width="280" 
                                Height="100"/>
    </Grid>
</Window>

xaml

<Window xmlns:syncfusion="http://schemas.syncfusion.com/wpf">
    <Grid>
        <syncfusion:ColorPicker Name="colorPicker" 
                                Width="280" 
                                Height="100"/>
    </Grid>
</Window>

Basic C# Setup

基础C#配置

csharp

using Syncfusion.Windows.Shared;

ColorPicker colorPicker = new ColorPicker();
colorPicker.Width = 300;
colorPicker.Height = 100;
grid.Children.Add(colorPicker);

csharp

using Syncfusion.Windows.Shared;

ColorPicker colorPicker = new ColorPicker();
colorPicker.Width = 300;
colorPicker.Height = 100;
grid.Children.Add(colorPicker);

Set Initial Color

设置初始颜色

xaml

<syncfusion:ColorPicker Color="Yellow" />

xaml

<syncfusion:ColorPicker Color="Yellow" />

Common Patterns

常见模式

Pattern 1: Solid Color Selection

模式1：纯色选择

Use when you need users to pick a single solid color for a brush or property.

xaml

<syncfusion:ColorPicker x:Name="solidColorPicker"
                        Color="Blue"
                        IsColorPaletteVisible="True"/>

当需要用户为画刷或属性选择单一纯色时使用。

xaml

<syncfusion:ColorPicker x:Name="solidColorPicker"
                        Color="Blue"
                        IsColorPaletteVisible="True"/>

Pattern 2: Gradient Selection

模式2：渐变选择

Use when you need users to create linear or radial gradients for advanced styling.

xaml

<syncfusion:ColorPicker x:Name="gradientPicker" Width="200">
    <syncfusion:ColorPicker.Brush>
        <LinearGradientBrush StartPoint="0,0" EndPoint="1,1">
            <GradientStop Color="Yellow" Offset="0.0" />
            <GradientStop Color="Red" Offset="0.5" />
            <GradientStop Color="Blue" Offset="1.0" />
        </LinearGradientBrush>
    </syncfusion:ColorPicker.Brush>
</syncfusion:ColorPicker>

当需要用户创建线性或径向渐变以实现高级样式时使用。

xaml

<syncfusion:ColorPicker x:Name="gradientPicker" Width="200">
    <syncfusion:ColorPicker.Brush>
        <LinearGradientBrush StartPoint="0,0" EndPoint="1,1">
            <GradientStop Color="Yellow" Offset="0.0" />
            <GradientStop Color="Red" Offset="0.5" />
            <GradientStop Color="Blue" Offset="1.0" />
        </LinearGradientBrush>
    </syncfusion:ColorPicker.Brush>
</syncfusion:ColorPicker>

Pattern 3: Respond to Color Changes

模式3：响应颜色变更

Use when you need to react to user color selections in real-time.

csharp

ColorPicker colorPicker = new ColorPicker();
colorPicker.ColorChanged += ColorPicker_ColorChanged;
colorPicker.SelectedBrushChanged += ColorPicker_SelectedBrushChanged;

private void ColorPicker_ColorChanged(DependencyObject d, 
                                      DependencyPropertyChangedEventArgs e)
{
    // Handle color change
    Color selectedColor = (Color)e.NewValue;
}

private void ColorPicker_SelectedBrushChanged(DependencyObject d, 
                                              DependencyPropertyChangedEventArgs e)
{
    // Handle brush change
    Brush selectedBrush = (Brush)e.NewValue;
}

当需要实时响应用户颜色选择时使用。

csharp

ColorPicker colorPicker = new ColorPicker();
colorPicker.ColorChanged += ColorPicker_ColorChanged;
colorPicker.SelectedBrushChanged += ColorPicker_SelectedBrushChanged;

private void ColorPicker_ColorChanged(DependencyObject d, 
                                      DependencyPropertyChangedEventArgs e)
{
    // 处理颜色变更
    Color selectedColor = (Color)e.NewValue;
}

private void ColorPicker_SelectedBrushChanged(DependencyObject d, 
                                              DependencyPropertyChangedEventArgs e)
{
    // 处理画刷变更
    Brush selectedBrush = (Brush)e.NewValue;
}

Pattern 4: Hide Alpha Channel

模式4：隐藏Alpha通道

Use when you only need opaque colors without transparency options.

xaml

<syncfusion:ColorPicker IsAlphaVisible="False" />

当仅需要不透明颜色、无需透明度选项时使用。

xaml

<syncfusion:ColorPicker IsAlphaVisible="False" />

Pattern 5: Lock to Solid Colors Only

模式5：仅锁定纯色模式

Use when you want to prevent users from switching to gradient modes.

xaml

<syncfusion:ColorPicker EnableSolidToGradientSwitch="false" />

当需要阻止用户切换到渐变模式时使用。

xaml

<syncfusion:ColorPicker EnableSolidToGradientSwitch="false" />

Key Properties

关键属性

Property	Type	Purpose
`Color`	Color	Gets or sets the selected solid color
`Brush`	Brush	Gets or sets the selected gradient or solid brush
`IsAlphaVisible`	bool	Shows/hides alpha (opacity) controls
`IsColorPaletteVisible`	bool	Shows/hides built-in color palette
`EnableSolidToGradientSwitch`	bool	Allows/prevents switching between modes
`GradientBrushDisplayMode`	enum	Sets display mode (Default or Extended)

属性	类型	用途
`Color`	Color	获取或设置选中的纯色
`Brush`	Brush	获取或设置选中的渐变或纯色画刷
`IsAlphaVisible`	bool	显示/隐藏透明度（Alpha）控件
`IsColorPaletteVisible`	bool	显示/隐藏内置颜色调色板
`EnableSolidToGradientSwitch`	bool	允许/阻止模式间切换
`GradientBrushDisplayMode`	enum	设置显示模式（默认或扩展）

Key Events

关键事件

Event	Triggered When
`ColorChanged`	Selected solid color changes
`SelectedBrushChanged`	Selected brush (gradient) changes

事件	触发时机
`ColorChanged`	选中的纯色发生变更时
`SelectedBrushChanged`	选中的画刷（渐变）发生变更时

Dependencies

依赖项

Assembly: Syncfusion.Shared.WPF
Framework: .NET Framework 4.5+
Dependencies: Syncfusion WPF shared components

程序集： Syncfusion.Shared.WPF
框架： .NET Framework 4.5+
依赖组件： Syncfusion WPF共享组件