syncfusion-winui-color-palette

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When to Use This Skill

何时使用本技能

Use this skill immediately when the user:

Needs to implement a color palette (swatch-based) UI in WinUI applications
Wants to display theme colors with their variant shades
Needs to show standard colors with or without color shade variants
Requires adding custom colors to the theme or standard color palette
Wants to open a More Colors dialog for extended color selection
Needs a "No Color" (transparent) selection option
Wants to track recently used colors from the More Colors dialog
Needs to set or get the selected color programmatically via
```
SelectedBrush
```
Requires customizing palette headers, header templates, or color shade spacing
Needs to change layout flow direction or foreground styling
Wants to set an automatic/default color that users can restore easily

This skill is specifically for the Syncfusion WinUI Color Palette control (

SfColorPalette

), not for gradient-based or spectrum-based color pickers.

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

需要在WinUI应用中实现基于色板的调色板UI
希望显示带有变体色调的主题色
需要显示带或不带色调变体的标准色
需在主题或标准调色板中添加自定义颜色
想要打开「更多颜色」对话框以进行扩展颜色选择
需要「无颜色」（透明）选择选项
希望跟踪从「更多颜色」对话框中选择的最近使用颜色
需要通过
```
SelectedBrush
```
以编程方式设置或获取选中的颜色
需自定义调色板标题、标题模板或色调间距
需要更改布局流向或前景样式
想要设置用户可轻松恢复的自动/默认颜色

本技能专门针对Syncfusion WinUI Color Palette控件（

SfColorPalette

），不适用于基于渐变或光谱的颜色选择器。

Component Overview

组件概述

The SfColorPalette is a WinUI control that provides a swatch-based color selection interface. It supports:

Theme Colors: Built-in palette themes (Office, Yellow, Green, etc.) with variant shades
Standard Colors: Fixed set of standard colors with optional shade variants
Custom Colors: Add your own colors to theme or standard palettes
More Colors Dialog: Extended selection via color spectrum with opacity control
Recent Colors: Tracks colors selected from the More Colors dialog
Automatic Color: Default/automatic color button with configurable color
No Color Option: Transparent color selection button
Tooltip Support: Color name shown on hover
Programmatic Access: Get/set selected color via
```
SelectedBrush
```
Event Notifications:
```
SelectedBrushChanged
```
for real-time change detection

Key Namespace:

csharp

using Syncfusion.UI.Xaml.Editors;

NuGet Package:

Syncfusion.Editors.WinUI

SfColorPalette是一款WinUI控件，提供基于色板的颜色选择界面。它支持：

主题色：内置调色板主题（Office、Yellow、Green等）及变体色调
标准色：固定的标准色集合，可选择是否显示色调变体
自定义颜色：在主题或标准调色板中添加自有颜色
更多颜色对话框：通过带透明度控制的颜色光谱进行扩展选择
最近使用颜色：跟踪从「更多颜色」对话框中选择的颜色
自动颜色：可配置的默认/自动颜色按钮
无颜色选项：透明颜色选择按钮
提示框支持：悬停时显示颜色名称
编程访问：通过
```
SelectedBrush
```
获取/设置选中颜色
事件通知：
```
SelectedBrushChanged
```
用于实时检测颜色变化

关键命名空间：

csharp

using Syncfusion.UI.Xaml.Editors;

NuGet包：

Syncfusion.Editors.WinUI

Documentation and Navigation Guide

文档与导航指南

Getting Started with SfColorPalette

SfColorPalette快速入门

📄 Read: references/getting-started.md

Read this reference when you need:

Installation and NuGet package setup instructions
Basic
```
SfColorPalette
```
control implementation
Namespace and assembly references
Accessing and setting selected color programmatically
Handling the SelectedBrushChanged event
Showing/hiding No Color button
First working XAML + C# example with minimal configuration

Topics covered:

Creating a WinUI 3 desktop application
Adding
```
Syncfusion.Editors.WinUI
```
NuGet package
Importing the control namespace
Basic XAML and C# initialization
SelectedBrush property (get/set)
SelectedBrushChanged event handling
ShowNoColorButton property
ShowMoreColorsButton property
RecentColors collection
Control structure overview

📄 阅读： references/getting-started.md

当你需要以下内容时阅读本参考文档：

安装与NuGet包设置说明
```
SfColorPalette
```
控件的基础实现
命名空间与程序集引用
以编程方式访问和设置选中颜色
处理SelectedBrushChanged事件
显示/隐藏「无颜色」按钮
第一个最简配置的XAML + C#可运行示例

涵盖主题：

创建WinUI 3桌面应用
添加
```
Syncfusion.Editors.WinUI
```
NuGet包
导入控件命名空间
基础XAML与C#初始化
SelectedBrush属性（获取/设置）
SelectedBrushChanged事件处理
ShowNoColorButton属性
ShowMoreColorsButton属性
RecentColors集合
控件结构概述

Theme Colors

主题色

📄 Read: references/theme-colors.md

Read this reference when you need:

Selecting colors from built-in theme palettes
Switching the active theme palette at runtime
Adding custom colors to the theme palette
Showing or hiding base theme colors
Showing or hiding theme color variant shades
Customizing the theme palette header text or template
Hiding the theme palette header
Adjusting spacing between base colors and their variants

Topics covered:

ActivePalette property and available ColorPaletteNames
PaletteColors property (ColorPaletteModel)
PaletteColors.ShowColors — show/hide base theme colors
PaletteColors.ShowColorShades — show/hide variant shades
PaletteColors.Colors — adding custom ColorModel entries
PaletteColors.Header — custom header text
PaletteColors.ShowHeader — header visibility
PaletteColors.HeaderTemplate — custom header UI
PaletteColors.ColorShadesSpacing — variant spacing
Hiding the entire theme palette

📄 阅读： references/theme-colors.md

当你需要以下内容时阅读本参考文档：

从内置主题调色板中选择颜色
在运行时切换活动主题调色板
向主题调色板添加自定义颜色
显示或隐藏基础主题色
显示或隐藏主题色变体色调
自定义主题调色板标题文本或模板
隐藏主题调色板标题
调整基础颜色与其变体之间的间距

涵盖主题：

ActivePalette属性及可用的ColorPaletteNames
PaletteColors属性（ColorPaletteModel）
PaletteColors.ShowColors — 显示/隐藏基础主题色
PaletteColors.ShowColorShades — 显示/隐藏变体色调
PaletteColors.Colors — 添加自定义ColorModel条目
PaletteColors.Header — 自定义标题文本
PaletteColors.ShowHeader — 标题可见性
PaletteColors.HeaderTemplate — 自定义标题UI
PaletteColors.ColorShadesSpacing — 变体间距
隐藏整个主题调色板

Standard Colors

标准色

📄 Read: references/standard-colors.md

Read this reference when you need:

Selecting colors from the built-in standard colors panel
Adding custom colors to the standard color palette
Showing or hiding standard color variant shades
Hiding the standard colors panel entirely
Customizing the standard palette header text or template
Hiding the standard palette header
Adjusting spacing between standard colors and their variants

Topics covered:

StandardColors property (StandardPaletteModel)
StandardColors.ShowColors — show/hide standard colors
StandardColors.ShowColorShades — show/hide variant shades
StandardColors.Colors — adding custom ColorModel entries
StandardColors.Header — custom header text
StandardColors.ShowHeader — header visibility
StandardColors.HeaderTemplate — custom header UI
StandardColors.ColorShadesSpacing — variant spacing
Hiding the entire standard colors panel

📄 阅读： references/standard-colors.md

当你需要以下内容时阅读本参考文档：

从内置标准色面板中选择颜色
向标准调色板添加自定义颜色
显示或隐藏标准色变体色调
完全隐藏标准色面板
自定义标准调色板标题文本或模板
隐藏标准调色板标题
调整标准颜色与其变体之间的间距

涵盖主题：

StandardColors属性（StandardPaletteModel）
StandardColors.ShowColors — 显示/隐藏标准色
StandardColors.ShowColorShades — 显示/隐藏变体色调
StandardColors.Colors — 添加自定义ColorModel条目
StandardColors.Header — 自定义标题文本
StandardColors.ShowHeader — 标题可见性
StandardColors.HeaderTemplate — 自定义标题UI
StandardColors.ColorShadesSpacing — 变体间距
隐藏整个标准色面板

More Color Dialog

UI Customization

UI自定义

📄 Read: references/ui-customization.md

Read this reference when you need:

Setting or getting the selected color programmatically
Setting a null/transparent color value
Configuring the automatic (default) color button
Hiding the default color button
Customizing palette header foreground color
Changing flow direction (right-to-left support)
Understanding tooltip behavior for color items
Working with recently used colors panel

Topics covered:

SelectedBrush property (programmatic access)
Setting null/transparent color (Colors.Transparent)
AutomaticBrush property — default color configuration
ShowDefaultColorButton property — default color button visibility
Foreground property — header text color
FlowDirection property — RTL support
Tooltip behavior for color items
RecentColors collection — recently used colors

📄 阅读： references/ui-customization.md

当你需要以下内容时阅读本参考文档：

以编程方式设置或获取选中颜色
设置空/透明颜色值
配置自动（默认）颜色按钮
隐藏默认颜色按钮
自定义调色板标题前景色
更改流向（支持从右到左）
了解颜色项的提示框行为
使用最近使用颜色面板

涵盖主题：

SelectedBrush属性（编程访问）
设置空/透明颜色（Colors.Transparent）
AutomaticBrush属性 — 默认颜色配置
ShowDefaultColorButton属性 — 默认颜色按钮可见性
Foreground属性 — 标题文本颜色
FlowDirection属性 — RTL支持
颜色项的提示框行为
RecentColors集合 — 最近使用颜色

Best Practices and Troubleshooting

最佳实践与故障排除

📄 Read: references/best-practices.md

Read this reference when you need:

Guidance on when to use SfColorPalette vs SfColorPicker
Common implementation patterns and use cases
Troubleshooting color selection or display issues
Understanding edge cases and limitations
Accessibility considerations
Integration with flyouts, dialogs, and property panels

Topics covered:

When to use palette vs picker
Common use cases (theme selector, document editor, drawing tool)
Troubleshooting guide
Edge cases to avoid
Accessibility best practices
Integration patterns (flyout, dialog, property panel)

📄 阅读： references/best-practices.md

当你需要以下内容时阅读本参考文档：

指导何时使用SfColorPalette vs SfColorPicker
常见实现模式与使用场景
排查颜色选择或显示问题
了解边缘情况与限制
无障碍设计注意事项
与弹出层、对话框和属性面板的集成

涵盖主题：

何时使用调色板vs选择器
常见使用场景（主题选择器、文档编辑器、绘图工具）
故障排除指南
需避免的边缘情况
无障碍设计最佳实践
集成模式（弹出层、对话框、属性面板）

Quick Start Example

快速入门示例

Here's a minimal example to get started with SfColorPalette:

以下是SfColorPalette的最简入门示例：

XAML Implementation

XAML实现

xml

<Page
    x:Class="ColorPaletteApp.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 Padding="20">
        <!-- Basic Color Palette -->
        <editors:SfColorPalette 
            x:Name="colorPalette"
            ShowMoreColorsButton="True"
            ShowNoColorButton="True"
            SelectedBrushChanged="ColorPalette_SelectedBrushChanged" />
    </Grid>
</Page>

xml

<Page
    x:Class="ColorPaletteApp.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 Padding="20">
        <!-- 基础调色板 -->
        <editors:SfColorPalette 
            x:Name="colorPalette"
            ShowMoreColorsButton="True"
            ShowNoColorButton="True"
            SelectedBrushChanged="ColorPalette_SelectedBrushChanged" />
    </Grid>
</Page>

C# Code-Behind

C#代码后置

csharp

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

namespace ColorPaletteApp
{
    public sealed partial class MainPage : Page
    {
        public MainPage()
        {
            this.InitializeComponent();
        }

        private void ColorPalette_SelectedBrushChanged(object sender, SelectedBrushChangedEventArgs e)
        {
            var oldBrush = e.OldBrush;
            var newBrush = e.NewBrush;

            // Apply selected color to a target element
            if (newBrush is SolidColorBrush solidBrush)
            {
                targetRectangle.Fill = solidBrush;
            }
        }
    }
}

csharp

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

namespace ColorPaletteApp
{
    public sealed partial class MainPage : Page
    {
        public MainPage()
        {
            this.InitializeComponent();
        }

        private void ColorPalette_SelectedBrushChanged(object sender, SelectedBrushChangedEventArgs e)
        {
            var oldBrush = e.OldBrush;
            var newBrush = e.NewBrush;

            // 将选中颜色应用到目标元素
            if (newBrush is SolidColorBrush solidBrush)
            {
                targetRectangle.Fill = solidBrush;
            }
        }
    }
}

Common Patterns

常见模式

Pattern 1: Basic Palette with Theme and Standard Colors

模式1：包含主题色与标准色的基础调色板

xml

<editors:SfColorPalette Name="colorPalette">
    <editors:SfColorPalette.PaletteColors>
        <editors:ColorPaletteModel ShowColorShades="True"/>
    </editors:SfColorPalette.PaletteColors>
    <editors:SfColorPalette.StandardColors>
        <editors:StandardPaletteModel ShowColorShades="True"/>
    </editors:SfColorPalette.StandardColors>
</editors:SfColorPalette>

xml

<editors:SfColorPalette Name="colorPalette">
    <editors:SfColorPalette.PaletteColors>
        <editors:ColorPaletteModel ShowColorShades="True"/>
    </editors:SfColorPalette.PaletteColors>
    <editors:SfColorPalette.StandardColors>
        <editors:StandardPaletteModel ShowColorShades="True"/>
    </editors:SfColorPalette.StandardColors>
</editors:SfColorPalette>

Pattern 2: Active Palette (Theme Switching)

模式2：活动调色板（主题切换）

xml

<!-- Show "Yellow" theme colors by default -->
<editors:SfColorPalette ActivePalette="Yellow" Name="colorPalette" />

csharp

// Switch theme programmatically
colorPalette.ActivePalette = ColorPaletteNames.Office;

xml

<!-- 默认显示"Yellow"主题色 -->
<editors:SfColorPalette ActivePalette="Yellow" Name="colorPalette" />

csharp

// 以编程方式切换主题
colorPalette.ActivePalette = ColorPaletteNames.Office;

Pattern 3: Custom Theme and Standard Colors

模式3：自定义主题色与标准色

xml

<editors:SfColorPalette Name="colorPalette">
    <editors:SfColorPalette.PaletteColors>
        <editors:ColorPaletteModel ShowColors="True" ShowColorShades="True" Header="Brand Colors">
            <editors:ColorPaletteModel.Colors>
                <editors:ColorCollection>
                    <editors:ColorModel Color="#FF1464A0" Tooltip="Brand Blue" />
                    <editors:ColorModel Color="#FF00A651" Tooltip="Brand Green" />
                    <editors:ColorModel Color="#FFFF6600" Tooltip="Brand Orange" />
                </editors:ColorCollection>
            </editors:ColorPaletteModel.Colors>
        </editors:ColorPaletteModel>
    </editors:SfColorPalette.PaletteColors>
</editors:SfColorPalette>

xml

<editors:SfColorPalette Name="colorPalette">
    <editors:SfColorPalette.PaletteColors>
        <editors:ColorPaletteModel ShowColors="True" ShowColorShades="True" Header="品牌色">
            <editors:ColorPaletteModel.Colors>
                <editors:ColorCollection>
                    <editors:ColorModel Color="#FF1464A0" Tooltip="品牌蓝" />
                    <editors:ColorModel Color="#FF00A651" Tooltip="品牌绿" />
                    <editors:ColorModel Color="#FFFF6600" Tooltip="品牌橙" />
                </editors:ColorCollection>
            </editors:ColorPaletteModel.Colors>
        </editors:ColorModel>
    </editors:SfColorPalette.PaletteColors>
</editors:SfColorPalette>

Pattern 4: Programmatic Color Selection

模式4：编程式颜色选择

csharp

// Set selected color
colorPalette.SelectedBrush = new SolidColorBrush(Colors.Yellow);

// Set transparent/no color
colorPalette.SelectedBrush = new SolidColorBrush(Colors.Transparent);

// Read selected color
if (colorPalette.SelectedBrush is SolidColorBrush brush)
{
    var color = brush.Color;
}

csharp

// 设置选中颜色
colorPalette.SelectedBrush = new SolidColorBrush(Colors.Yellow);

// 设置透明/无颜色
colorPalette.SelectedBrush = new SolidColorBrush(Colors.Transparent);

// 读取选中颜色
if (colorPalette.SelectedBrush is SolidColorBrush brush)
{
    var color = brush.Color;
}

Pattern 5: Enable All Options

模式5：启用所有选项

xml

<editors:SfColorPalette 
    ShowMoreColorsButton="True"
    ShowNoColorButton="True"
    AutomaticBrush="Black"
    ShowDefaultColorButton="True"
    Name="colorPalette" />

xml

<editors:SfColorPalette 
    ShowMoreColorsButton="True"
    ShowNoColorButton="True"
    AutomaticBrush="Black"
    ShowDefaultColorButton="True"
    Name="colorPalette" />

Key Properties Reference

关键属性参考

Property	Type	Default	Purpose
SelectedBrush	Brush	Transparent	Gets or sets the currently selected color
ActivePalette	ColorPaletteNames	Office	Sets the active built-in theme palette
PaletteColors	ColorPaletteModel	—	Configures theme color panel
StandardColors	StandardPaletteModel	—	Configures standard color panel
ShowMoreColorsButton	bool	true	Shows/hides the More Colors button
ShowNoColorButton	bool	false	Shows/hides the No Color (transparent) button
AutomaticBrush	Brush	Black	Sets the default/automatic color
ShowDefaultColorButton	bool	true	Shows/hides the default color button
RecentColors	Collection	—	Gets the recently used colors list
Foreground	Brush	Black	Sets header text foreground color
FlowDirection	FlowDirection	LeftToRight	Sets RTL/LTR layout direction

ColorPaletteModel / StandardPaletteModel Properties:

Property	Type	Default	Purpose
ShowColors	bool	true	Shows/hides base colors
ShowColorShades	bool	true/false	Shows/hides variant shades
Colors	ColorCollection	—	Custom color entries
Header	string	"Theme Colors" / "Standard Colors"	Panel header text
ShowHeader	bool	true	Shows/hides the header
HeaderTemplate	DataTemplate	—	Custom header UI
ColorShadesSpacing	double	10	Space between base color and shades

属性	类型	默认值	用途
SelectedBrush	Brush	Transparent	获取或设置当前选中的颜色
ActivePalette	ColorPaletteNames	Office	设置活动的内置主题调色板
PaletteColors	ColorPaletteModel	—	配置主题色面板
StandardColors	StandardPaletteModel	—	配置标准色面板
ShowMoreColorsButton	bool	true	显示/隐藏「更多颜色」按钮
ShowNoColorButton	bool	false	显示/隐藏「无颜色」（透明）按钮
AutomaticBrush	Brush	Black	设置默认/自动颜色
ShowDefaultColorButton	bool	true	显示/隐藏默认颜色按钮
RecentColors	Collection	—	获取最近使用颜色列表
Foreground	Brush	Black	设置标题文本前景色
FlowDirection	FlowDirection	LeftToRight	设置RTL/LTR布局流向

ColorPaletteModel / StandardPaletteModel属性：

属性	类型	默认值	用途
ShowColors	bool	true	显示/隐藏基础颜色
ShowColorShades	bool	true/false	显示/隐藏变体色调
Colors	ColorCollection	—	自定义颜色条目
Header	string	"Theme Colors" / "Standard Colors"	面板标题文本
ShowHeader	bool	true	显示/隐藏标题
HeaderTemplate	DataTemplate	—	自定义标题UI
ColorShadesSpacing	double	10	基础颜色与其变体之间的间距

Key Events

关键事件

Event	Args	Purpose
SelectedBrushChanged	SelectedBrushChangedEventArgs	Fired when selected color changes

Event Args Properties:

```
OldBrush
```
— Previously selected brush
```
NewBrush
```
— Newly selected brush

事件	参数	用途
SelectedBrushChanged	SelectedBrushChangedEventArgs	选中颜色变化时触发

事件参数属性：

```
OldBrush
```
— 之前选中的画刷
```
NewBrush
```
— 新选中的画刷

Common Use Cases

常见使用场景

Document Editor — Font and highlight color selection (like MS Word color palette)
Theme Customizer — Let users pick from brand or theme colors
Drawing/Annotation Tool — Color picker for pen, highlighter, or shape fill
Form Design Tool — Background and text color selection for form elements
Dashboard Builder — Widget color assignment from a predefined palette

文档编辑器 — 字体与高亮颜色选择（类似MS Word调色板）
主题定制器 — 让用户从品牌色或主题色中选择
绘图/标注工具 — 画笔、荧光笔或形状填充的颜色选择器
表单设计工具 — 表单元素的背景与文本颜色选择
仪表板构建器 — 从预定义调色板中为组件分配颜色

Next Steps

下一步

Start Simple: Begin with getting-started.md for basic setup
Theme Colors: Customize palette themes using theme-colors.md
Standard Colors: Configure standard color panel via standard-colors.md
More Colors: Add extended color dialog using more-color-dialog.md
Customize UI: Apply visual customizations from ui-customization.md
Optimize: Review best-practices.md for production-ready implementation

Note: This skill focuses on the Syncfusion WinUI Color Palette control (

SfColorPalette

). For gradient/spectrum-based color picking, refer to the

syncfusion-winui-colorpicker

skill.

undefined

从简开始：阅读getting-started.md完成基础设置
主题色：使用theme-colors.md自定义调色板主题
标准色：通过standard-colors.md配置标准色面板
更多颜色：使用more-color-dialog.md添加扩展颜色对话框
自定义UI：参考ui-customization.md应用视觉自定义
优化实现：查看best-practices.md完成生产级实现

注意： 本技能聚焦于Syncfusion WinUI Color Palette控件（

SfColorPalette

）。如需基于渐变/光谱的颜色选择，请参考

syncfusion-winui-colorpicker

技能。

undefined

syncfusion-winui-color-palette

Original

Translation

When to Use This Skill

何时使用本技能

Component Overview

组件概述

Documentation and Navigation Guide

文档与导航指南

Getting Started with SfColorPalette

SfColorPalette快速入门

Theme Colors

主题色

Standard Colors

标准色

More Color Dialog

更多颜色对话框

UI Customization

UI自定义

Best Practices and Troubleshooting

最佳实践与故障排除

Quick Start Example

快速入门示例

XAML Implementation

XAML实现

C# Code-Behind

C#代码后置

Common Patterns

常见模式

Pattern 1: Basic Palette with Theme and Standard Colors

模式1：包含主题色与标准色的基础调色板

Pattern 2: Active Palette (Theme Switching)

模式2：活动调色板（主题切换）

Pattern 3: Custom Theme and Standard Colors

模式3：自定义主题色与标准色

Pattern 4: Programmatic Color Selection

模式4：编程式颜色选择

Pattern 5: Enable All Options

模式5：启用所有选项

Key Properties Reference

关键属性参考

Key Events

关键事件

Common Use Cases

常见使用场景

Next Steps

下一步