syncfusion-winforms-theming

Windows Forms 主题设置（SkinManager）

Syncfusion Windows Forms SkinManager 支持为应用程序中的所有 Syncfusion 控件应用统一主题。它可以使用预定义主题或基于 Theme Studio 的自定义主题，为整个应用程序、窗体或单个控件设置统一样式。

何时使用此技能

在以下情况下使用此技能：

• 为 Syncfusion WinForms 控件应用主题（Office2007、Office2010、Office2013、Office2016、Office2019、Metro）
• 设置主题程序集并正确加载
• 为整个应用程序、窗体或容器应用主题
• 使用 ThemeStyle 或 Style 属性自定义主题外观
• 通过设计器或基于代码的方式应用主题
• 控制主题是否覆盖用户自定义设置

组件概览

SkinManager 是用于管理 Syncfusion Windows Forms 控件主题应用的组件。它支持：

• 多种预定义主题（Office2007、Office2010、Office2013、Office2016、Office2019、Metro、HighContrast）
• 应用程序级主题管理
• 窗体／容器级主题应用
• 单个控件的主题应用
• 通过 ThemeStyle／Style 属性进行高级样式设置

主要程序集： Syncfusion.Shared.Base

其他程序集： 某些主题需要单独的程序集（Office2016Theme、Office2019Theme、HighContrastTheme）

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 程序集部署和主题程序集要求
• 使用 LoadAssembly 方法加载主题程序集
• 通过设计器添加 SkinManager 组件
• 通过代码添加 SkinManager 组件
• 为控件和窗体应用基本主题
• 为整个窗体和容器应用主题

主题管理

📄 阅读： references/theme-management.md

• 可用主题的完整列表
• VisualTheme 属性的用法
• 用于以编程方式设置主题的 SetVisualTheme 方法
• 使用 ApplicationVisualTheme 设置应用程序级主题
• 使用 ThemeName 属性为单个控件设置主题
• 特定主题的程序集要求
• 主题应用模式和最佳实践

高级自定义

📄 阅读： references/advanced-customization.md

• 用于自定义主题的 ThemeStyle 属性
• 适用于 Sf 前缀控件的 Style 属性
• CanOverrideStyle 属性的行为
• 使用 FontHelper 自定义应用程序级字体
• 自定义样式示例和模式
• 使用主题覆盖用户自定义设置

快速入门示例

基本主题应用（基于代码）

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

应用程序级主题（Program.cs）

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

常见模式

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

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

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

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

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

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

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

模式 4：自定义主题外观

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

主要属性和方法

SkinManager 属性

属性	说明	类型
Controls	指定要应用主题的父控件／窗体	Control
VisualTheme	指定要应用的主题样式	枚举（VisualTheme）
ApplicationVisualTheme	为整个应用程序设置主题（静态属性）	String

SkinManager 方法

方法	说明	参数
SetVisualTheme(Control, VisualTheme)	为指定控件应用主题	Control、VisualTheme 枚举
SetVisualTheme(Control, String)	为指定控件应用主题	Control、主题名称字符串
LoadAssembly(Assembly)	应用主题前加载主题程序集	Assembly 对象

控件级属性

属性	说明	适用对象
ThemeName	应用于单个控件的主题名称	所有 Syncfusion 控件
ThemeStyle	自定义主题外观属性	非 Sf 控件
Style	自定义主题外观属性	带 Sf 前缀的控件
CanOverrideStyle	允许主题覆盖用户自定义设置	兼容 Theme Studio 的控件

可用主题

预定义主题（内置）

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

独立程序集主题

• Office2016：White、Dark Gray、Black、Colorful（需要 Syncfusion.Office2016Theme.WinForms.dll）
• Office2019：Colorful（需要 Syncfusion.Office2019Theme.WinForms.dll）
• HighContrast：Black（需要 Syncfusion.HighContrastTheme.WinForms.dll）

常见用例

1. 统一应用程序样式：在所有窗体和控件中应用一致的主题
2. 现代 UI 外观：使用 Office2016/2019 主题，呈现现代风格
3. 深色模式支持：使用深色主题（Office2016Black、Office2016DarkGray）
4. 无障碍合规：使用 HighContrast 主题以满足无障碍要求
5. 动态切换主题：根据用户偏好在运行时更改主题
6. 按窗体设置主题：在同一应用程序的不同窗体中应用不同主题

重要说明

• 程序集加载：应用需要独立程序集的主题前，始终先调用 LoadAssembly()
• 应用程序级主题：在主窗体初始化之前（在 Program.cs 中）设置 ApplicationVisualTheme
• 容器主题：为提高效率，应将主题应用于窗体/容器，而非单个控件
• 覆盖行为：主题会遵循 CanOverrideStyle 属性来控制对自定义设置的覆盖

故障排除

主题未生效：

• 确认已使用 LoadAssembly() 加载主题程序集
• 检查 Controls 属性是否设置正确
• 确保主题名称拼写完全正确（区分大小写）

自定义主题无法使用：

• 确认项目中已引用自定义主题程序集
• 确认在应用主题前调用了 LoadAssembly()
• 检查主题名称是否与程序集名称完全一致

外观自定义未生效：

• 确认使用的是基于 Theme Studio 的主题（Office2019Colorful、HighContrastBlack）
• 如果要保留自定义设置，请检查 CanOverrideStyle 是否设为 false
• 非 Sf 控件使用 ThemeStyle，带 Sf 前缀的控件使用 Style