syncfusion-winforms-common

实现 Syncfusion Windows Forms 组件

在桌面应用程序中实现 Syncfusion® Essential Studio® Windows Forms（WinForms）控件的综合指南。本技能涵盖从初始设置和安装到本地化和 .NET 兼容性的所有内容。

何时使用本技能

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

• 向 Windows Forms 应用程序添加 Syncfusion WinForms 控件
• 注册和管理 WinForms 应用程序的许可证密钥
• 通过安装程序或 NuGet 安装或升级 Syncfusion WinForms
• 为使用 Syncfusion WinForms 控件的项目设置 .NET Core / .NET 5-9
• 为 Syncfusion WinForms 控件启用 High DPI 支持
• 针对不同区域设置本地化 Syncfusion WinForms 控件
• 排查安装、许可或运行时错误

库概览

Syncfusion® Essential Studio® for Windows Forms 提供一套全面的 UI 控件，用于构建丰富的 Windows 桌面应用程序，包括网格、图表、日程安排、编辑器、导航、布局和输入控件。所有控件均专为 WinForms 应用程序设计，并支持 .NET Framework 4.6.2+ 和 .NET 6.0–9.0。

---

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 通过设计器添加控件（从工具箱拖放）
• 通过代码添加控件（C# / VB）
• 使用项目模板和项模板
• 控件所需的程序集引用
• 控件依赖项查询（每个控件对应的程序集和 NuGet 包）

本地化

📄 阅读： references/localization.md

• 使用 ILocalizationProvider 接口
• 使用 Satellite Assemblies 实现多语言支持
• 使用 .resx 文件进行本地化
• 在运行时更改应用程序区域设置
• 编辑默认区域设置字符串

High DPI 支持

📄 阅读： references/high-dpi-support.md

• DPI 感知概览（DPI 感知与非 DPI 感知应用）
• DPI 兼容性测试矩阵
• 通过 app.manifest 启用 DPI 感知
• 设置 AutoScaleDimensions 和 AutoScaleMode
• 为 Grid 控件启用 DpiAware 属性
• 通过 ImageListAdv 按 DPI 缩放自动切换图像

系统要求

📄 阅读： references/system-requirements.md

• 支持的 Windows 操作系统版本
• 硬件要求（处理器、RAM、磁盘）
• 支持的 Visual Studio 版本
• 支持的 .NET Framework 和 .NET 版本

.NET 兼容性

📄 阅读： references/dotnet-compatibility.md

• 使用 .NET Core / .NET 5-9 创建 WinForms 应用
• 在 .NET Core 项目中添加 Syncfusion 控件（程序集 / NuGet）
• .NET Framework 和 .NET Core 版本兼容性矩阵
• Syncfusion 各版本对 .NET 的支持情况

升级

📄 阅读： references/upgrading.md

• 通过控制面板 / 网站安装程序升级
• 通过 Visual Studio 扩展升级
• 通过包管理器 UI 升级 NuGet 包
• 通过包管理器控制台升级 NuGet 包
• 通过 .NET CLI 升级 NuGet 包
• 从试用版升级到许可版

安装

📄 阅读： references/installation.md

• 下载离线安装程序（试用版和许可版）
• 使用 UI 向导安装（分步说明）
• 静默安装/卸载或通过命令行安装/卸载
• 通过包管理器 UI 安装 NuGet 包
• 通过 .NET CLI 安装 NuGet 包
• 通过包管理器控制台安装 NuGet 包
• 常见安装错误及解决方案

---

快速入门

1. 通过 NuGet 安装

# Package Manager Console
Install-Package Syncfusion.Shared.Base

# .NET CLI
dotnet add package Syncfusion.Shared.Base

2. 注册许可证密钥

在初始化任何 Syncfusion 控件之前注册许可证：

// Program.cs — in static void Main(), before Application.Run()
static void Main()
{
    string licenseKey = ConfigurationManager.AppSettings["SyncfusionLicenseKey"];
    
    if (string.IsNullOrEmpty(licenseKey))
    {
        MessageBox.Show("Syncfusion license key not configured!", "Configuration Error");
        return;
    }
    
    SyncfusionLicenseProvider.RegisterLicense(licenseKey);

    Application.EnableVisualStyles();
    Application.SetCompatibleTextRenderingDefault(false);
    Application.Run(new Form1());
}

3. 通过代码添加控件

using Syncfusion.Windows.Forms.Tools;

// Create and configure the control
TextBoxExt textBox = new TextBoxExt();
textBox.Location = new System.Drawing.Point(100, 100);
textBox.Size = new System.Drawing.Size(200, 25);

// Add to form
this.Controls.Add(textBox);

---

常见模式

启用 High DPI

在 app.manifest 中：

<application xmlns="urn:schemas-microsoft-com:asm.v3">
  <windowsSettings>
    <dpiAware xmlns="http://schemas.microsoft.com/SMI/2005/WindowsSettings">true</dpiAware>
  </windowsSettings>
</application>

在代码中（针对 Grid 控件）：

gridControl1.DpiAware = true;

在运行时本地化控件

// Set culture before InitializeComponent()
Thread.CurrentThread.CurrentCulture = new System.Globalization.CultureInfo("de-DE");
Thread.CurrentThread.CurrentUICulture = new System.Globalization.CultureInfo("de-DE");

---

主要程序集

程序集	涵盖的控件
Syncfusion.Shared.Base	ButtonAdv、大多数共享控件
Syncfusion.Tools.Windows	ComboBoxAdv、DockingManager、TabControlAdv，以及大多数 Tools 控件
Syncfusion.Grid.Windows	GridControl、GridGroupingControl
Syncfusion.Chart.Windows	Chart 控件
Syncfusion.SfDataGrid.WinForms	SfDataGrid

如需查找各控件的依赖项，请阅读 references/getting-started.md。

---

常见用例

• 业务表单： 使用 Syncfusion WinForms 工具添加输入控件、编辑器和验证功能
• 数据密集型界面： 使用 GridControl 或 SfDataGrid，并支持高 DPI
• 多语言应用： 使用 .resx 文件或 ILocalizationProvider 实现本地化
• CI/CD 管道： 使用 LicenseKeyValidator 自动验证许可证密钥