# 键盘快捷键说明

本文档描述了 Haoyun Music Player 支持的键盘快捷键。

## 🎵 播放控制快捷键

| 功能 | macOS | Windows/Linux | 说明 |
|------|-------|---------------|------|
| **播放/暂停** | `Space` | `Space` | 空格键控制播放状态 |
| **上一曲** | `⌘ + [` | `Ctrl + [` | 切换到上一首歌曲（类似浏览器后退） |
| **下一曲** | `⌘ + ]` | `Ctrl + ]` | 切换到下一首歌曲（类似浏览器前进） |

### 播放/暂停行为说明
- **当播放列表为空时**：自动从当前音乐库加载所有歌曲并开始播放
- **当播放列表不为空时**：在当前播放状态和暂停状态之间切换

### 为什么使用方括号而不是箭头键？
- ✅ **避免系统冲突**：macOS 中 `Cmd+←/→` 被系统用于文本编辑（光标移动）
- ✅ **更高的可靠性**：方括号键在 Wails v3 Alpha 版本中支持更稳定
- ✅ **符合习惯**：许多应用（如浏览器标签页切换）使用 `[` 和 `]` 进行导航

## 🔧 其他快捷键

| 功能 | 快捷键 | 说明 |
|------|--------|------|
| **浏览歌曲** | `Cmd/Ctrl + F` | 打开浏览歌曲窗口 |
| **刷新音乐库** | `Cmd/Ctrl + R` | 重新扫描当前音乐库 |
| **下载** | `Cmd/Ctrl + D` | 打开下载管理 |
| **设置** | `Cmd/Ctrl + S` | 打开设置界面 |

## ⌨️ 使用注意事项

1. **焦点要求**：快捷键仅在应用窗口获得焦点时生效
2. **输入框例外**：当焦点在文本输入框中时，空格键会输入字符而非触发播放/暂停
3. **跨平台兼容**：
   - macOS 使用 `Command (⌘)` 键作为主要修饰键
   - Windows/Linux 使用 `Ctrl` 键作为主要修饰键
4. **全局快捷键**：当前实现的是应用内快捷键，非系统级全局快捷键

## 🎹 系统媒体键支持

本项目已通过 CGO 实现了**系统级媒体键**支持（即使在其他应用中也能控制播放器）：

| 功能 | 按键 | 平台支持 |
|------|------|----------|
| **播放/暂停** | 媒体播放/暂停键 | ✅ macOS & Windows |
| **上一曲** | 媒体上一曲键 | ✅ macOS & Windows |
| **下一曲** | 媒体下一曲键 | ✅ macOS & Windows |

**注意**：系统媒体键通过底层 CGO 实现，不依赖 Wails 的 `SetAccelerator()`，因此不受框架限制影响。

## 🚀 未来计划

- [x] 支持系统媒体键（Play/Pause, Next, Previous）- 已通过 CGO 实现
- [ ] 添加全局快捷键配置选项
- [ ] 支持自定义快捷键绑定

## 💡 技术实现

基于 Wails v3 的 MenuItem Accelerator 机制实现：
- 使用 `SetAccelerator()` 方法绑定快捷键
- 采用 Electron 风格的快捷键语法（如 "CmdOrCtrl+["）
- 自动适配不同操作系统的修饰键
- 系统媒体键通过 CGO 调用原生 API 实现（Carbon/Cocoa for macOS, Win32 for Windows）

---

**提示**：推荐使用系统媒体键获得最佳体验，或在应用内使用方括号快捷键避免与系统快捷键冲突。