keyboard-codes

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

特性

• 跨平台支持: 为 Windows、Linux 和 macOS 提供全面的键码映射
• 完整的键定义: 标准键、修饰键、功能键、媒体键等
• 双向转换: 在键名和平台特定编码之间进行转换
• 自定义键映射: 支持自定义键和宏
• 零依赖 (核心功能)
• Serde 支持: 可选的序列化/反序列化
• PHF 支持: 可选完美哈希函数，提供更快的查找速度

安装

在 Cargo.toml 中添加：

[dependencies]

keyboard-codes = "0.1"

可选特性

• serde: 启用序列化/反序列化支持
• phf: 使用完美哈希函数加速字符串查找

[dependencies]

keyboard-codes = { version = "0.1", features = ["serde"] }

快速开始

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();

使用示例

基本按键操作

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));

自定义键映射

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());
}

平台检测

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 等
• 导航键: 方向键、Home、End、PageUp、PageDown
• 字母键: A 到 Z
• 数字键: 0-9 (主键盘和小键盘)
• 功能键: F1 到 F24
• 特殊键: CapsLock、NumLock、ScrollLock 等

修饰键

• 基本修饰键: Alt、Control、Shift、Meta
• 侧边特定修饰键: LeftAlt、RightAlt、LeftControl、RightControl 等

媒体键

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

平台支持

错误处理

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

use keyboard_codes::KeyParseError;

match "UnknownKey".parse::<Key>() {
    Ok(key) => println!("解析的按键: {}", key),
    Err(KeyParseError::UnknownKey(name)) => println!("未知按键: {}", name),
    Err(e) => println!("其他错误: {}", e),
}

工具函数

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"));

特性标志

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

API 概览

主要类型

• Key: 键盘按键枚举
• Modifier: 修饰键枚举
• Platform: 平台类型枚举
• CustomKey: 自定义按键
• CustomKeyMap: 自定义按键映射管理器

主要特性

• KeyCodeMapper: 键码映射特性
• FromStr: 字符串解析支持
• Display: 字符串显示支持

贡献

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

许可证

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

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

按您的选择。

致谢

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