syncfusion-winui-color-picker

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

何时使用此技能

当用户需要以下操作时，立即使用此技能：

• 在 WinUI 应用程序中实现颜色选取器 UI
• 使用多种颜色模型（RGB、HSV、HSL、CMYK）选择纯色
• 创建渐变画刷（线性或径向）
• 自定义颜色光谱形状（方框或圆环）
• 提供带 alpha/不透明度控制的颜色编辑功能
• 在纯色和渐变画刷模式之间切换
• 输入/输出十六进制颜色值
• 处理颜色选取更改事件
• 自定义颜色通道输入选项（滑块、文本输入）
• 以编程方式选择颜色画刷

此技能专用于 Syncfusion WinUI Color Picker（SfColorPicker）控件，而非通用颜色选取解决方案。

组件概述

SfColorPicker 是一个用于选取和调整颜色值的 WinUI 控件。它支持：

• 纯色：支持 RGB、HSV、HSL、CMYK 颜色模型，并提供十六进制编辑器
• 渐变画刷：线性和径向渐变颜色画刷，支持多个色标
• 颜色光谱：通过方框或圆环形状交互式选取颜色
• 不透明度控制：通过滑块和文本输入调整 alpha 通道
• 模式切换：在纯色和渐变模式之间动态切换
• 事件通知：实时颜色选取更改事件

主要命名空间：

using Syncfusion.UI.Xaml.Editors;

NuGet 包：

Syncfusion.Editors.WinUI

---

文档与导航指南

开始使用 SfColorPicker

📄 阅读： references/getting-started.md

在以下情况下阅读此参考：

• 需要安装说明和 NuGet 包设置指南
• 需要实现基本的 SfColorPicker 控件
• 需要了解命名空间和程序集引用
• 需要包含事件处理的首个可运行 XAML + C# 示例
• 需要了解控件结构并排查设置问题

涵盖主题：

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

---

纯色选取

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

在以下情况下阅读此参考：

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

涵盖主题：

• 用于以编程方式和交互式选取的 SelectedBrush 属性
• ColorChannelOptions（RGB、HSV、HSL、CMYK）及用法示例
• 用于限制为仅纯色模式的 BrushTypeOptions
• 用于不透明度控制的 AlphaInputOptions（All、TextInput、SliderInput）
• 用于控制十六进制编辑器可见性的 IsHexInputVisible
• ColorChannelInputOptions（TextInput、SliderInput、All）
• ColorEditorsVisibilityMode（Inline、Expandable、Collapsed）
• SelectedBrushChanged 事件处理

---

渐变颜色选择

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

在以下情况下阅读此参考：

• 创建包含多个颜色停靠点的线性渐变画刷
• 创建具有渐变起点和中心的径向渐变画刷
• 以编程方式配置渐变画刷
• 在运行时交互式编辑渐变
• 调整渐变角度和方向
• 修改渐变偏移量（起点/终点、半径）
• 控制渐变不透明度
• 处理渐变颜色更改事件

涵盖主题：

• 使用 GradientStop、StartPoint、EndPoint 的 LinearGradientBrush
• 使用 GradientOrigin、Center、RadiusX、RadiusY 的 RadialGradientBrush
• 使用 BrushTypeOptions 交互式创建渐变
• AxisInputOption — 简单（角度/方向）与高级（精确编辑器）
• 添加、删除和重新排序渐变停靠点
• 渐变不透明度控制
• 渐变画刷的 SelectedBrushChanged 事件

---

UI 自定义与模式

📄 阅读： references/ui-customization.md

在以下情况下阅读此参考：

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

涵盖主题：

• BrushTypeOptions 配置（SolidColorBrush、LinearGradientBrush、RadialGradientBrush、All）
• 交互式画刷模式下拉菜单行为
• ColorSpectrumShape（方框或圆环）及适用场景说明
• ColorSpectrumComponents（SaturationValue、HueSaturation、HueValue 等）
• 适用于不同应用类型的常见自定义模式

---

最佳实践与故障排除

📄 阅读： references/best-practices.md

在以下情况下阅读此参考：

• 了解何时使用纯色或渐变颜色
• 获取渐变性能优化建议
• 了解常见用例的实现模式
• 排查颜色选择或渲染问题
• 了解无障碍注意事项
• 了解集成模式（弹出层、对话框、属性面板）

涵盖主题：

• 纯色与渐变的决策矩阵
• 性能建议：渐变停靠点数量限制、缓存画刷、防抖事件
• 常见用例：主题选择器、绘图工具、文本荧光笔、背景编辑器
• 弹出层、对话框和属性面板集成模式
• 常见错误（画刷类型不匹配、缺少 null 检查）
• 无障碍：键盘导航、ARIA 属性、屏幕阅读器支持

---

快速入门示例

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# 代码隐藏

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

---

常见模式

模式 1：仅使用纯色选择器

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

模式 2：仅使用渐变编辑器

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

模式 3：以编程方式选择颜色

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

模式 4：自定义光谱形状

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

---

关键属性参考

属性	类型	默认值	用途
SelectedBrush	Brush	Blue	获取/设置选中的颜色画刷
BrushTypeOptions	BrushTypeOptions	All	启用特定画刷模式（Solid、Linear、Radial）
ColorChannelOptions	ColorChannelOptions	RGB	设置颜色模型（RGB、HSV、HSL、CMYK）
ColorSpectrumShape	ColorSpectrumShape	Box	设置色谱形状（Box 或 Ring）
ColorSpectrumComponents	ColorSpectrumComponents	SaturationValue	定义色谱坐标轴
AlphaInputOptions	ColorInputOptions	All	控制 alpha/不透明度输入的可见性
IsHexInputVisible	bool	true	显示/隐藏十六进制编辑器
ColorChannelInputOptions	ColorInputOptions	All	控制通道输入类型（Slider/Text/All）
ColorEditorsVisibilityMode	ColorEditorsVisibilityMode	Inline	设置编辑器的可见性（Inline/Expandable/Collapsed）
AxisInputOption	AxisInputOption	Simple	控制渐变坐标轴输入的复杂程度

关键事件

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

事件参数： OldBrush（先前选中的画刷） · NewBrush（新选中的画刷）

---

常见用例

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