syncfusion-winui-getting-started

实施 Syncfusion WinUI 设置和许可

何时使用此技能

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

• 用户需要安装 Syncfusion WinUI 组件
• 需要注册或验证许可证
• 必须检查系统要求
• 出现安装错误
• 需要进行配置（主题、本地化、RTL）
• 排查设置或许可问题
• 从试用许可证升级到已购买的许可证
• 在 CI/CD 环境中进行设置

设置概览

Syncfusion WinUI 组件需要完成三个核心设置阶段：

1. 先决条件与系统检查 - 验证操作系统、.NET 版本和兼容性
2. 许可证注册 - 注册并验证 Syncfusion 许可证
3. 程序包安装与配置 - 通过 NuGet 安装并配置功能

每个阶段都基于前一阶段进行，跳过任何步骤都可能导致后续问题。

---

文档与导航指南

系统要求与先决条件

📄 阅读： references/system-requirements.md

• WinUI 和 Windows 操作系统兼容性
• .NET 版本要求
• Visual Studio 先决条件
• 硬件和浏览器要求
• 目标框架兼容性

许可概览

📄 阅读： references/licensing-overview.md

• 许可证类型和选项
• 获取许可证密钥的途径
• 许可证注册流程
• 社区许可证资格
• 试用许可证与已购买许可证的区别

安装和程序包设置

📄 阅读： references/installation-setup.md

• NuGet 程序包安装步骤
• 命名空间注册
• 在线安装程序配置
• 离线安装程序下载和设置
• 验证是否成功安装

许可证验证和激活

📄 阅读： references/license-validation.md

• 在代码中注册许可证密钥
• 离线许可证验证
• 互联网连接要求
• 常见许可证错误及解决方案
• 从试用许可证升级到已购买许可证

主题

📄 阅读： references/theming.md

• 可用主题（浅色、深色）
• 设置和切换主题
• 检测系统主题

本地化和语言支持

📄 阅读： references/localization.md

• 支持的语言和区域性代码
• 设置应用语言（WinUI 专用方法）
• 使用 .resw 文件进行本地化（基于资源的方法）
• 不使用 .resw 文件进行本地化（ILocalizationProvider 和编程方式）
• 自定义资源文件和编辑默认字符串
• RTL（从右到左）语言支持
• 动态切换语言

无障碍功能和紧凑尺寸

📄 阅读： references/configuration-basics.md

• 屏幕阅读器支持
• 自动化属性和 ARIA
• 键盘导航
• 高对比度模式
• 紧凑尺寸选项

安装故障排查

📄 阅读： references/troubleshooting-installation.md

• 安装错误解决方案
• NuGet 还原和程序包问题
• 许可证验证故障排查
• 配置问题修复
• 获取支持和调试

升级和补丁

📄 阅读： references/upgrade-and-patches.md

• 从试用许可证升级到已购买的许可证
• 应用服务包和补丁
• 版本升级注意事项
• 维护现有安装
• 回滚流程

---

快速入门示例

// 1. Register License (in App.xaml.cs or MainWindow.xaml.cs)
using Syncfusion.Licensing;

public partial class App : Application
{
    public App()
    {
        // Register your license key before using any Syncfusion component
        SyncfusionLicenseProvider.RegisterLicense("YOUR_LICENSE_KEY");
        this.InitializeComponent();
    }
}

// 2. Add namespaces in XAML
xmlns:syncfusion="using:Syncfusion.UI.Xaml.Controls"
xmlns:editors="using:Syncfusion.UI.Xaml.Editors"

// 3. Use components
<editors:SfComboBox x:Name="comboBox"
                    Width="250"
                    PlaceholderText="Select an item"
                    ItemsSource="{Binding Items}"
                    DisplayMemberPath="Name"
                    TextMemberPath="Name" />

---

常见设置模式

模式 1：新建项目设置

1. 在 Visual Studio 中创建 WinUI 项目
2. 安装 Syncfusion NuGet 程序包：Install-Package Syncfusion.WinUI
3. 在 App.xaml.cs 中注册许可证
4. 将命名空间添加到 XAML
5. 开始使用组件

模式 2：从试用版升级到正式版

1. 在代码中验证当前试用许可证
2. 获取购买的许可证密钥
3. 使用新密钥更新许可证注册信息
4. 测试所有组件是否均可在没有试用限制的情况下正常工作
5. 部署到正式环境

模式 3：CI/CD 环境设置

1. 在构建环境中设置离线许可证验证
2. 在环境变量或安全保管库中配置许可证
3. 在构建过程中引用许可证
4. 确保所有依赖项均已预缓存
5. 在隔离环境中测试构建

模式 4：功能配置

1. 安装基础 Syncfusion 包
2. 配置所需主题（FluentLight、FluentDark、MaterialLight 等）
3. 添加本地化文件（.resw 方案），或实现 ILocalizationProvider（编程方案）
4. 如果面向阿拉伯语／希伯来语用户，请启用 RTL
5. 启用辅助功能以满足合规要求

模式 5：本地化设置

选项 A - .resw 文件方案：

1. 从 Syncfusion GitHub 下载默认资源文件
2. 在项目中创建 Resources/{language}/ 文件夹
3. 为目标语言复制 .resw 文件
4. 在代码中设置 ApplicationLanguages.PrimaryLanguageOverride
5. 使用目标语言进行测试

选项 B - Provider 方案：

1. 创建实现 ILocalizationProvider 接口的类
2. 实现 GetLocalizedString(LocalizationInfo) 方法
3. 在 InitializeComponent() 之前设置 LocalizationProvider.Provider
4. 为特定资源键返回自定义字符串
5. 使用 ResourceAssemblyName 进行特定程序集的本地化

---

关键要求检查清单

安装 Syncfusion WinUI 组件之前，请确认：

• 操作系统： Windows 10 version 1809+ 或 Windows 11
• .NET 版本： .NET 5 或更高版本（通常为 .NET 6+）
• Visual Studio： VS 2019 v16.9+ 或 VS 2022
• WinUI 3： 已安装最新稳定版
• 许可证： 已获取有效许可证密钥或已启用试用版
• NuGet： 已更新至最新版本
• 管理员权限： 某些安装场景需要此权限
• 互联网： 可用于在线还原包（或已缓存离线包）

---

快速决策树

用户需要……

• 安装 Syncfusion？ → 安装和包设置
• 注册许可证？ → 许可证概览，然后查看许可证验证
• 修复安装错误？ → 安装故障排除
• 检查系统是否兼容？ → 系统要求
• 设置主题？ → 主题设置
• 配置语言／RTL？ → 本地化和语言支持
• 使用 .resw 文件进行本地化？ → 本地化和语言支持（.resw Files 部分）
• 以编程方式进行本地化？ → 本地化和语言支持（Provider Method 部分）
• 设置辅助功能？ → 辅助功能和紧凑尺寸
• 从试用版升级到付费版？ → 升级和补丁
• 在 CI/CD 中验证许可证？ → 许可证验证