1. 概述

HandyControls 是一个基于 WPF (Windows Presentation Foundation) 的开源 UI 控件库，旨在为开发者提供丰富、美观且易用的自定义控件，帮助快速构建现代化的 Windows 桌面应用程序。该控件库遵循 MVVM 设计模式，提供了一致的设计语言和丰富的交互效果，极大简化了 WPF 应用的界面开发流程。

核心特点

• 提供超过 70 种自定义控件，覆盖常见 UI 场景
• 支持明暗两种主题及自定义主题
• 内置丰富的动画和过渡效果
• 完全开源，基于 MIT 许可协议
• 良好的兼容性，支持 .NET Framework 4.0+、.NET Core 3.0+ 和 .NET 5+
• 完善的文档和示例代码

适用场景

• 企业级桌面应用程序
• 数据可视化工具
• 管理系统界面
• 需要现代化 UI 的 WPF 应用

2. 安装与配置

2.1 安装方式

NuGet 安装（推荐）

通过 NuGet 包管理器安装 HandyControls：

# .NET Framework 版本
Install-Package HandyControls

# .NET Core/.NET 5+ 版本
Install-Package HandyControls.NetCore

或使用 .NET CLI：

# .NET Framework 版本
dotnet add package HandyControls

# .NET Core/.NET 5+ 版本
dotnet add package HandyControls.NetCore

手动安装

1. 从 GitHub 仓库 下载源码
2. 编译生成 HandyControls.dll
3. 在项目中添加对该 DLL 的引用

2.2 环境要求

• Windows 7 及以上操作系统
• .NET Framework 4.0+ 或 .NET Core 3.0+/.NET 5+
• Visual Studio 2017 及以上版本（推荐）

2.3 基本配置

在 XAML 中引入 HandyControls 命名空间：

<Window 
    xmlns:hc="https://handyorg.github.io/handycontrol"
    ...>
</Window>

为应用程序配置全局样式（在 App.xaml 中）：

<Application.Resources>
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>
            <!-- 基础样式 -->
            <hc:ThemeResources />
            <!-- 控件样式 -->
            <hc:Theme />
        </ResourceDictionary.MergedDictionaries>
    </ResourceDictionary>
</Application.Resources>

3. 核心控件分类与使用

3.1 基础控件

按钮控件 (Button)

HandyControls 提供了多种样式的按钮：

<!-- 主要按钮 -->
<hc:Button Content="主要按钮" Style="{StaticResource ButtonPrimary}" />

<!-- 成功按钮 -->
<hc:Button Content="成功按钮" Style="{StaticResource ButtonSuccess}" />

<!-- 警告按钮 -->
<hc:Button Content="警告按钮" Style="{StaticResource ButtonWarning}" />

<!-- 危险按钮 -->
<hc:Button Content="危险按钮" Style="{StaticResource ButtonDanger}" />

<!-- 图标按钮 -->
<hc:Button Style="{StaticResource ButtonIcon}">
    <hc:SymbolIcon Symbol="Search" />
</hc:Button>

文本输入控件

包括文本框、密码框等增强型输入控件：

<!-- 带清除按钮的文本框 -->
<hc:TextBox hc:InfoElement.Placeholder="请输入内容" hc:TextBoxHelper.ClearButton="True" />

<!-- 带图标的文本框 -->
<hc:TextBox hc:InfoElement.Placeholder="搜索...">
    <hc:TextBox.Header>
        <hc:SymbolIcon Symbol="Search" />
    </hc:TextBox.Header>
</hc:TextBox>

<!-- 密码框 -->
<hc:PasswordBox hc:InfoElement.Placeholder="请输入密码" />

3.2 布局控件

网格布局 (FlexGrid)

灵活的网格布局控件，支持自动换行：

<hc:FlexGrid Columns="3" Margin="10" Spacing="10">
    <hc:Button Content="Item 1" />
    <hc:Button Content="Item 2" />
    <hc:Button Content="Item 3" />
    <hc:Button Content="Item 4" />
    <hc:Button Content="Item 5" />
</hc:FlexGrid>

卡片布局 (Card)

用于展示包含标题、内容和操作区的卡片：

<hc:Card Margin="10" Title="卡片标题" Description="这是卡片描述信息">
    <hc:Card.Content>
        <TextBlock Text="卡片内容区域" />
    </hc:Card.Content>
    <hc:Card.Action>
        <hc:Button Content="操作按钮" />
    </hc:Card.Action>
</hc:Card>

3.3 数据展示控件

数据表格 (DataGrid)

增强型数据表格，支持排序、筛选和分页：

<hc:DataGrid ItemsSource="{Binding DataItems}" 
             CanUserSortColumns="True"
             CanUserFilterColumns="True"
             AutoGenerateColumns="False">
    <hc:DataGrid.Columns>
        <hc:DataGridTextColumn Header="ID" Binding="{Binding Id}" />
        <hc:DataGridTextColumn Header="名称" Binding="{Binding Name}" />
        <hc:DataGridDateTimeColumn Header="日期" Binding="{Binding Date}" />
        <hc:DataGridTemplateColumn Header="操作">
            <hc:DataGridTemplateColumn.CellTemplate>
                <DataTemplate>
                    <hc:Button Content="编辑" />
                </DataTemplate>
            </hc:DataGridTemplateColumn.CellTemplate>
        </hc:DataGridTemplateColumn>
    </hc:DataGrid.Columns>
</hc:DataGrid>

树形视图 (TreeView)

带复选框和动画效果的树形控件：

<hc:TreeView ItemsSource="{Binding Categories}">
    <hc:TreeView.ItemTemplate>
        <HierarchicalDataTemplate ItemsSource="{Binding Children}">
            <hc:CheckComboBoxItem Content="{Binding Name}" IsChecked="{Binding IsSelected}" />
        </HierarchicalDataTemplate>
    </hc:TreeView.ItemTemplate>
</hc:TreeView>

3.4 交互控件

对话框 (Dialog)

简化的对话框调用方式：

<!-- XAML 中定义 -->
<hc:Dialog x:Name="CustomDialog" Title="自定义对话框">
    <StackPanel>
        <TextBlock Text="这是一个自定义对话框" Margin="5" />
        <hc:Button Content="确定" Click="OnConfirmClick" />
    </StackPanel>
</hc:Dialog>

// 代码中调用
private void ShowDialogButton_Click(object sender, RoutedEventArgs e)
{
    // 显示消息对话框
    Dialog.ShowMessage("这是一条消息", "消息标题");

    // 显示确认对话框
    var result = Dialog.ShowConfirm("确定要执行此操作吗？", "确认");
    if (result)
    {
        // 执行操作
    }

    // 显示自定义对话框
    CustomDialog.Show();
}

通知提示 (Notification)

轻量级通知提示控件：

// 显示成功通知
Notification.ShowSuccess("操作成功", "提示");

// 显示错误通知
Notification.ShowError("操作失败", "错误");

// 显示信息通知
Notification.Show("这是一条信息", "通知");

3.5 特色控件

时钟控件 (Clock)

模拟时钟和数字时钟：

<!-- 模拟时钟 -->
<hc:Clock Width="200" Height="200" />

<!-- 数字时钟 -->
<hc:DigitalClock Format="HH:mm:ss" />

步骤指示器 (StepBar)

用于多步骤流程展示：

<hc:StepBar CurrentIndex="1" Margin="10">
    <hc:StepBarItem Content="步骤 1" Description="基本信息" />
    <hc:StepBarItem Content="步骤 2" Description="详细设置" />
    <hc:StepBarItem Content="步骤 3" Description="完成" />
</hc:StepBar>

4. 主题与样式

4.1 主题切换

HandyControls 支持明暗两种内置主题，可通过代码动态切换：

// 切换到深色主题
ThemeManager.Current.ApplicationTheme = ApplicationTheme.Dark;

// 切换到浅色主题
ThemeManager.Current.ApplicationTheme = ApplicationTheme.Light;

4.2 自定义主题

通过修改资源字典自定义主题颜色：

<ResourceDictionary xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
                    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <!-- 重写主题颜色 -->
    <SolidColorBrush x:Key="PrimaryBrush" Color="#FF0078D7" />
    <SolidColorBrush x:Key="SuccessBrush" Color="#FF00B42A" />
    <SolidColorBrush x:Key="WarningBrush" Color="#FFFF7D00" />
    <SolidColorBrush x:Key="DangerBrush" Color="#FFE50000" />
</ResourceDictionary>

在 App.xaml 中引用自定义主题：

<Application.Resources>
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>
            <hc:ThemeResources />
            <hc:Theme />
            <!-- 引入自定义主题 -->
            <ResourceDictionary Source="CustomTheme.xaml" />
        </ResourceDictionary.MergedDictionaries>
    </ResourceDictionary>
</Application.Resources>

5. 高级功能

5.1 本地化支持

HandyControls 支持多语言，包括中文、英文、日文等，可通过以下方式设置：

// 设置为中文
LocalizationManager.Instance.SetCulture(new CultureInfo("zh-CN"));

// 设置为英文
LocalizationManager.Instance.SetCulture(new CultureInfo("en-US"));

5.2 动画效果

内置丰富的动画效果，可通过附加属性启用：

<!-- 为按钮添加悬停动画 -->
<hc:Button Content="带动画的按钮" hc:AnimationHelper.MouseHoverAnimation="True" />

<!-- 为面板添加加载动画 -->
<hc:Panel hc:LoadingHelper.IsLoading="True" hc:LoadingHelper.LoadingStyle="Circle" />

5.3 MVVM 支持

HandyControls 提供了一系列辅助类简化 MVVM 开发：

// 继承 ViewModelBase 实现 INotifyPropertyChanged
public class MainViewModel : ViewModelBase
{
    private string _message;
    public string Message
    {
        get => _message;
        set => SetProperty(ref _message, value);
    }

    // 命令示例
    public DelegateCommand SubmitCommand { get; }

    public MainViewModel()
    {
        SubmitCommand = new DelegateCommand(Submit, CanSubmit);
    }

    private void Submit()
    {
        // 执行提交逻辑
    }

    private bool CanSubmit()
    {
        // 命令可执行条件
        return !string.IsNullOrEmpty(Message);
    }
}

6. 使用示例

以下是一个简单的 HandyControls 应用示例，展示了多个控件的组合使用：

<Window x:Class="HandyControlsDemo.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:hc="https://handyorg.github.io/handycontrol"
        Title="HandyControls 示例" Height="450" Width="800">
    <hc:ScrollViewer>
        <StackPanel Margin="20" Spacing="15">
            <hc:TitleBar Title="HandyControls 演示" />

            <hc:Card Title="输入区域">
                <StackPanel Spacing="10" Margin="10">
                    <hc:TextBox hc:InfoElement.Placeholder="请输入姓名" hc:InfoElement.Title="姓名" />
                    <hc:PasswordBox hc:InfoElement.Placeholder="请输入密码" hc:InfoElement.Title="密码" />
                    <hc:ComboBox hc:InfoElement.Title="选择类别">
                        <hc:ComboBoxItem Content="类别 1" />
                        <hc:ComboBoxItem Content="类别 2" />
                        <hc:ComboBoxItem Content="类别 3" />
                    </hc:ComboBox>
                </StackPanel>
            </hc:Card>

            <hc:Card Title="操作区域">
                <StackPanel Orientation="Horizontal" Spacing="10" Margin="10">
                    <hc:Button Content="保存" Style="{StaticResource ButtonPrimary}" />
                    <hc:Button Content="取消" Style="{StaticResource ButtonDefault}" />
                    <hc:Button Content="帮助" Style="{StaticResource ButtonInfo}" />
                </StackPanel>
            </hc:Card>

            <hc:StepBar CurrentIndex="0">
                <hc:StepBarItem Content="基本信息" />
                <hc:StepBarItem Content="详细设置" />
                <hc:StepBarItem Content="完成" />
            </hc:StepBar>

            <hc:TagContainer>
                <hc:Tag Content="标签 1" />
                <hc:Tag Content="标签 2" />
                <hc:Tag Content="标签 3" />
            </hc:TagContainer>
        </StackPanel>
    </hc:ScrollViewer>
</Window>

7. 常见问题与解决方案

7.1 控件样式不生效

• 确保已在 App.xaml 中正确引用 ThemeResources 和 Theme
• 检查项目是否引用了正确版本的 HandyControls
• 清理并重新生成项目

7.2 主题切换无效

• 确保主题切换代码在 UI 线程执行
• 检查是否有自定义样式覆盖了主题资源

7.3 在 .NET Core 中使用问题

• 确保安装的是 HandyControls.NetCore 包
• 检查项目是否目标框架为 .NET Core 3.0+ 或 .NET 5+

7.4 本地化不生效

• 确保已添加对应语言的资源文件
• 检查文化名称是否正确（如 "zh-CN" 而非 "zh"）

8. 相关资源

• GitHub 仓库：https://github.com/HandyOrg/HandyControls
• 官方文档：https://handyorg.github.io/handycontrol/
• 示例项目：仓库中包含的 Demo 项目
• 社区支持：GitHub Issues 和 Discussions

9. 版本历史

• v3.0：支持 .NET 5+，重构部分控件
• v2.5：新增 10+ 控件，优化性能
• v2.0：支持 .NET Core 3.0，完善主题系统
• v1.0：初始版本，包含基础控件集

10. 总结

HandyControls 为 WPF 开发者提供了一套完整的 UI 解决方案，通过丰富的控件、灵活的主题和简化的 API，显著提高了桌面应用的开发效率。其开源特性和活跃的社区支持使其成为构建现代化 WPF 应用的理想选择。无论是小型工具还是大型企业应用，HandyControls 都能满足各种 UI 需求，帮助开发者专注于业务逻辑而非界面实现。