# VirtualKeyAssistant

**Repository Path**: zhu-kanglong/VirtualKeyAssistant

## Basic Information

- **Project Name**: VirtualKeyAssistant
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-02-22
- **Last Updated**: 2026-06-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 虚拟按键助手 (Virtual Key Assistant)

虚拟按键助手是一个轻量级的 Windows 桌面工具，允许您通过全局快捷键快速呼出一个悬浮面板，并在面板上点击按钮来模拟键盘输入。

它非常适合以下场景：
*   **键盘故障**：当键盘上某些按键失灵时，可以用它作为临时替代方案。
*   **单手操作**：将常用的组合键（如 `Ctrl+C`, `Ctrl+V`）配置到面板上，只需鼠标点击即可完成操作。
*   **复杂快捷键**：将难以记忆或按压的复杂快捷键配置为一键触发。
*   **辅助输入**：在某些只能使用鼠标的场景下辅助输入特定按键。

## 主要功能

*   **全局快捷键呼出**：默认使用 `Ctrl+Space` (可配置) 快速显示或隐藏按键面板。
*   **自定义虚拟按键**：支持添加任意键盘按键或组合键（如 `F1`, `Ctrl+Alt+Delete` 等）。
*   **多种添加方式**：
    *   **一键录制**：直接按下键盘即可录入。
    *   **组合选择**：通过下拉菜单和复选框组合生成按键。
    *   **手动输入**：支持手动编辑按键名称。
*   **悬浮置顶**：面板始终置顶，方便在任何软件上层操作。
*   **托盘管理**：支持最小化到系统托盘，右键菜单提供便捷控制。

## 使用指南

### 1. 启动程序
*   **EXE 版本**：直接双击运行 `VirtualKeyAssistant.exe`。
*   **源码运行**：在项目根目录下运行 `python main.py`。

### 2. 呼出/隐藏面板
*   按下全局快捷键（默认 `Ctrl+Space`）即可切换面板的显示状态。
*   也可以双击系统托盘区的图标，或右键点击托盘图标选择“显示/隐藏”。

### 3. 模拟按键
*   在悬浮面板上，点击对应的按钮，即可模拟该按键的按下操作。

### 4. 设置配置
点击面板右上角的 **设置图标 (⚙)**，或右键点击托盘图标选择 **“设置”**，即可打开配置窗口。

*   **修改全局快捷键**：
    *   点击“点击录制”，然后按下您想设置的快捷键。
    *   或者直接在输入框中修改。
*   **管理按键列表**：
    *   **添加**：点击“添加”，在弹出的对话框中选择“点击录制”直接按下键盘，或者使用下方的组合选择器生成按键。
    *   **删除**：选中列表中的按键，点击“删除”。
    *   **清空**：点击“清空”移除所有按键。
*   **保存**：点击“保存”按钮，配置即时生效。

### 5. 退出程序
*   右键点击系统托盘图标，选择 **“退出”**。
*   注意：点击面板右上角的“X”只会隐藏面板，程序仍在后台运行。

## 开发构建

如果您想自己修改代码或重新打包：

1.  **安装依赖**：
    ```bash
    uv pip install -r requirements.txt
    ```

2.  **运行代码**：
    ```bash
    python main.py
    ```

3.  **打包为 EXE**：
    确保已安装 `pyinstaller`，然后运行：
    ```bash
    pyinstaller --onefile --noconsole --name VirtualKeyAssistant main.py
    ```
    打包后的文件位于 `dist/` 目录下。

## 配置文件
程序首次运行会自动在同级目录下生成 `config.json` 文件，用于存储您的配置信息。

```json
{
    "hotkey": "ctrl+space",
    "keys": ["F1", "F2", "ctrl+c", "ctrl+v"]
}
```

## 许可证 (License)

本项目采用 **CC BY-NC 4.0** 协议。

*   **个人使用**：免费。您可以自由下载、使用、修改和分发本软件，但必须保留原作者署名。
*   **商业使用**：收费。如果您希望将本软件用于商业目的（包括但不限于公司内部使用、捆绑销售、提供付费服务等），必须获得作者的商业授权。

如需商业授权，请联系：[Your Contact Information]