syncfusion-winui-color-picker（Synfusion Winui 颜色选择器）

Implementing Syncfusion WinUI Color Picker (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.

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:

using Syncfusion.UI.Xaml.Editors;

NuGet Package:

Syncfusion.Editors.WinUI

Documentation and Navigation Guide

Getting Started with 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

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

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

UI Customization and Modes

📄 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

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

Quick Start Example

XAML

<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

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;
    }
}

Common Patterns

Pattern 1: Solid Color Picker Only

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

Pattern 2: Gradient Editor Only

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

Pattern 3: Programmatic Color Selection

// 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;

Pattern 4: Custom Spectrum Shape

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

Key Properties Reference

Key Events

Event Args: OldBrush (previous selection) · NewBrush (new selection)

Common Use Cases

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