keyboard-codes 0.3.0

# keyboard-codes


[![Crates.io](https://img.shields.io/crates/v/keyboard-codes.svg)](https://crates.io/crates/keyboard-codes)
[![Documentation](https://docs.rs/keyboard-codes/badge.svg)](https://docs.rs/keyboard-codes)
[![License](https://img.shields.io/crates/l/keyboard-codes.svg)](https://github.com/ymc-github/keyboard-codes/blob/main/LICENSE)
[![Build Status](https://github.com/ymc-github/keyboard-codes/actions/workflows/ci.yml/badge.svg)](https://github.com/ymc-github/keyboard-codes/actions)

一个全面的跨平台 Rust 库，用于键盘键码映射和转换。支持 Windows、Linux 和 macOS，提供键名与平台特定编码之间的双向转换。

## 特性


- **跨平台支持**: 为 Windows、Linux 和 macOS 提供全面的键码映射
- **完整的键定义**: 标准键、修饰键、功能键、媒体键等
- **双向转换**: 在键名和平台特定编码之间进行转换
- **灵活解析**: 支持别名、不区分大小写匹配和多种快捷键格式
- **自定义键映射**: 支持具有平台特定编码的自定义键和宏
- **快捷键解析**: 高级解析带修饰键组合的键盘快捷键
- **零依赖** (核心功能)
- **Serde 支持**: 可选的序列化/反序列化
- **PHF 支持**: 可选完美哈希函数，提供更快的查找速度

## 安装


在 `Cargo.toml` 中添加：

```toml
[dependencies]
keyboard-codes = "0.2.0"
```

### 可选特性


- `serde`: 为所有键类型启用序列化/反序列化支持
- `phf`: 使用完美哈希函数加速字符串查找

```toml
[dependencies]
keyboard-codes = { version = "0.2.0", features = ["serde", "phf"] }
```

## 快速开始


```rust
use keyboard_codes::{Key, Modifier, Platform, KeyCodeMapper};

// 从字符串解析按键
let enter_key: Key = "Enter".parse().unwrap();
let shift_mod: Modifier = "Shift".parse().unwrap();

// 转换为平台特定编码
let windows_code = enter_key.to_code(Platform::Windows);
let linux_code = enter_key.to_code(Platform::Linux);

// 从编码解析
let key_from_code = Key::from_code(0x0D, Platform::Windows).unwrap();

// 获取当前平台
let current_platform = keyboard_codes::current_platform();
```

## 使用示例


### 基本按键操作


```rust
use keyboard_codes::{Key, Modifier, Platform, KeyCodeMapper};

// 字符串解析
assert_eq!("Escape".parse::<Key>().unwrap(), Key::Escape);
assert_eq!("Shift".parse::<Modifier>().unwrap(), Modifier::Shift);

// 编码转换
assert_eq!(Key::Enter.to_code(Platform::Windows), 0x0D);
assert_eq!(Key::Enter.to_code(Platform::Linux), 28);
assert_eq!(Key::Enter.to_code(Platform::MacOS), 36);

// 反向查找
assert_eq!(Key::from_code(0x1B, Platform::Windows), Some(Key::Escape));
assert_eq!(Modifier::from_code(42, Platform::Linux), Some(Modifier::LeftShift));
```

### 高级快捷键解析


```rust
use keyboard_codes::{
    parse_shortcut_with_aliases, 
    parse_shortcut_flexible, 
    parse_shortcut_sequence,
    parse_input,
    Shortcut
};

// 使用别名支持解析快捷键
let shortcut = parse_shortcut_with_aliases("ctrl+shift+a").unwrap();
assert_eq!(shortcut.modifiers, vec![Modifier::Control, Modifier::Shift]);
assert_eq!(shortcut.key, Key::A);

// 灵活分隔符支持 (+, -, 空格)
let shortcut = parse_shortcut_flexible("ctrl-shift a").unwrap();

// 解析快捷键序列
let shortcuts = parse_shortcut_sequence("ctrl+a, cmd+q, shift+enter").unwrap();

// 自动检测单键或快捷键
let single_key = parse_input("a").unwrap(); // 单键
let shortcut = parse_input("ctrl+a").unwrap(); // 快捷键

// 修饰键和键的别名支持
let shortcut = parse_shortcut_with_aliases("cmd+esc").unwrap(); // Meta+Escape
```

### 自定义键映射


```rust
use keyboard_codes::{CustomKey, CustomKeyMap, Platform};

let mut custom_map = CustomKeyMap::new();

// 创建自定义宏键
let mut macro_key = CustomKey::new("MyMacro");
macro_key.add_platform_code(Platform::Windows, 0x100)
         .add_platform_code(Platform::Linux, 200);

custom_map.add_key(macro_key).unwrap();

// 使用自定义键
if let Some(key) = custom_map.parse_by_name("MyMacro") {
    let code = key.code(Platform::Windows).unwrap();
    println!("自定义键编码: {}", code);
}

// 通过编码查找
if let Some(key) = custom_map.parse_by_code(200, Platform::Linux) {
    println!("找到自定义键: {}", key.name());
}
```

### 平台检测


```rust
use keyboard_codes::{current_platform, Key, KeyCodeMapper};

let platform = current_platform();
let key = Key::A;
let code = key.to_code(platform);

println!("按键 {} 在 {} 平台上的编码是 {}", key, platform, code);
```

## 支持的键类型


### 标准按键

- **功能键**: Escape、Enter、Tab、Backspace、Space、Insert、Delete 等
- **导航键**: 方向键、Home、End、PageUp、PageDown
- **字母键**: A 到 Z
- **数字键**: 0-9 (主键盘和小键盘)
- **功能键**: F1 到 F24
- **特殊键**: CapsLock、NumLock、ScrollLock、Pause、Apps、Sleep 等

### 修饰键

- **基本修饰键**: Alt、Control、Shift、Meta
- **侧边特定修饰键**: LeftAlt、RightAlt、LeftControl、RightControl、LeftShift、RightShift、LeftMeta、RightMeta

### 媒体键

- **媒体控制**: Play/Pause、Stop、Next、Previous
- **音量控制**: VolumeUp、VolumeDown、VolumeMute
- **浏览器控制**: Back、Forward、Refresh、Home

## 别名支持


库提供广泛的别名支持，方便解析：

### 修饰键别名

- `ctrl`, `ctl` → `Control`
- `shft` → `Shift`
- `altgr`, `opt`, `option` → `Alt`
- `win`, `windows`, `cmd`, `command`, `super` → `Meta`
- `lctrl`, `lctl` → `LeftControl`
- `rshift`, `rshft` → `RightShift`
- 以及更多...

### 键别名

- `esc` → `Escape`
- `return` → `Enter`
- `back`, `bs` → `Backspace`
- `del` → `Delete`
- `ins` → `Insert`
- `pgup` → `PageUp`
- `pgdn`, `pagedown` → `PageDown`
- `left` → `ArrowLeft`
- `right` → `ArrowRight`
- `up` → `ArrowUp`
- `down` → `ArrowDown`
- `0`-`9` → `D0`-`D9`

## 平台支持


| 平台 | 键码范围 | 说明 |
|------|----------|------|
| Windows | 0x00 - 0xFF | 虚拟键码 |
| Linux | 0x00 - 0x2FF | 输入事件码 |
| macOS | 0x00 - 0x7F | 键码 |

## 错误处理


库通过 `KeyParseError` 枚举提供全面的错误处理：

```rust
use keyboard_codes::KeyParseError;

match "UnknownKey".parse::<Key>() {
    Ok(key) => println!("解析的按键: {}", key),
    Err(KeyParseError::UnknownKey(name)) => println!("未知按键: {}", name),
    Err(KeyParseError::UnknownModifier(modifier)) => println!("未知修饰键: {}", modifier),
    Err(KeyParseError::InvalidShortcutFormat(msg)) => println!("无效的快捷键格式: {}", msg),
    Err(e) => println!("其他错误: {}", e),
}
```

## 工具函数


```rust
use keyboard_codes::{utils, Platform};

// 验证键码有效性
assert!(utils::is_valid_key_code(0x41, Platform::Windows));
assert!(!utils::is_valid_key_code(0x1000, Platform::Windows));

// 规范化键码
let normalized = utils::normalize_key_code(0x141, Platform::Windows); // 返回 0x41

// 验证键名有效性
assert!(utils::is_valid_key_name("Enter"));
assert!(!utils::is_valid_key_name("123"));
```

## API 概览


### 主要类型

- `Key`: 键盘按键枚举 (150+ 按键)
- `Modifier`: 修饰键枚举 (12 种变体)
- `Platform`: 平台类型枚举 (Windows、Linux、macOS)
- `CustomKey`: 自定义按键定义
- `CustomKeyMap`: 自定义按键映射管理器
- `Shortcut`: 解析后的键盘快捷键（包含修饰键）

### 主要特性

- `KeyCodeMapper`: 键码映射特性，支持双向转换
- `FromStr`: 键和修饰键的字符串解析支持
- `Display`: 字符串表示支持

### 主要模块

- `mapping::standard`: 标准键码映射
- `mapping::custom`: 自定义键映射功能
- `parser`: 带别名支持的高级输入解析
- `types`: 核心类型定义
- `utils`: 工具函数和辅助功能

## 特性标志


- **default**: 无额外特性
- **serde**: 为所有类型启用 `Serialize` 和 `Deserialize` 实现
- **phf**: 使用完美哈希函数加速字符串到按键的解析


## 示例目录结构

```
├── examples/
│   ├── basic_usage.rs          # 基础用法示例
│   ├── game_input_system.rs    # 游戏输入系统
│   ├── gui_shortcuts.rs        # GUI 应用快捷键
│   ├── macro_system.rs         # 自动化宏系统
│   ├── config_management.rs    # 跨平台配置管理
│   ├── validation_tool.rs      # 测试验证工具
│   └── advanced_parsing.rs     # 高级解析功能
```

## 贡献


欢迎贡献！请随时提交 Pull Request、开启 Issue 或建议新功能。

## 许可证


本项目采用以下任一许可证：

- Apache 许可证 2.0 版本 ([LICENSE-APACHE](LICENSE-APACHE) 或 http://www.apache.org/licenses/LICENSE-2.0)
- MIT 许可证 ([LICENSE-MIT](LICENSE-MIT) 或 http://opensource.org/licenses/MIT)

按您的选择。

## 致谢


- 键码映射基于平台文档并跨多个来源交叉参考
- 受到 Rust 应用程序中需要一致的跨平台按键处理需求的启发


## 主要更新内容


1. **版本号更新**: 统一使用 "0.2.0" 版本
2. **新增高级功能**: 添加了快捷键解析、别名支持等高级功能说明
3. **完整的别名列表**: 提供了详细的修饰键和键别名列表
4. **API 概览**: 添加了完整的类型、特性和模块概览
5. **代码示例丰富**: 增加了更多实用的代码示例
6. **功能描述更准确**: 根据实际代码功能更新了特性描述