syncfusion-winui-color-palette

何时使用此技能

当用户遇到以下情况时，请立即使用此技能：

• 需要在 WinUI 应用程序中实现基于色块的调色板 UI
• 想要显示带有不同色阶的主题颜色
• 需要显示带有或不带有色阶变体的标准颜色
• 需要向主题调色板或标准调色板中添加自定义颜色
• 想要打开“更多颜色”对话框，以便选择更多颜色
• 需要添加“无颜色”（透明）选项
• 想要跟踪从“更多颜色”对话框中最近选择的颜色
• 需要通过 SelectedBrush 以编程方式设置或获取所选颜色
• 需要自定义调色板标题、标题模板或颜色色阶间距
• 需要更改布局流向或前景样式
• 想要设置一种自动/默认颜色，以便用户轻松恢复

此技能专用于 Syncfusion WinUI Color Palette 控件（SfColorPalette），不适用于基于渐变或色谱的颜色选择器。

组件概览

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

• 主题颜色：内置调色板主题（Office、Yellow、Green 等），带有不同色阶
• 标准颜色：一组固定的标准颜色，可选择是否显示色阶变体
• 自定义颜色：向主题或标准调色板添加自定义颜色
• 更多颜色对话框：通过色谱和不透明度控制扩展选择范围
• 最近使用的颜色：跟踪从“更多颜色”对话框中选择的颜色
• 自动颜色：默认/自动颜色按钮，可配置颜色
• 无颜色选项：透明颜色选择按钮
• 工具提示支持：悬停时显示颜色名称
• 编程访问：通过 SelectedBrush 获取/设置所选颜色
• 事件通知：使用 SelectedBrushChanged 实时检测更改

主要命名空间：

using Syncfusion.UI.Xaml.Editors;

NuGet 包：

Syncfusion.Editors.WinUI

文档与导航指南

SfColorPalette 入门

📄 阅读： references/getting-started.md

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

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

涵盖主题：

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

---

主题颜色

📄 阅读： references/theme-colors.md

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

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

涵盖主题：

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

---

标准颜色

📄 阅读： references/standard-colors.md

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

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

涵盖主题：

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

---

更多颜色对话框

📄 阅读： references/more-color-dialog.md

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

• 启用或禁用“更多颜色”按钮
• 了解“更多颜色”对话框的工作方式
• 隐藏“更多颜色”选项以限制颜色选择

涵盖主题：

• ShowMoreColorsButton 属性
• 从色谱对话框中选择自定义颜色
• 隐藏“更多颜色”按钮

---

UI 自定义

📄 阅读： references/ui-customization.md

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

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

涵盖主题：

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

---

最佳实践与故障排除

📄 阅读： references/best-practices.md

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

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

涵盖主题：

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

---

快速入门示例

以下是一个帮助你开始使用 SfColorPalette 的最简示例：

XAML 实现

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

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

---

常见模式

模式 1：包含主题和标准颜色的基本调色板

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

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

<editors:SfColorPalette ActivePalette="Yellow" Name="colorPalette" />

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

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

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

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

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

模式 5：启用所有选项

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

---

关键属性参考

属性	类型	默认值	用途
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	基色与不同深浅变体之间的间距

---

关键事件

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

事件参数属性：

• OldBrush — 之前选中的画笔
• NewBrush — 新选中的画笔

---

常见使用场景

1. 文档编辑器 — 选择字体和高亮颜色（类似 MS Word 调色板）
2. 主题自定义工具 — 允许用户从品牌或主题颜色中进行选择
3. 绘图/批注工具 — 用于画笔、荧光笔或形状填充的颜色选择器
4. 表单设计工具 — 选择表单元素的背景色和文本颜色
5. 仪表板构建器 — 从预定义调色板中为组件分配颜色

---

后续步骤

1. 从简单开始： 从入门指南开始进行基本设置
2. 主题颜色： 使用主题颜色自定义调色板主题
3. 标准颜色： 通过标准颜色配置标准颜色面板
4. 更多颜色： 使用更多颜色对话框添加扩展颜色对话框
5. 自定义 UI： 应用 UI 自定义中的视觉自定义设置
6. 优化： 查看最佳实践，实现适用于生产环境的方案

---

注意： 此技能专注于 Syncfusion WinUI Color Palette 控件（SfColorPalette）。如需基于渐变/光谱的颜色选择，请参阅 syncfusion-winui-colorpicker 技能。