Back to Details

syncfusion-winforms-theming

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Windows Forms Theming (SkinManager)

Windows Forms 主题设置（SkinManager）

The Syncfusion Windows Forms SkinManager provides support to apply consistent themes across all Syncfusion controls in an application. It enables uniform styling for entire applications, forms, or individual controls using predefined themes or custom Theme Studio-based themes.
Syncfusion Windows Forms SkinManager 支持为应用内所有 Syncfusion 控件应用统一的主题。你可以使用预设主题或基于 Theme Studio 的自定义主题，为整个应用、单个窗体或独立控件设置一致的样式。

When to Use This Skill

何时使用本指南

Use this skill when you need to:
  • Apply themes to Syncfusion WinForms controls (Office2007, Office2010, Office2013, Office2016, Office2019, Metro)
  • Set up theme assemblies and load them properly
  • Apply themes to entire applications, forms, or containers
  • Customize theme appearance using ThemeStyle or Style properties
  • Apply themes through designer or code-based approaches
  • Control whether themes override user customizations
当你需要完成以下操作时可参考本指南：
  • 为 Syncfusion WinForms 控件应用主题（Office2007、Office2010、Office2013、Office2016、Office2019、Metro）
  • 配置主题程序集并正确加载
  • 为整个应用、窗体或容器应用主题
  • 使用 ThemeStyle 或 Style 属性自定义主题外观
  • 通过设计器或代码方式应用主题
  • 控制主题是否覆盖用户自定义样式

Component Overview

组件概览

SkinManager is a component that manages theme application for Syncfusion Windows Forms controls. It supports:
  • Multiple predefined themes (Office2007, Office2010, Office2013, Office2016, Office2019, Metro, HighContrast)
  • Application-wide theme management
  • Form/container-level theme application
  • Individual control theme application
  • Advanced styling through ThemeStyle/Style properties
Key Assembly: 
Syncfusion.Shared.Base
Additional Assemblies: Some themes require separate assemblies (Office2016Theme, Office2019Theme, HighContrastTheme)
SkinManager 是负责为 Syncfusion Windows Forms 控件管理主题应用的组件，支持以下能力：
  • 多款预设主题（Office2007、Office2010、Office2013、Office2016、Office2019、Metro、HighContrast）
  • 应用全局主题管理
  • 窗体/容器层级的主题应用
  • 单个控件的主题应用
  • 通过 ThemeStyle/Style 属性实现高级样式定制
核心程序集： 
Syncfusion.Shared.Base
额外程序集： 部分主题需要单独引用对应程序集（Office2016Theme、Office2019Theme、HighContrastTheme）

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md
  • Assembly deployment and theme assembly requirements
  • Loading theme assemblies using LoadAssembly method
  • Adding SkinManager component through designer
  • Adding SkinManager component through code
  • Basic theme application to controls and forms
  • Applying themes to entire forms and containers
📄 阅读： references/getting-started.md
  • 程序集部署与主题程序集要求
  • 使用 LoadAssembly 方法加载主题程序集
  • 通过设计器添加 SkinManager 组件
  • 通过代码添加 SkinManager 组件
  • 为控件和窗体应用基础主题
  • 为整个窗体和容器应用主题

Theme Management

主题管理

📄 Read: references/theme-management.md
  • Complete list of available themes
  • VisualTheme property usage
  • SetVisualTheme method for programmatic theme setting
  • Application-wide theming using ApplicationVisualTheme
  • Individual control theming using ThemeName property
  • Assembly requirements for specific themes
  • Theme application patterns and best practices
📄 阅读： references/theme-management.md
  • 可用主题完整列表
  • VisualTheme 属性使用方法
  • 使用 SetVisualTheme 方法通过代码设置主题
  • 使用 ApplicationVisualTheme 配置应用全局主题
  • 使用 ThemeName 属性为单个控件设置主题
  • 特定主题的程序集要求
  • 主题应用模式与最佳实践

Advanced Customization

高级自定义

📄 Read: references/advanced-customization.md
  • ThemeStyle property for theme customization
  • Style property for Sf-prefixed controls
  • CanOverrideStyle property behavior
  • FontHelper customization for application-wide fonts
  • Custom styling examples and patterns
  • Overriding user customizations with themes
📄 阅读： references/advanced-customization.md
  • 用于主题自定义的 ThemeStyle 属性
  • 适用于 Sf 前缀控件的 Style 属性
  • CanOverrideStyle 属性的行为说明
  • 用于配置应用全局字体的 FontHelper 自定义
  • 自定义样式示例与模式
  • 用主题覆盖用户自定义样式

Quick Start Example

快速上手示例

Basic Theme Application (Code-Based)

基础主题应用（代码方式）

csharp
using Syncfusion.Windows.Forms;

namespace MyWinFormsApp
{
    public partial class Form1 : Form
    {
        public Form1()
        {
            InitializeComponent();
            
            // Create SkinManager instance
            SkinManager skinManager1 = new SkinManager(this.components);
            
            // Apply theme to entire form (all Syncfusion controls)
            skinManager1.Controls = this;
            skinManager1.VisualTheme = VisualTheme.Office2016Black;
        }
    }
}
csharp
using Syncfusion.Windows.Forms;

namespace MyWinFormsApp
{
    public partial class Form1 : Form
    {
        public Form1()
        {
            InitializeComponent();
            
            // Create SkinManager instance
            SkinManager skinManager1 = new SkinManager(this.components);
            
            // Apply theme to entire form (all Syncfusion controls)
            skinManager1.Controls = this;
            skinManager1.VisualTheme = VisualTheme.Office2016Black;
        }
    }
}

Application-Wide Theme (Program.cs)

应用全局主题（Program.cs）

csharp
using Syncfusion.Windows.Forms;
using Syncfusion.WinForms.Themes;

static class Program
{
    [STAThread]
    static void Main()
    {
        // Load theme assembly (for Office2019, Office2016, HighContrast)
        SkinManager.LoadAssembly(typeof(Office2019Theme).Assembly);
        
        // Set application-wide theme
        SkinManager.ApplicationVisualTheme = "Office2019Colorful";
        
        Application.EnableVisualStyles();
        Application.SetCompatibleTextRenderingDefault(false);
        Application.Run(new Form1());
    }
}
csharp
using Syncfusion.Windows.Forms;
using Syncfusion.WinForms.Themes;

static class Program
{
    [STAThread]
    static void Main()
    {
        // Load theme assembly (for Office2019, Office2016, HighContrast)
        SkinManager.LoadAssembly(typeof(Office2019Theme).Assembly);
        
        // Set application-wide theme
        SkinManager.ApplicationVisualTheme = "Office2019Colorful";
        
        Application.EnableVisualStyles();
        Application.SetCompatibleTextRenderingDefault(false);
        Application.Run(new Form1());
    }
}

Common Patterns

常用模式

Pattern 1: Theme Entire Form

模式1：为整个窗体设置主题

csharp
// Apply theme to all Syncfusion controls in a form
SkinManager skinManager1 = new SkinManager(this.components);
skinManager1.Controls = this; // 'this' refers to the form
skinManager1.VisualTheme = VisualTheme.Office2016White;
csharp
// Apply theme to all Syncfusion controls in a form
SkinManager skinManager1 = new SkinManager(this.components);
skinManager1.Controls = this; // 'this' refers to the form
skinManager1.VisualTheme = VisualTheme.Office2016White;

Pattern 2: Theme Individual Control

模式2：为单个控件设置主题

csharp
// Option 1: Using SkinManager
skinManager1.Controls = treeViewAdv1;
skinManager1.VisualTheme = VisualTheme.Office2016Colorful;

// Option 2: Using ThemeName property
this.treeViewAdv1.ThemeName = "Office2019Colorful";
csharp
// Option 1: Using SkinManager
skinManager1.Controls = treeViewAdv1;
skinManager1.VisualTheme = VisualTheme.Office2016Colorful;

// Option 2: Using ThemeName property
this.treeViewAdv1.ThemeName = "Office2019Colorful";

Pattern 3: Loading Required Theme Assemblies

模式3：加载所需的主题程序集

csharp
// Office2019 themes
SkinManager.LoadAssembly(typeof(Office2019Theme).Assembly);

// Office2016 themes (for SfDataGrid, SfButton, etc.)
SkinManager.LoadAssembly(typeof(Syncfusion.WinForms.Themes.Office2016Theme).Assembly);

// HighContrast themes
SkinManager.LoadAssembly(typeof(HighContrastTheme).Assembly);
csharp
// Office2019 themes
SkinManager.LoadAssembly(typeof(Office2019Theme).Assembly);

// Office2016 themes (for SfDataGrid, SfButton, etc.)
SkinManager.LoadAssembly(typeof(Syncfusion.WinForms.Themes.Office2016Theme).Assembly);

// HighContrast themes
SkinManager.LoadAssembly(typeof(HighContrastTheme).Assembly);

Pattern 4: Customize Theme Appearance

模式4：自定义主题外观

csharp
// For Theme Studio themes, customize using ThemeStyle
this.treeViewAdv1.ThemeName = "Office2019Colorful";
this.treeViewAdv1.ThemeStyle.BackColor = System.Drawing.Color.White;
this.treeViewAdv1.ThemeStyle.BorderColor = System.Drawing.Color.SteelBlue;
this.treeViewAdv1.ThemeStyle.TreeNodeAdvStyle.TextColor = System.Drawing.Color.Red;
csharp
// For Theme Studio themes, customize using ThemeStyle
this.treeViewAdv1.ThemeName = "Office2019Colorful";
this.treeViewAdv1.ThemeStyle.BackColor = System.Drawing.Color.White;
this.treeViewAdv1.ThemeStyle.BorderColor = System.Drawing.Color.SteelBlue;
this.treeViewAdv1.ThemeStyle.TreeNodeAdvStyle.TextColor = System.Drawing.Color.Red;

Key Properties and Methods

核心属性与方法

SkinManager Properties

SkinManager 属性

PropertyDescriptionType
Controls
Specifies the parent control/form for which theme is appliedControl
VisualTheme
Specifies the theme style to applyEnum (VisualTheme)
ApplicationVisualTheme
Sets theme for entire application (static property)String
属性说明类型
Controls
指定要应用主题的父控件/窗体Control
VisualTheme
指定要应用的主题样式枚举（VisualTheme）
ApplicationVisualTheme
为整个应用设置主题（静态属性）String

SkinManager Methods

SkinManager 方法

MethodDescriptionParameters
SetVisualTheme(Control, VisualTheme)
Applies theme to specified controlControl, VisualTheme enum
SetVisualTheme(Control, String)
Applies theme to specified controlControl, theme name string
LoadAssembly(Assembly)
Loads theme assembly before applying themeAssembly object
方法说明参数
SetVisualTheme(Control, VisualTheme)
为指定控件应用主题Control, VisualTheme 枚举
SetVisualTheme(Control, String)
为指定控件应用主题Control, 主题名称字符串
LoadAssembly(Assembly)
在应用主题前加载主题程序集Assembly 对象

Control-Level Properties

控件层级属性

PropertyDescriptionAvailable On
ThemeName
Theme name to apply to individual controlAll Syncfusion controls
ThemeStyle
Customize theme appearance propertiesNon-Sf controls
Style
Customize theme appearance propertiesSf-prefixed controls
CanOverrideStyle
Allow theme to override user customizationsTheme Studio compatible controls
属性说明适用范围
ThemeName
应用到单个控件的主题名称所有 Syncfusion 控件
ThemeStyle
自定义主题外观属性非 Sf 前缀控件
Style
自定义主题外观属性Sf 前缀控件
CanOverrideStyle
允许主题覆盖用户自定义样式兼容 Theme Studio 的控件

Available Themes

可用主题

Predefined Themes (Built-in)

预设主题（内置）

  • Office2007: Blue, Black, Silver, Managed
  • Office2010: Blue, Black, Silver, Managed
  • Office2013: White, Dark Gray, Black, Colorful
  • Metro
  • Office2007：Blue、Black、Silver、Managed
  • Office2010：Blue、Black、Silver、Managed
  • Office2013：White、Dark Gray、Black、Colorful
  • Metro

Separate Assembly Themes

需单独引用程序集的主题

  • Office2016: White, Dark Gray, Black, Colorful (requires 
    Syncfusion.Office2016Theme.WinForms.dll
    )
  • Office2019: Colorful (requires 
    Syncfusion.Office2019Theme.WinForms.dll
    )
  • HighContrast: Black (requires 
    Syncfusion.HighContrastTheme.WinForms.dll
    )
  • Office2016：White、Dark Gray、Black、Colorful（需引用 
    Syncfusion.Office2016Theme.WinForms.dll
    ）
  • Office2019：Colorful（需引用 
    Syncfusion.Office2019Theme.WinForms.dll
    ）
  • HighContrast：Black（需引用 
    Syncfusion.HighContrastTheme.WinForms.dll
    ）

Common Use Cases

常见使用场景

  1. Uniform Application Styling: Apply consistent theme across all forms and controls
  2. Modern UI Appearance: Use Office2016/2019 themes for contemporary look
  3. Dark Mode Support: Implement dark themes (Office2016Black, Office2016DarkGray)
  4. Accessibility Compliance: Use HighContrast themes for accessibility
  5. Dynamic Theme Switching: Change themes at runtime based on user preferences
  6. Per-Form Theming: Apply different themes to different forms in the same application
  1. 统一应用样式：为所有窗体和控件应用一致的主题
  2. 现代化UI外观：使用 Office2016/2019 主题实现现代观感
  3. 深色模式支持：实现深色主题（Office2016Black、Office2016DarkGray）
  4. 无障碍合规：使用高对比度主题满足无障碍要求
  5. 动态主题切换：运行时根据用户偏好更改主题
  6. 单窗体主题设置：同一应用内为不同窗体应用不同主题

Important Notes

重要注意事项

  • Assembly Loading: Always call 
    LoadAssembly()
    before applying themes that require separate assemblies
  • Application-Wide Theme: Set 
    ApplicationVisualTheme
    before main form initialization (in Program.cs)
  • Container Theming: Apply theme to form/container instead of individual controls for efficiency
  • Override Behavior: Themes respect 
    CanOverrideStyle
    property to control customization overrides
  • 程序集加载：应用需要单独程序集的主题前，务必先调用 
    LoadAssembly()
  • 应用全局主题：在主窗体初始化前（Program.cs 中）设置 
    ApplicationVisualTheme
  • 容器主题设置：优先为窗体/容器应用主题，而非逐个设置控件，提升效率
  • 覆盖行为：主题会遵循 
    CanOverrideStyle
    属性的设置来控制是否覆盖自定义样式

Troubleshooting

问题排查

Theme not applying:
  • Verify theme assembly is loaded using 
    LoadAssembly()
  • Check that 
    Controls
    property is set correctly
  • Ensure theme name spelling is exact (case-sensitive)
Custom theme not working:
  • Confirm custom theme assembly is referenced in project
  • Verify 
    LoadAssembly()
    is called before theme application
  • Check that theme name matches assembly name exactly
Appearance customization not taking effect:
  • Verify using Theme Studio-based themes (Office2019Colorful, HighContrastBlack)
  • Check 
    CanOverrideStyle
    is set to 
    false
    if you want to preserve customizations
  • Use 
    ThemeStyle
    for non-Sf controls, 
    Style
    for Sf-prefixed controls
主题未生效：
  • 确认已通过 
    LoadAssembly()
    加载了对应的主题程序集
  • 检查 
    Controls
    属性是否设置正确
  • 确保主题名称拼写完全正确（区分大小写）
自定义主题不生效：
  • 确认项目中已引用自定义主题程序集
  • 验证在应用主题前已调用 
    LoadAssembly()
  • 检查主题名称与程序集名称完全匹配
外观自定义未生效：
  • 确认使用的是基于 Theme Studio 的主题（Office2019Colorful、HighContrastBlack）
  • 如果要保留自定义样式，检查 
    CanOverrideStyle
    是否设置为 
    false
  • 非 Sf 前缀控件使用 
    ThemeStyle
    ，Sf 前缀控件使用 
    Style