syncfusion-wpf-getting-started

实现 Syncfusion 入门

在 Windows Presentation Foundation 应用程序中安装、配置和开始使用 Syncfusion® WPF 组件的完整指南。本技能涵盖从系统要求到添加第一个控件的所有内容。

何时使用本技能

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

• 安装 Syncfusion WPF 组件（Web 安装程序、离线安装程序或 NuGet 包）
• 检查系统要求，确保满足 Syncfusion WPF 开发需求
• 向 WPF 项目添加 Syncfusion 控件（设计器、XAML 或代码隐藏）
• 使用 Package Manager、CLI 或 Console 配置 NuGet 包
• 将 Syncfusion 升级到较新版本，或从试用版迁移到许可版本
• 设置本地化，通过 .resx 文件支持多种语言
• 配置从右向左（RTL）支持，用于阿拉伯语、希伯来语、乌尔都语等
• 使用 Syncfusion 控件实现 MVVM 模式（命令、数据绑定、NotificationObject）
• 排查安装或设置问题
• 了解 Syncfusion 程序集之间的依赖关系
• 配置与 .NET Framework 或 .NET Core/.NET 8+ 的兼容性

本技能是所有 Syncfusion WPF 设置和配置任务的起点。

概述

Syncfusion® Essential® Studio for WPF 提供一套全面的 UI 控件，用于构建现代 Windows 桌面应用程序。入门步骤包括：

1. 验证系统要求（Windows OS、Visual Studio、.NET Framework/.NET）
2. 选择安装方式（Web 安装程序、离线安装程序或 NuGet）
3. 安装或下载组件
4. 向 WPF 项目添加控件
5. 配置引用、主题和许可

设置流程会因所用方式而异：

• 完整安装程序（包含所有控件、项目模板和文档）
• NuGet 包（轻量级，按控件逐个安装）
• 试用版（30 天评估）或许可版本

文档与导航指南

系统要求

📄 阅读： references/system-requirements.md

需要确认以下内容时，请查看此参考文档：

• 支持的操作系统（Windows XP 至 Windows 11）
• 硬件要求（处理器、RAM、磁盘空间）
• 开发环境（Visual Studio 2015/2017/2019/2022）
• .NET Framework 版本（4.0、4.6.2）和 .NET 版本（8.0、9.0、10.0）
• 与现有开发环境的兼容性

安装方式

📄 阅读： references/installation-methods.md

所有安装方式的综合指南：

• Web 安装程序：从 Syncfusion.com 下载并安装（安装期间需要联网）
• 离线安装程序：下载完整包以供离线安装
• 试用版与许可版：两者的区别，以及如何分别下载
• 帐户设置和许可证密钥生成
• 安装向导操作说明
• 试用版安装所需的解锁密钥

向项目添加控件

📄 阅读： references/adding-controls.md

了解向 WPF 应用程序添加 Syncfusion 控件的所有方法：

• 使用设计器：从 Visual Studio Toolbox 拖放控件
• 使用 XAML：手动添加命名空间和控件声明
• 使用代码隐藏：通过 C# 或 VB.NET 以编程方式创建控件
• 使用项目模板：使用 Syncfusion 模板创建新项目
• 程序集引用要求
• 命名空间声明

NuGet 包管理

📄 阅读： references/nuget-package-management.md

使用 Syncfusion NuGet 包的完整指南：

• 包管理器 UI：用于包管理的可视化界面
• Dotnet CLI：使用 dotnet add package 通过命令行安装
• 包管理器控制台：基于 PowerShell 的包命令
• 将 nuget.org 配置为包源
• 安装指定版本
• 更新包
• 在没有完整安装程序的情况下使用（仅 NuGet 工作流）

升级和迁移

📄 阅读： references/upgrading.md

将 Syncfusion 升级到较新版本或迁移许可证：

• 从 Syncfusion Control Panel 升级到最新版本
• 下载并安装较新版本
• Volume 版本与 Service Pack 版本
• 从试用版升级到授权版本（安装程序或 NuGet）
• 注册许可证密钥
• 版本兼容性注意事项

配置

📄 阅读： references/configuration.md

框架兼容性和核心配置：

• .NET Framework 兼容性：使用不同的框架版本
• .NET Core/.NET 8+ 兼容性：支持现代 .NET
• 控件依赖项：了解程序集之间的关系（6 个常见示例）
• 从右向左（RTL）：为国际化应用配置 RTL 支持

本地化

📄 阅读： references/localization.md

为 Syncfusion WPF 控件设置多语言支持：

• 更改应用程序区域性：设置 CurrentUICulture
• 创建 .resx 文件：为翻译设置资源文件
• 本地化分步指南：包含示例的完整指南
• 常见区域性代码：支持的语言和地区
• 编辑默认字符串：自定义英文文本
• 故障排除：解决本地化问题

模式和实践

📄 阅读： references/patterns-and-practices.md

Syncfusion WPF 开发的 MVVM 模式和最佳实践：

• MVVM 入门：基本的 MVVM 结构和设置
• MVVM 命令：使用内置命令（TabControlExt 等）
• CommandParameter 用法：向命令处理程序传递数据
• 命令目标：指定命令目标元素
• DataContext 和数据绑定：双向绑定和 ItemsSource
• NotificationObject：INotifyPropertyChanged 实现
• 完整 MVVM 示例：使用 SfDataGrid 管理员工
• 主题管理：应用主题和 SfSkinManager
• 性能最佳实践：优化技巧

故障排除

📄 阅读： references/troubleshooting.md

常见安装和设置问题的解决方案：

• 安装错误及其解决方法
• 许可证注册问题
• 程序集引用问题（“Could not load file or assembly”）
• NuGet 包错误
• 版本冲突
• Visual Studio 集成问题

快速入门示例

以下是使用 Syncfusion WPF 控件快速入门的方法：

选项 1：使用 NuGet（推荐快速入门）

# In Package Manager Console
Install-Package Syncfusion.SfGrid.WPF

<Window x:Class="WpfApp.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:syncfusion="http://schemas.syncfusion.com/wpf"
        Title="Syncfusion WPF Demo" Height="450" Width="800">
    <Grid>
        <syncfusion:SfDataGrid x:Name="dataGrid" 
                               AutoGenerateColumns="True"
                               ItemsSource="{Binding Employees}"/>
    </Grid>
</Window>

选项 2：使用完整安装程序

1. 从 Syncfusion.com 下载并安装
2. 打开 Visual Studio → 创建新的 WPF 项目
3. 右键单击项目 → 管理 NuGet 包 → 浏览“Syncfusion.SfGrid.WPF”
4. 或从工具箱拖动控件（安装后会显示 Syncfusion 控件）

许可证注册（试用版/NuGet 必需）

// In App.xaml.cs or before InitializeComponent()
Syncfusion.Licensing.SyncfusionLicenseProvider.RegisterLicense("YOUR_LICENSE_KEY");

注意：如果使用试用版安装程序或 NuGet 包，则必须注册许可证。请从 Syncfusion License & Downloads 页面生成许可证密钥。

常见模式

模式 1：通过 Web 安装程序安装

适用场景：网络连接可靠，且希望获取包含所有功能的最新版本。

1. 访问 Syncfusion.com 下载页面
2. 选择 WPF 平台
3. 下载 Web 安装程序
4. 运行安装程序（安装期间需要联网）
5. 按照向导选择组件
6. 启动 Visual Studio 并开始开发

模式 2：通过 NuGet 安装（无需安装程序）

适用场景：希望轻量安装、按控件安装，或在 CI/CD 环境中使用。

# Install specific controls as needed
Install-Package Syncfusion.SfGrid.WPF
Install-Package Syncfusion.SfChart.WPF
Install-Package Syncfusion.SfBusyIndicator.WPF

优点：

• 无需完整安装程序
• 只安装所需控件
• 便于按项目管理版本
• 非常适合在 CI/CD 管道中使用

注意：需要在应用程序中注册许可证密钥。

模式 3：使用 Syncfusion 模板创建新项目

适用场景：使用 Syncfusion 组件启动新的 WPF 应用程序。

1. 通过完整安装程序安装 Syncfusion WPF
2. 在 Visual Studio 中依次选择“文件”→“新建项目”
3. 搜索“Syncfusion WPF Application”
4. 选择模板 → 配置项目
5. 在“项目配置向导”中选择控件、主题和语言
6. 项目创建完成，其中包含引用、XAML 和许可证设置

模式 4：通过设计器添加控件

适用场景：可视化开发、快速原型设计。

1. 确认已安装 Syncfusion（完整安装程序）
2. 在 Visual Studio 中打开 WPF 项目
3. 在设计器视图中打开 MainWindow.xaml
4. 打开工具箱（视图 → 工具箱）
5. 搜索控件（例如，“SfDataGrid”）
6. 将控件拖放到设计器中
7. Visual Studio 会自动添加引用和命名空间

模式 5：从试用版升级到授权版

适用场景：试用期即将结束，或已购买许可证。

如果使用安装程序：

1. 从 许可证和下载 下载授权版安装程序
2. 运行安装程序（无需卸载试用版）
3. 授权版将替换试用版

如果使用 NuGet 包：

1. 从 许可证和下载 生成许可证密钥
2. 在代码中替换试用版许可证密钥：

// Replace trial key with licensed key
Syncfusion.Licensing.SyncfusionLicenseProvider.RegisterLicense("YOUR_LICENSED_KEY");

安装工作流决策树

使用此决策树选择安装方式：

Do you need all Syncfusion WPF controls?
├─ YES → Do you have reliable internet?
│   ├─ YES → Use Web Installer
│   └─ NO → Use Offline Installer
│
└─ NO → Do you need only a few specific controls?
    └─ YES → Use NuGet Packages
        ├─ Package Manager UI (visual approach)
        ├─ Package Manager Console (PowerShell commands)
        └─ Dotnet CLI (command-line for .NET Core/.NET 8+)

特殊情况：

• CI/CD 环境：使用 NuGet 包并自动注册许可证
• 企业部署：使用离线安装程序以确保安装一致
• 快速原型设计：使用 Web 安装程序，或通过 NuGet 安装特定控件
• 学习/评估：使用试用版（Web 或离线安装程序）

核心概念

程序集引用

Syncfusion 控件分布在多个程序集中。常见程序集包括：

• Syncfusion.SfGrid.WPF.dll - 数据网格控件
• Syncfusion.SfChart.WPF.dll - 图表控件
• Syncfusion.SfShared.WPF.dll - 共享功能
• Syncfusion.SfInput.WPF.dll - 输入控件
• Syncfusion.Tools.WPF.dll - 工具控件（Ribbon 等）

每个控件都可能依赖共享程序集。NuGet 会自动处理这些依赖项；手动添加引用则需要了解依赖关系。

命名空间声明

XAML 的标准命名空间声明：

xmlns:syncfusion="http://schemas.syncfusion.com/wpf"

对于代码隐藏，请使用特定命名空间：

using Syncfusion.UI.Xaml.Grid;        // For SfDataGrid
using Syncfusion.UI.Xaml.Charts;      // For SfChart
using Syncfusion.Windows.Controls.Input; // For input controls

许可证密钥管理

需要许可证密钥的情况：

• 使用试用版安装程序
• 使用来自 nuget.org 的 NuGet 包

无需许可证密钥的情况：

• 使用授权版安装程序，并使用安装目录中的程序集引用

注册方式：

// In App.xaml.cs constructor, before InitializeComponent()
public App()
{
    Syncfusion.Licensing.SyncfusionLicenseProvider.RegisterLicense("YOUR_LICENSE_KEY");
    InitializeComponent();
}

主题配置

Syncfusion 提供多种主题。要应用主题：

<Application.Resources>
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>
            <ResourceDictionary Source="/Syncfusion.Themes.MaterialLight.WPF;component/MSControl/SfDataGrid.xaml"/>
        </ResourceDictionary.MergedDictionaries>
    </ResourceDictionary>
</Application.Resources>

有关完整的主题设置，请参阅配置参考。

常见用例

用例 1：新开发者评估 Syncfusion

目标：以最少的设置试用 Syncfusion WPF 控件。

方法：

1. 查看系统要求
2. 下载试用版 Web 安装程序
3. 使用默认选项安装
4. 使用 Syncfusion WPF Application 模板创建项目
5. 从工具箱中探索控件

用例 2：将 Syncfusion 添加到现有项目

目标：将特定的 Syncfusion 控件添加到现有 WPF 应用程序。

方法：

1. 通过 NuGet安装控件：

   Install-Package Syncfusion.SfGrid.WPF
   

2. 在 App.xaml.cs 中注册许可证密钥
3. 使用 XAML添加控件

用例 3：企业部署

目标：在多台开发者计算机上部署 Syncfusion，无需依赖互联网。

方法：

1. 下载脱机安装程序
2. 在内部分发安装程序包
3. 在每台开发者计算机上安装
4. 提供许可证密钥以进行注册

用例 4：升级现有项目

目标：将项目从较旧的 Syncfusion 版本更新到最新版本。

方法：

1. 查看 升级指南
2. 从帐户下载页下载最新版本
3. 更新 NuGet 包或安装新版本
4. 测试是否存在破坏性变更
5. 如有需要，更新许可证密钥

用例 5：本地化应用程序

目标：在使用 Syncfusion 控件的 WPF 应用程序中支持多种语言。

方法：

1. 设置本地化资源
2. 为目标区域性创建 .resx 文件
3. 在应用程序启动时设置区域性
4. Syncfusion 控件会自动使用本地化字符串

后续步骤

完成设置后：

1. 设置本地化（如果正在构建国际化应用）：

   • 查看 references/localization.md，获取完整的 .resx 设置指南

2. 学习使用 Syncfusion 控件的 MVVM 模式：

   • 查看 references/patterns-and-practices.md，了解命令、数据绑定和最佳实践

3. 探索特定组件的技能：

   • 图表：请参阅 implementing-syncfusion-wpf-components → Charts
   • 数据网格：请参阅 implementing-syncfusion-wpf-components → Data Grids
   • 编辑器：请参阅 implementing-syncfusion-wpf-components → Editors

4. 配置框架兼容性：

   • 查看 references/configuration.md，了解 .NET Framework 和 .NET Core/.NET 的设置

相关资源

• 官方文档：Syncfusion WPF Documentation
• 升级指南：Breaking Changes and Updates
• 许可：License Key Overview
• 组件库：如需实现特定组件，请使用 implementing-syncfusion-wpf-components 技能