# KeyOverlay Ultra (Python 版)

这是一个基于 Python 编写的轻量级、高度可定制的按键显示器（Key Overlay）。它可以实时监测你的全局键盘输入，并在屏幕上显示按键次数。特别支持“二次元人物联动”模式，让你的桌面更具个性。

## ✨ 主要功能

- **全局监听**：无论是在打游戏还是敲代码，程序都能准确记录按键。
- **双样式切换**：支持“简洁列表模式”和“高亮键盘模式”。
- **人物联动**：支持 `idle`（空闲）和 `pressed`（按下）两张图片切换，实现角色随你一起按键的效果。
- **数据持久化**：自动保存按键计数、窗口位置、透明度设置，下次打开无缝衔接。
- **高度自由**：
  - **左键拖动**：自由调整窗口位置。
  - **右键菜单**：快速添加/删除监控按键、设置透明度。
  - **置顶显示**：永远保持在最顶层，不被其他窗口遮挡。

## 🛠️ 前期准备

在运行程序之前，请确保已安装以下 Python 库：

```bash
pip install pynput pillow
```

## 🚀 快速开始

1. 将 `key_overlay.py` 放在你的项目文件夹中。
2. (可选) 在同目录下放入两张 PNG 图片：
   - `idle.png`: 人物平时的状态。
   - `pressed.png`: 人物按键时的状态。
3. 运行程序：
   ```bash
   python key_overlay.py
   ```

## 🖱️ 交互操作指南

- **移动窗口**：直接用 **鼠标左键** 按住窗口任何地方并拖动。
- **功能菜单**：在窗口上点击 **鼠标右键**：
  - **切换样式**：在“列表”和“方块键盘”布局间切换。
  - **添加按键**：输入想要监控的键名（如 `a`, `s`, `d`, `space`, `shift`, `ctrl_l`）。
  - **删除按键**：输入键名从监控列表中移除。
  - **设置透明度**：输入 0.1 - 1.0 之间的数值。
  - **重置计数**：清空所有按键的历史统计。
  - **退出并保存**：安全关闭并保存当前所有配置。

## 📂 配置文件说明

程序运行后会自动生成 `key_config.json`，其中存储了：
- `monitored_keys`: 你正在监控的按键列表。
- `counts`: 每个按键的累计点击次数。
- `position`: 窗口在屏幕上的坐标。
- `alpha`: 窗口透明度。
- `ui_mode`: 当前使用的 UI 样式。

## ⚠️ 注意事项

- **特殊按键名**：添加非字符键时，请使用标准名称（如 `space`, `shift`, `enter`, `tab`, `backspace`, `caps_lock`）。
- **图片建议**：为了美观，建议使用透明背景的 `.png` 图片，程序会自动将其缩放至 150x150 像素。
- **权限问题**：在 macOS 上运行可能需要授予终端“辅助功能”权限以允许监听键盘。

---
*祝你敲得开心！*