QKeyMapper
[按键映射工具] QKeyMapper，Qt开发Win10&Win11可用，不修改注册表、不需重新启动系统，可立即生效和停止。支持游戏手柄映射到键鼠，手柄摇杆控制鼠标移动，键鼠映射到虚拟游戏手柄，鼠标控制虚拟手柄移动摇杆等功能。
Install / Use
/learn @Zalafina/QKeyMapperREADME
📖 软件简介
QKeyMapper是兼容Win7/Win10/Win11的开源按键映射工具，使用Qt Widget 和 WinAPI 基于C++语言开发。可支持键盘、鼠标、游戏手柄、虚拟游戏手柄之间各种互相按键映射。软件下载解压后直接运行，不修改注册表、不需重新启动系统，依靠程序在内存中运行完成按键映射转换。程序运行中可随时控制映射功能生效和停止，软件退出后映射功能自动停止。适用于各种游戏或办公等目的的Windows PC端改键场景。
⚠️ 免责声明
QKeyMapper 是一个开源软件项目，基于 GPLv3 协议发布。使用本软件前请您仔细阅读并理解以下条款：
📋 使用责任
- 本软件按"现状"提供，不提供任何形式的明示或暗示保证
- 用户使用本软件的所有风险由用户自行承担
- 开发者不对因使用本软件而导致的任何直接或间接损失承担责任
🔒 安全提醒
- 本软件涉及底层系统操作和驱动程序，请确保您理解相关技术风险
- 使用前请备份重要数据，并在测试环境中验证功能
- 某些功能需要管理员权限，请谨慎授权
🎯 合规使用
- 请确保您的使用场景符合当地法律法规要求
- 本软件仅供学习、研究和合法的个人使用
- 禁止将本软件用于任何非法、恶意或侵犯他人权益的目的
💼 商业使用
- 本软件开发目的为开源分享，不鼓励商业使用
- 虽然 GPLv3 协议在技术上允许商业使用，但开发者的初衷是为社区提供免费工具
- 如确需商业使用，必须严格遵循 GPLv3 协议要求：
- 必须保持 GPLv3 协议并公开完整源代码
- 基于本软件的衍生作品也必须采用 GPLv3 协议开源
- 不得将本软件用于任何形式的闭源商业产品
- 强烈建议企业和商业用户寻找其他商业替代方案
- 协议详情请参阅 GPLv3 完整条款
继续使用本软件即表示您已阅读、理解并同意上述免责条款。
✨ 功能特性
| 设备 | 输入检测 | 输入映射 | 组合键支持 | 多键鼠支持 | 多手柄支持 | | -------- | -------- | --------- | --------- | --------- | ----------- | | 键盘 | ✅ | ✅ | ✅ | ✅ (10) | | | 鼠标 | ✅ | ✅ | ✅ | ✅ (10) | | | 物理手柄 | ✅ | | ✅ | | ✅ (10) | | 虚拟手柄 | | ✅ | ✅ | | ✅ (4) |
💡 常用名词解释列表
| 名词 | 含义解释 | |--------------------------|----------------------------------------| | 映射开始/停止快捷键 | 可通过键盘、鼠标或手柄按键开始和停止软件映射功能，默认快捷键L-Ctrl+F6 (键盘左Ctrl和F6键同时按下) | | 原始按键 | 键盘、鼠标或手柄等物理输入设备上直接按下的按键 | | 映射按键 | 游戏或软件中希望接收到的虚拟按键 | | 抬起映射 | 与映射按键类似，配合发送时机设定，原始按键抬起时可以发送不同的虚拟按键 | | 宏 | 映射宏列表窗口中，在"宏"标签页添加，编写格式与映射按键内容相同，每个设定项的宏列表各自独立，可使用"Macro(宏名)"形式插入到映射按键内容中 | | 通用宏 | 映射宏列表窗口中，在"通用宏"标签页添加，编写格式与映射按键内容相同，映射软件内所有设定项共用一个通用宏列表，可使用"UniversalMacro(通用宏名)"形式插入到映射按键内容中 | | 抬起映射 | 与映射按键类似，配合发送时机设定，原始按键抬起时可以发送不同的虚拟按键 | | 延时 | 发送映射按键时，设置虚拟按键按下后保持按下状态时间长短，单位毫秒 | | 组合键 | 原始按键或映射按键中代表多个按键同时按下，用"+"号连接。例如: A+B | | 按键序列 | 映射按键中代表先按下某个按键抬起释放后，再按下其他按键，用"»"号连接。例如: A+B⏱50»NONE⏱200»C⏱50，表示键盘A和B键同时按下50毫秒后抬起，等待200毫秒后键盘C键按下50毫秒后抬起 | | 连发 | 原始按键按下时持续自动发送映射按键，发送时间间隔可调整 | | 连发按下时间 | 勾选连发时，设置连发中每次按键按下状态保持的时长，连发按下时间+连发抬起时间是每次连发的时间间隔 | | 连发抬起时间 | 勾选连发时，设置连发中每次按键抬起状态保持的时长，连发按下时间+连发抬起时间是每次连发的时间间隔 | | 锁定 | 原始按键按下一次后，映射按键保持按下状态，原始按键再次按下解除映射按键按下状态。可配合连发一起使用，做到不按按键持续连发开火 | | 长按 | 原始按键按下指定时间后触发映射按键发送 | | 双击 | 原始按键在指定时间内双击两次时触发映射按键发送 | | 全局按键映射 | 开始映射后，只要系统处于解锁状态，所有情况下都生效的映射配置 | | 映射设定 | 一套包含设定名称的完整的映射配置，可以包含多个映射表Tab等各种设定信息，开启自动匹配前台进程后可以根据窗口信息匹配设置自动切换到此映射设定 | | 映射项设定 | Tab映射表中一行映射项包含的设定信息，可以修改连发、锁定、发送时机等各种映射项具体设定 | | 自动匹配前台进程 | 开始映射后，监测前台窗口信息是否与已保存的映射设定的窗口信息相匹配，检索到最匹配的映射设定后自动切换此设定。全局按键映射设定如果开启此选项，2秒内如果前台窗口没有相匹配的设定则自动切换到全局按键映射设定 | | 窗口信息 | 用户设定中编辑好的窗口进程名、窗口标题、窗口类名信息及对应的匹配方式，用于"自动匹配前台进程"功能进行前台窗口监测匹配使用。| | 正则匹配 | 窗口信息匹配方式中使用正则表达式进行窗口进程名、窗口标题、窗口类名的高级匹配方式，可以参考软件目录下的"QKeyMapper正则匹配规则说明.pdf"文档了解基本的正则表达式匹配规则。可以实现包括：等于、包含、开头匹配、结尾匹配、先出现A字符串再出现B字符串、包含A或B或C字符串、不包含特定字符串等各种复杂匹配方式在内的文本匹配。 |
📦 最新Release版本压缩包下载:
https://github.com/Zalafina/QKeyMapper/releases/latest
https://gitee.com/asukavov/QKeyMapper/releases/latest
※ QKeyMapper_vX.Y.Z_x64/x86开头的ZIP包是编译好的可执行文件压缩包Build_YYYYMMDD代表编译日期，较新的编译日期有相应的新增功能说明。Win10及Win11系统推荐使用 Qt6_x64 版本release包，只有无法使用Qt6版本的Win7系统需要使用Qt5版本release包。
⭐ Star 趋势图
如果 QKeyMapper 按键映射软件对您有帮助，请给个 ⭐ Star 支持一下，让更多的人看到 QKeyMapper
💡 软件使用须知
Win10及Win11系统推荐使用Qt6版本，提供Qt5版本只是为了能兼容Win7系统。Win7下如果无法使用Qt6版本的话请下载Qt5版本使用。
📌注意1 : 使用时可能需要安装 Visual C++ Redistributable 64位运行库。<br>VC++ 2015-2022 64位运行库，微软下载网址：<br>https://aka.ms/vs/17/release/vc_redist.x64.exe
- ( 32位系统则下载安装32位运行库 https://aka.ms/vs/17/release/vc_redist.x86.exe )
📌注意2 : 软件的多设备支持功能使用了Interception驱动，此驱动存在下面已知问题，输入设备(键盘/鼠标)反复USB接口插拔、断开重连或者Windows系统进入睡眠状态再唤醒会导致系统的输入设备(键盘/鼠标等)ID增加，ID数值超过Interception驱动支持上限(10个键盘、10个鼠标)会出现输入设备无法工作的问题，只有完全重新启动操作系统才能复归(保持软件工作状态的快速重启不复归)。请在确实需要使用多设备功能的情况并且仔细阅读了解驱动程序使用方法以及可能引发的副作用前提下再谨慎的安装多设备驱动，避免引发不必要的困扰。如果发生鼠标或键盘无效问题，先对系统完全重启后，点击多设备卸载驱动按钮后再重启系统会恢复正常状态不再受驱动影响。
📌注意3 : ViGEMBus驱动与vJoy驱动都是虚拟手柄驱动，不建议在系统中同时安装。如果操作系统中之前安装过vJoy驱动并且出现虚拟手柄相关的异常问题，建议卸载vJoy驱动后确认是否可以解决问题。
📌注意4: Win7系统使用虚拟手柄功能需要自己安装ViGEMBus v1.16.116
- https://github.com/Zalafina/ViGEmBus_v1.16.116_Win7_InstallFiles
🔧 软件使用建议
※通常情况下建议先运行QKeyMapper映射工具再运行需要使用按键映射的游戏或软件，避免按键被其他软件拦截导致映射工具无法检测到。
※使用QKeyMapper强烈建议开启Windows系统的筛选键，避免持续按下键盘按键时候Windows系统不停发送同一个按键，会引发各种按键映射功能的不可预知问题。<br>v1.3.8.20250816版本增加了"开启系统筛选键"设定勾选框，勾选此设定后，开始映射时如果系统没有开启筛选键，程序会自动开启系统筛选键，映射结束后会自动恢复映射开始前的系统筛选键关闭状态。
-
Win10系统筛选键开启方式
Windows设置 -> 轻松使用 -> 键盘 -> 筛选键 <div align="center"><img src="https://raw.githubusercontent.com/Zalafina/QKeyMapper/master/screenshot/Win10_FilterKey.png" width="1839" height="auto"/></div> -
Win11系统筛选键开启方式
设置 -> 辅助功能 -> 键盘 -> 筛选键 <div align="center"><img src="https://raw.githubusercontent.com/Zalafina/QKeyMapper/master/screenshot/Win11_FilterKey.png" width="1182" height="auto"/></div>
📣 已知问题
※使用物理游戏手柄原始按键映射为鼠标左键的情况下，请避免使用此方式点击QKeyMapper窗口标题栏右上角的关闭、最小化、最大化按钮区域，会发生界面卡住的现象。如果进行上面操作发生界面卡住问题可以通过按下键盘Win键或者Win+D组合键等通过键盘切换前台窗口的方式解除卡住状态。
📚 按键映射工具使用技巧等参考Wiki页面：
📺 使用教学视频合集请点击下方图片
<div align="center"><img src="https://raw.githubusercontent.com/Zalafina/QKeyMapper/master/screenshot/show_video.png" width="572" height="auto"/></div>
💬 使用中有疑问也可以加Q群咨询 (群号: 906963961)
<div align="center"><img src="https://raw.githubusercontent.com/Zalafina/QKeyMapper/master/screenshot/QKeyMapper_QGroup_Number.png" width="357" height="auto"/></div>🎯 新添加功能列表(根据更新时间降序排列)
- v1.3.8(Build 20260406)
- 映射表中右键点击 分类 列时弹出专用的右键菜单，可以 选择分类 和 输入分类。
- "悬浮按钮设定" 窗口中添加 同步显示按下和锁定状态 勾选框，默认是勾选状态。按下键盘、鼠标或手柄原始按键时会同步到悬浮按钮的显示。
- 主窗口右侧添加"显示悬浮列"可勾选按钮，按下状态在映射表中显示"悬浮"列，可以更改和显示当前映射项是否开启悬浮按钮功能。
- v1.3.8(Build 20260328)
- SendText(...) 和 PasteText(...) 支持特殊参数 {{CLIPBOARD_TEXT}}。当括号内内容完整写成 {{CLIPBOARD_TEXT}} 时，会读取当前 Windows 系统剪贴板中的字符串内容进行发送；如果剪贴板中不存在字符串内容，则不执行发送。
发送/粘贴剪贴板文本示例
SendText({{CLIPBOARD_TEXT}}) PasteText({{CLIPBOARD_TEXT}}) - "映射项设定"窗口中添加 悬浮按钮设定，勾选"启用悬浮按钮"，会为此设定项单独显示一个可点击的悬浮按钮。VButton{虚拟按钮}启用悬浮按钮后此虚拟按钮不在虚拟按钮面板中显示，变为悬浮按钮显示。
- 添加 ShowAllFButtons 和 HideAllFButtons 映射按键，可配合"悬浮按钮设定"的"映射开始时显示"用于控制当前映射表中所有悬浮按钮的显示和隐藏。
- 映射表中右键点击"禁用"、"连发"、"锁定"列时候弹出专用的右键菜单。
- "显示切换"快捷键功能调整，默认在系统托盘隐藏状态和正常显示状态直接切换。如果主动将窗口最小化到任务栏，则"显示切换"快捷键变为在任务栏最小化显示和正常显示之间切换，此切换状态在手动隐藏窗口到系统托盘后恢复默认的系统托盘和正常显示之间显示切换功能。
- SendText(...) 和 PasteText(...) 支持特殊参数 {{CLIPBOARD_TEXT}}。当括号内内容完整写成 {{CLIPBOARD_TEXT}} 时，会读取当前 Windows 系统剪贴板中的字符串内容进行发送；如果剪贴板中不存在字符串内容，则不执行发送。
- v1.3.8(Build 20260320)
- 为主窗口映射表、映射宏列表、映射序列编辑列表这三个表格添加鼠标右键菜单。
- 修复VButton按钮面板显示布局问题。
- v1.3.8(Build 20260316)
- 修复VButton显示问题。
- 修复手柄摇杆阈值检测问题。
- v1.3.8(Build 20260306)
- 新增支持 VButton{虚拟按钮标签} 原始按键，添加此类虚拟按钮映射后，可以将当前映射表中的所有虚拟按钮在虚拟按钮面板中显示出来，鼠标点击按钮发送对应的映射按键。 ※虚拟按钮面板的网格布局行列数、颜色、布局、尺寸、透明度和显示位置位置等自定义设置可通过"映射设定"标签页的"虚拟按钮面板设定"对话框进行调整。虚拟按钮面板显示中右键点击弹出的菜单中也可以选择"虚拟按钮面板设定"选项进入相同的设定窗口。
- 添加 ShowVButtonPanel 和 HideVButtonPanel 映射按键，可配合"虚拟按钮面板设定"的"映射开始时显示"用于控制虚拟按钮面板显示和隐藏。
- 物理手柄摇杆和扳机键添加 重推/轻推、重按/轻按 检测，在映射设定标签页->映射高级设定窗口中可以分别对左右摇杆和左右扳机键的 重推/轻推、重按/轻按 阈值分别进行设置。
轻推/轻按新增原始按键如下所示
Joy-LS-Up_Light -> 左摇杆轻上推 Joy-LS-Down_Light -> 左摇杆轻下推 Joy-LS-Left_Light -> 左摇杆轻左推 Joy-LS-Right_Light -> 左摇杆轻右推 Joy-RS-Up_Light -> 右摇杆轻上推 Joy-RS-Down_Light -> 右摇杆轻下推 Joy-RS-Left_Light -> 右摇杆轻左推 Joy-RS-Right_Light
Related Skills
node-connect
342.5kDiagnose OpenClaw node connection and pairing failures for Android, iOS, and macOS companion apps
frontend-design
85.3kCreate distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
openai-whisper-api
342.5kTranscribe audio via OpenAI Audio Transcriptions API (Whisper).
qqbot-media
342.5kQQBot 富媒体收发能力。使用 <qqmedia> 标签，系统根据文件扩展名自动识别类型（图片/语音/视频/文件）。
