syncfusion-wpf-theming

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Syncfusion WPF Theming

实现Syncfusion WPF主题定制

Apply professional, customizable themes to Syncfusion WPF controls and framework controls using SfSkinManager. The theming system provides built-in themes following modern design standards (Windows 11, Fluent, Material 3, Office 2019) and supports complete customization through the Theme Studio utility.
使用SfSkinManager为Syncfusion WPF控件和框架控件应用专业、可自定义的主题。该主题系统提供遵循现代设计标准的内置主题(Windows 11、Fluent、Material 3、Office 2019),并支持通过Theme Studio工具进行完全自定义。

When to Use This Skill

何时使用此技能

  • Applying built-in themes: Choose and apply pre-designed themes to your entire application or specific controls
  • Customizing theme colors: Modify theme colors and fonts programmatically
  • Creating branded themes: Build custom themes that match your application's branding
  • Configuring visual effects: Enable/disable reveal animations, acrylic effects, and hover effects
  • Multi-window theming: Apply themes globally across all windows or to individual controls
  • Accessibility: Configure keyboard focus visuals and high-contrast themes
  • Theme switching: Support dynamic theme switching at runtime
  • 应用内置主题: 选择并应用预设计主题到整个应用程序或特定控件
  • 自定义主题颜色: 以编程方式修改主题颜色和字体
  • 创建品牌主题: 构建与应用程序品牌匹配的自定义主题
  • 配置视觉效果: 启用/禁用显示动画、亚克力效果和悬停效果
  • 多窗口主题设置: 在所有窗口全局应用主题,或应用到单个控件
  • 辅助功能: 配置键盘焦点视觉效果和高对比度主题
  • 主题切换: 支持运行时动态切换主题

Quick Overview

快速概述

Key Components:
  • SfSkinManager: Applies themes to Syncfusion and Framework controls (XAML attached property or C# code)
  • Built-in Themes: 17+ pre-designed themes including Windows 11, Fluent, Material, and Office styles
  • Custom Themes: After exporting from Theme Studio, register custom themes and integrate into applications
核心组件:
  • SfSkinManager: 为Syncfusion和框架控件应用主题(XAML附加属性或C#代码)
  • 内置主题: 17+款预设计主题,包括Windows 11、Fluent、Material和Office风格
  • 自定义主题: 从Theme Studio导出后,注册自定义主题并集成到应用程序中

Documentation and Navigation Guide

文档与导航指南

Getting Started with SfSkinManager

SfSkinManager入门

📄 Read: references/skin-manager-setup.md
  • Adding SfSkinManager references and assemblies
  • Applying themes to individual controls
  • Applying themes globally to entire applications
  • Understanding theme inheritance (window → child elements)
  • Basic implementation in XAML and C#
  • ApplyThemeAsDefaultStyle property usage
📄 阅读: references/skin-manager-setup.md
  • 添加SfSkinManager引用和程序集
  • 为单个控件应用主题
  • 为整个应用程序全局应用主题
  • 理解主题继承(窗口 → 子元素)
  • XAML和C#中的基础实现
  • ApplyThemeAsDefaultStyle属性的使用

Exploring Built-in Themes

探索内置主题

📄 Read: references/built-in-themes.md
  • Complete list of 17 available themes
  • Light/Dark theme variants
  • Theme categories: Windows 11, Fluent, Material 3, Material, Office 2019, High Contrast, System
  • Theme assembly and NuGet package references
  • Choosing the right theme for your application
  • Theme compatibility with Syncfusion and Framework controls
📄 阅读: references/built-in-themes.md
  • 17款可用主题的完整列表
  • 浅色/深色主题变体
  • 主题类别:Windows 11、Fluent、Material 3、Material、Office 2019、高对比度、系统
  • 主题程序集和NuGet包引用
  • 为应用程序选择合适的主题
  • 主题与Syncfusion和框架控件的兼容性

Creating and Customizing Themes

创建和自定义主题

📄 Read: references/theme-customization.md
  • After exporting custom theme from Theme Studio, follow the steps in this document
  • Customizing colors and fonts programmatically
  • Working with exported theme projects
  • Generating theme assemblies
  • Registering and integrating custom themes
  • Multi-framework SDK-style theme projects (.NET 4.6.2, .NET 8.0, .NET 9.0, .NET 10.0)
📄 阅读: references/theme-customization.md
  • 从Theme Studio导出自定义主题后,按照本文档中的步骤操作
  • 以编程方式自定义颜色和字体
  • 处理导出的主题项目
  • 生成主题程序集
  • 注册和集成自定义主题
  • 多框架SDK风格主题项目(.NET 4.6.2、.NET 8.0、.NET 9.0、.NET 10.0)

Advanced Theme Features

高级主题功能

📄 Read: references/theme-features.md
  • Fluent theme reveal animations (hover and pressed effects)
  • Configuring HoverEffectMode and PressedEffectMode
  • Acrylic background effects for windows
  • Keyboard focus visual indicators
  • ScrollBar modes (Native, Compact)
  • Touch support configuration
📄 阅读: references/theme-features.md
  • Fluent主题显示动画(悬停和按下效果)
  • 配置HoverEffectMode和PressedEffectMode
  • 窗口的亚克力背景效果
  • 键盘焦点视觉指示器
  • 滚动条模式(原生、紧凑)
  • 触摸支持配置

Quick Start Example

快速入门示例

Apply a Built-in Theme in XAML

在XAML中应用内置主题

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>
        <!-- Your controls here - theme automatically applied -->
    </Grid>
</Window>
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>
        <!-- Your controls here - theme automatically applied -->
    </Grid>
</Window>

Apply a Theme in C#

在C#中应用主题

csharp
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();
    }
}
csharp
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();
    }
}

Apply Theme Globally to Application

为应用程序全局应用主题

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

Common Patterns

常见模式

Pattern 1: Theme Switching at Runtime

模式1:运行时主题切换

Allow users to switch themes dynamically in your application:
csharp
// Example: Switch theme when user selects from dropdown
private void OnThemeSelectionChanged(string themeName)
{
    SfSkinManager.SetTheme(this, new Theme(themeName));
}
允许用户在应用程序中动态切换主题:
csharp
// Example: Switch theme when user selects from dropdown
private void OnThemeSelectionChanged(string themeName)
{
    SfSkinManager.SetTheme(this, new Theme(themeName));
}

Pattern 2: Combine Custom Theme with Built-in Theme

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

Register a custom theme derived from a built-in theme:
csharp
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}"));
注册一个基于内置主题的自定义主题:
csharp
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}"));

Pattern 3: Customize Theme Colors Programmatically

模式3:以编程方式自定义主题颜色

Modify specific theme colors at runtime:
csharp
// 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"));
在运行时修改特定主题颜色:
csharp
// 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"));

Theme Selection Guide

主题选择指南

Choose by Application Style:
  • Modern/Windows 11 Native: Windows11Light, Windows11Dark
  • Microsoft Fluent Design: FluentLight, FluentDark
  • Material Design: Material3Light, Material3Dark, MaterialLight, MaterialDark
  • Office-like: Office2019Colorful, Office2019Black, Office2019White, Office2019DarkGray
  • High Contrast/Accessibility: Office2019HighContrast, Office2019HighContrastWhite
  • Follow OS: SystemTheme
Light vs. Dark:
  • Use Light themes for bright environments or daytime use
  • Use Dark themes for low-light environments or as a user preference
  • Pair with SystemTheme to automatically match OS settings
按应用程序风格选择:
  • 现代/Windows 11原生风格: Windows11Light、Windows11Dark
  • Microsoft Fluent设计风格: FluentLight、FluentDark
  • Material设计风格: Material3Light、Material3Dark、MaterialLight、MaterialDark
  • 类Office风格: Office2019Colorful、Office2019Black、Office2019White、Office2019DarkGray
  • 高对比度/辅助功能: Office2019HighContrast、Office2019HighContrastWhite
  • 跟随系统: SystemTheme
浅色 vs 深色:
  • 浅色主题适用于明亮环境或白天使用
  • 深色主题适用于弱光环境或用户偏好
  • 搭配SystemTheme可自动匹配系统设置

Key Properties

核心属性

PropertyPurposeTypeDefault
SfSkinManager.Theme
Applied theme name (XAML attached property)stringNone
SfSkinManager.ApplicationTheme
Global theme for entire applicationTheme objectNone
HoverEffectMode
Visual effect on hover (Fluent theme)HoverEffect enumBackgroundAndBorder
PressedEffectMode
Visual effect on press (Fluent theme)PressedEffect enumReveal
ShowAcrylicBackground
Enable acrylic blur effect (Fluent theme)boolfalse
ApplyThemeAsDefaultStyle
Apply theme as default style resourceboolfalse
属性用途类型默认值
SfSkinManager.Theme
应用的主题名称(XAML附加属性)string
SfSkinManager.ApplicationTheme
整个应用程序的全局主题Theme对象
HoverEffectMode
悬停时的视觉效果(Fluent主题)HoverEffect枚举BackgroundAndBorder
PressedEffectMode
按下时的视觉效果(Fluent主题)PressedEffect枚举Reveal
ShowAcrylicBackground
启用亚克力模糊效果(Fluent主题)boolfalse
ApplyThemeAsDefaultStyle
将主题作为默认样式资源应用boolfalse

Related Skills

相关技能

  • Custom theme creation and export (Theme Studio guide)
  • Keyboard accessibility and focus indicators
  • Responsive design for themed applications
  • 自定义主题创建与导出(Theme Studio指南)
  • 键盘辅助功能与焦点指示器
  • 主题应用程序的响应式设计