# TangHotKey

**Repository Path**: tjfzeishuai/TangHotKey

## Basic Information

- **Project Name**: TangHotKey
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-07-14
- **Last Updated**: 2025-07-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TangHotKey

一个功能强大、易于使用的 .NET 全局热键管理库，支持热键配置持久化存储和可视化管理界面。

## ✨ 特性

- 🔥 **全局热键注册**: 支持系统级全局热键注册和管理
- 🎯 **灵活的修饰键组合**: 支持 Ctrl、Alt、Shift 等修饰键的任意组合
- 💾 **配置持久化**: 自动保存和加载热键配置，重启后配置依然有效
- 🎨 **可视化管理界面**: 提供友好的热键编辑和管理界面
- 📝 **热键描述**: 为每个热键添加自定义描述，便于管理
- 🔄 **实时预览**: 热键设置时提供实时预览功能
- 📤 **配置导入导出**: 支持配置文件的导入导出，便于备份和迁移
- 🛡️ **异常处理**: 完善的错误处理机制，确保程序稳定运行
- 📊 **使用统计**: 记录热键的创建时间和最后使用时间

## 🚀 快速开始

### 安装

1. 克隆项目到本地：
```bash
git clone https://gitee.com/tjfzeishuai/TangHotKey.git
cd TangHotKey
```

2. 构建项目：
```bash
dotnet build
```

3. 运行演示程序：
```bash
dotnet run --project TangHotKey.Demo
```

### 基本使用

#### 1. 引用库

```csharp
using TangHotKey;
```

#### 2. 初始化热键管理器

```csharp
// 在窗体中初始化
GlobalHotKey.Initialize(this);
```

#### 3. 注册热键

```csharp
// 创建热键组合
var hotKey = new HotKeyCombination(
    HotKeyManager.ModifierKeys.Control | HotKeyManager.ModifierKeys.Alt,
    Keys.A,
    "我的热键"
);

// 注册热键并指定回调函数
int hotKeyId = hotKey.Register(() =>
{
    MessageBox.Show("热键被触发！");
});
```

#### 4. 注销热键

```csharp
// 注销指定ID的热键
GlobalHotKey.Unregister(hotKeyId);

// 清理所有热键
GlobalHotKey.Cleanup();
```

## 🎮 演示程序功能

演示程序 (`TangHotKey.Demo`) 提供了完整的热键管理界面：

### 主要功能

- **添加新热键**: 通过可视化界面设置热键组合和描述
- **删除选中热键**: 删除不需要的热键配置
- **清除所有热键**: 一键清空所有热键配置
- **导出配置**: 将当前热键配置导出为 JSON 文件
- **导入配置**: 从 JSON 文件导入热键配置
- **实时状态显示**: 显示当前操作状态和热键列表

### 热键编辑器特性

- **修饰键选择**: 通过复选框选择 Ctrl、Alt、Shift
- **主键选择**: 下拉菜单选择主要按键
- **描述输入**: 为热键添加自定义描述
- **实时预览**: 显示当前设置的热键组合
- **预设快捷键**: 提供常用热键组合的快速设置
- **直接输入**: 支持通过键盘直接输入热键组合
- **字符串解析**: 支持解析 "Ctrl+A" 格式的热键字符串

## 📁 项目结构

```
TangHotKey/
├── TangHotKey/                 # 核心库
│   ├── GlobalHotKey.cs         # 全局热键管理器
│   ├── HotKeyCombination.cs    # 热键组合类
│   ├── HotKeyManager.cs        # 底层热键管理
│   ├── HotKeyConfig.cs         # 配置管理类
│   └── TangHotKey.csproj       # 项目文件
├── TangHotKey.Demo/            # 演示程序
│   ├── MainForm.cs             # 主窗体
│   ├── MainForm.Designer.cs    # 主窗体设计器
│   ├── HotKeyEditForm.cs       # 热键编辑窗体
│   ├── HotKeyEditForm.Designer.cs # 热键编辑窗体设计器
│   ├── Program.cs              # 程序入口
│   └── TangHotKey.Demo.csproj  # 演示项目文件
├── README.md                   # 项目说明
├── README.en.md               # 英文说明
├── .gitignore                 # Git忽略文件
└── TangHotKey.sln             # 解决方案文件
```

## 💾 配置文件

热键配置自动保存在用户应用数据目录：
```
%APPDATA%\TangHotKey\hotkeys.json
```

### 配置文件格式

```json
{
  "HotKeys": [
    {
      "Modifiers": "Control, Alt",
      "Key": "A",
      "Description": "我的热键",
      "IsEnabled": true,
      "CreatedTime": "2024-01-01T12:00:00",
      "LastUsedTime": "2024-01-01T12:00:00"
    }
  ],
  "AutoStartWithWindows": false,
  "ShowNotifications": true,
  "Version": "1.0.0",
  "LastSaved": "2024-01-01T12:00:00"
}
```

## 🔧 API 参考

### GlobalHotKey 类

| 方法 | 描述 |
|------|------|
| `Initialize(Form form)` | 初始化热键管理器 |
| `Unregister(int id)` | 注销指定ID的热键 |
| `GetRegisteredHotKeys()` | 获取已注册的热键列表 |
| `Cleanup()` | 清理所有热键资源 |

### HotKeyCombination 类

| 属性/方法 | 描述 |
|-----------|------|
| `Modifiers` | 修饰键组合 |
| `Key` | 主要按键 |
| `Description` | 热键描述 |
| `Register(Action callback)` | 注册热键并指定回调函数 |
| `ToString()` | 获取热键的字符串表示 |

### HotKeyConfig 类

| 方法 | 描述 |
|------|------|
| `LoadConfig()` | 加载配置文件 |
| `SaveConfig()` | 保存配置文件 |
| `AddHotKey(...)` | 添加热键配置 |
| `RemoveHotKey(...)` | 移除热键配置 |
| `ExportConfig(string path)` | 导出配置到文件 |
| `ImportConfig(string path)` | 从文件导入配置 |

## 🛠️ 系统要求

- .NET 9.0 或更高版本
- Windows 操作系统
- Visual Studio 2022 或更高版本（开发）

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🙏 致谢

- 感谢所有贡献者的支持
- 感谢 .NET 社区提供的优秀资源

## 📞 联系方式

如有问题或建议，请通过以下方式联系：

- 提交 [Issue](https://gitee.com/tjfzeishuai/TangHotKey/issues)
- 发送邮件至：tjfzeishuai@163.com

---

⭐ 如果这个项目对你有帮助，请给它一个星标！