syncfusion-wpf-theming

实现 Syncfusion WPF 主题设置

使用 SfSkinManager 为 Syncfusion WPF 控件和框架控件应用专业且可自定义的主题。主题系统提供符合现代设计标准的内置主题（Windows 11、Fluent、Material 3、Office 2019），并支持通过 Theme Studio 工具进行完整自定义。

何时使用此技能

• 应用内置主题： 为整个应用或特定控件选择并应用预设主题
• 自定义主题颜色： 通过编程方式修改主题颜色和字体
• 创建品牌主题： 构建符合应用品牌风格的自定义主题
• 配置视觉效果： 启用或禁用显示动画、亚克力效果和悬停效果
• 多窗口主题设置： 在所有窗口中全局应用主题，或单独应用到各个控件
• 无障碍功能： 配置键盘焦点视觉效果和高对比度主题
• 主题切换： 支持在运行时动态切换主题

快速概览

关键组件：

• SfSkinManager： 为 Syncfusion 和 Framework 控件应用主题（通过 XAML 附加属性或 C# 代码）
• 内置主题： 提供 17 种以上预设主题，包括 Windows 11、Fluent、Material 和 Office 样式
• 自定义主题： 从 Theme Studio 导出后，注册自定义主题并将其集成到应用中

文档与导航指南

开始使用 SfSkinManager

📄 阅读： references/skin-manager-setup.md

• 添加 SfSkinManager 引用和程序集
• 为单个控件应用主题
• 为整个应用全局应用主题
• 了解主题继承（窗口 → 子元素）
• 在 XAML 和 C# 中进行基本实现
• 使用 ApplyThemeAsDefaultStyle 属性

探索内置主题

📄 阅读： references/built-in-themes.md

• 17 种可用主题的完整列表
• 浅色/深色主题变体
• 主题类别：Windows 11、Fluent、Material 3、Material、Office 2019、高对比度、系统
• 主题程序集和 NuGet 包引用
• 为应用选择合适的主题
• 主题与 Syncfusion 和 Framework 控件的兼容性

创建和自定义主题

📄 阅读： references/theme-customization.md

• 从 Theme Studio 导出自定义主题后，按照本文档中的步骤操作
• 通过编程方式自定义颜色和字体
• 使用导出的主题项目
• 生成主题程序集
• 注册并集成自定义主题
• 多框架 SDK 样式的主题项目（.NET 4.6.2、.NET 8.0、.NET 9.0、.NET 10.0）

高级主题功能

📄 阅读： references/theme-features.md

• Fluent 主题显示动画（悬停和按下效果）
• 配置 HoverEffectMode 和 PressedEffectMode
• 窗口亚克力背景效果
• 键盘焦点视觉指示器
• ScrollBar 模式（Native、Compact）
• 配置触控支持

快速入门示例

在 XAML 中应用内置主题

<Window x:Class="MyApp.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:syncfusionskin="clr-namespace:Syncfusion.SfSkinManager;assembly=Syncfusion.SfSkinManager.WPF"
        syncfusionskin:SfSkinManager.Theme="{syncfusionskin:SkinManagerExtension ThemeName=Windows11Light}">
    <Grid>
        
    </Grid>
</Window>

在 C# 中应用主题

using Syncfusion.SfSkinManager;

public partial class MainWindow : Window
{
    public MainWindow()
    {
        // Enable theme as default style
        SfSkinManager.ApplyThemeAsDefaultStyle = true;
        
        // Apply theme to this window and all child controls
        SfSkinManager.SetTheme(this, new Theme("Windows11Light"));
        
        InitializeComponent();
    }
}

为整个应用全局应用主题

public partial class App : Application
{
    protected override void OnStartup(StartupEventArgs e)
    {
        SfSkinManager.ApplyThemeAsDefaultStyle = true;
        SfSkinManager.ApplicationTheme = new Theme("Fluent
Dark");
        
        base.OnStartup(e);
    }
}

常见模式

模式 1：在运行时切换主题

允许用户在应用中动态切换主题：

// Example: Switch theme when user selects from dropdown
private void OnThemeSelectionChanged(string themeName)
{
    SfSkinManager.SetTheme(this, new Theme(themeName));
}

模式 2：将自定义主题与内置主题结合

注册一个基于内置主题派生的自定义主题：

string customThemeName = "MyCustomTheme";
string baseThemeName = "Windows11Light";

// Register custom theme (assuming custom theme assembly is referenced)
SkinHelper customThemeInstance = new MyCustomThemeSkinHelper();
SfSkinManager.RegisterTheme(customThemeName, customThemeInstance);

// Apply the custom theme
SfSkinManager.SetTheme(this, new Theme($"{customThemeName};{baseThemeName}"));

模式 3：通过编程方式自定义主题颜色

在运行时修改特定主题颜色：

// Example: Customize Windows 11 Light theme colors
var themeSettings = new Windows11LightThemeSettings();
themeSettings.Palette = new Windows11Palette 
{ 
    PrimaryColor = Colors.Blue,
    SecondaryColor = Colors.LightBlue
};

SfSkinManager.RegisterThemeSettings("Windows11Light", themeSettings);
SfSkinManager.SetTheme(this, new Theme("Windows11Light"));

主题选择指南

按应用风格选择：

• 现代/Windows 11 原生风格： Windows11Light、Windows11Dark
• Microsoft Fluent Design： FluentLight、FluentDark
• Material Design： Material3Light、Material3Dark、MaterialLight、MaterialDark
• 类似 Office 的风格： Office2019Colorful、Office2019Black、Office2019White、Office2019DarkGray
• 高对比度/无障碍： Office2019HighContrast、Office2019HighContrastWhite
• 跟随操作系统： SystemTheme

浅色与深色：

• 在明亮环境或白天使用浅色主题
• 在弱光环境中使用深色主题，或根据用户偏好选择
• 搭配 SystemTheme，自动匹配操作系统设置

关键属性

属性	用途	类型	默认值
SfSkinManager.Theme	应用的主题名称（XAML 附加属性）	string	None
SfSkinManager.ApplicationTheme	整个应用的全局主题	Theme object	None
HoverEffectMode	悬停时的视觉效果（Fluent 主题）	HoverEffect enum	BackgroundAndBorder
PressedEffectMode	按下时的视觉效果（Fluent 主题）	PressedEffect enum	Reveal
ShowAcrylicBackground	启用亚克力模糊效果（Fluent 主题）	bool	false
ApplyThemeAsDefaultStyle	将主题应用为默认样式资源	bool	false

相关技能

• 自定义主题的创建与导出（Theme Studio 指南）
• 键盘无障碍功能与焦点指示器
• 面向主题化应用的响应式设计