访问官网
Githubkeymapper
配置 | 示例 | 功能原理 | keymapperctl | 安装 | 构建 | 更新日志
一个跨平台的上下文感知键盘映射工具。它允许你：
- 重新定义系统范围或特定应用程序的键盘布局和快捷键。
- 在单个配置文件中管理所有键盘快捷键。
- 一次性更改不同应用程序中类似操作的快捷键。
- 在多个系统（GNU/Linux、Windows、MacOS）之间共享配置文件。
- 指定输入和输出为字符而不是输入它们所需的按键。
- 绑定键盘快捷键以启动应用程序。
- 使用keymapperctl从外部应用程序控制状态。
- 在映射中使用鼠标按钮和滚轮。
配置
配置文件易于手动编写，主要由输入表达式和相应的输出表达式组成，用 >> 分隔：
# 注释以 # 或 ; 开头，并持续到行尾
CapsLock >> Backspace
Z >> Y
Y >> Z
Control{Q} >> Alt{F4}
除非使用命令行参数 -c 覆盖，否则配置将从 keymapper.conf 读取，该文件位于以下常见位置：
- 在Linux和MacOS上，位于
$HOME/.config/和/etc/ - 在Windows上，位于用户的配置文件、
AppData\Local和AppData\Roaming文件夹
每个位置都可以有一个可选的 keymapper 子目录，最后在工作目录中查找。
命令行参数 -u 会在配置文件更改时自动重新加载配置。
:warning: 紧急情况下： 你始终可以按特殊组合键 Shift+Escape+K 来终止 keymapperd。
键名
键是根据其扫描码命名的，不受当前键盘布局的影响。
这些名称的选择与网络浏览器达成一致，因此可以使用这个方便的网站来获取键的名称。
为方便起见，字母和数字键也被命名为 A 到 Z 和 0 到 9。逻辑键 Shift、Control 和 Meta 也被定义（每个都匹配左右修饰键）。还有用于状态切换的虚拟键、任意键和无键。
鼠标按钮被命名为 ButtonLeft、ButtonRight、ButtonMiddle、ButtonBack 和 ButtonForward，滚轮被命名为 WheelUp 和 WheelDown。
也可以直接以十进制或十六进制表示法提供扫描码，而不是键名（例如 159、0x9F）。
:warning: 请注意，配置文件区分大小写。
输入表达式
输入表达式由一个或多个键名组成，用空格或括号分隔，它们具有不同的含义：
A B表示必须依次按下键（以任意顺序释放）。(A B)表示必须以任意顺序同时按下键。A{B}表示必须按住一个键的同时按下另一个键。!A表示不能按下某个键。- 组合和修饰符也可以嵌套，如
A{B{C}}或(A B){C}。 "..."字符串字面量在输入字符时匹配。- 以
?开头的映射在仅部分匹配时会被跳过。
输出表达式
输出表达式的格式类似于输入表达式格式：
A B表示依次按下键。(A B)表示同时按下两个键。A{B}表示按住一个键的同时按下另一个键。!A表示在应用其余表达式之前释放（可能已按下的）键。这也适用于虚拟键。^将输出分为两部分，一部分在输入键按下时应用，另一部分在键释放时应用。"..."字符串字面量允许指定要输入的字符。$()可用于启动应用程序。- 空表达式可用于抑制任何输出。
映射顺序
映射按顺序连续应用，直到找到匹配项，因此它们的顺序很重要。以下配置在按下 Meta 时立即输出 A：
Meta >> A
Meta{X} >> B
相反，当单独按下 Meta 时不会输出任何内容，因为根据是否跟随 X，输出的是 B 或 A：
Meta{X} >> B
Meta >> A
:warning: 你可能想在配置开始时添加一些映射，以确保常用的鼠标修饰键不会被阻止：
Shift >> Shift
Control >> Control
AltLeft >> AltLeft
有关如何应用映射的详细说明，请参见功能原理部分。
上下文感知
上下文块允许仅在特定上下文中启用映射。上下文可以通过 system、聚焦窗口的 title、窗口 class、进程 path 或事件源自的输入 device/device-id 来定义。
一个块持续到下一个块（或文件末尾）。适用于所有上下文的块可以使用 default 重新打开。例如：
[default]
[title = "Visual Studio"]
[system = "Linux", class != "qtcreator"] # '!=' 反转条件
[device = "Some Device Name"] # 连续的块共享映射
[device = "Some Other Device"]
[system = "Windows" path = "notepad.exe"] # 逗号分隔符是可选的
:warning: 在Windows上，device/device-id 过滤器需要安装虚拟设备驱动程序。在Wayland和具有更高权限的进程上，进程 path 可能不可用。在MacOS上，窗口 title 不可用。
可以使用系统托盘图标的"下一个键信息"功能或keymapperctl轻松获取上下文的值。
类和设备过滤器匹配具有完全相同字符串的上下文，其他过滤器匹配包含该字符串的上下文。
为了更精细的控制，可以使用正则表达式。这些表达式必须用斜杠分隔。可以选择在末尾添加 i 以使比较不区分大小写：
[title = /Visual Studio Code|Code OSS/i]
此外，modifier 过滤器允许根据一个或多个键的状态激活块：
# 当Virtual1处于按下状态且Virtual2未按下时激活
[modifier = "Virtual1 !Virtual2"]
抽象命令
为了简化将一个输入表达式映射到不同输出表达式的过程，可以先将其映射到一个抽象命令。命令名称可以任意选择，但不能是键名。配置区分大小写，所有键名都以大写字母开头，因此建议以小写字母开始命令名称：
Control{B} >> build
随后，可以在每个上下文中将此命令映射到一个输出表达式。最后一个活动映射会覆盖之前的映射：
build >> Control{B}
[title="Visual Studio"]
build >> (Shift Control){B}
多阶段
通过插入 [stage]，可以将配置拆分为多个阶段，这些阶段会被分别评估。一个阶段的输出是下一个阶段的输入，在下一个阶段中可以进行进一步映射：
# 调整键盘布局
Z >> Y
Y >> Z
# 映射前一阶段输出的按键
[stage]
Control{Z} >> undo
按键释放时的输出
当输出表达式包含 ^ 时，它仅在输入键被按下时应用到该点。^ 之后的部分直到输入释放时才应用。两部分都可以为空：
# 在 Windows 运行对话框出现后输入 "cmd"
Meta{C} >> Meta{R} ^ "cmd" Enter
# 防止按键重复
A >> B^
# 当 A 释放时输出 B
A >> ^B
虚拟按键
Virtual0 到 Virtual255 是虚拟按键，可用作状态开关。它们在输出表达式中使用时会被切换，并可在输入表达式中用作修饰键：
# 每当按下 ScrollLock 时，Virtual1 都会被切换
ScrollLock >> Virtual1
# 当 Virtual1 按下时，将 A 映射为 B
Virtual1{A} >> B
# 当 Virtual1 未按下时，将 E 映射为 F
!Virtual1 E >> F
# 只要 Virtual1 按下，就保持 G 按住
Virtual1 >> G
ContextActive 为每个上下文单独存在，当上下文变为活动/非活动时切换：
# 进入和离开上下文时切换 Virtual1
[title="Firefox"]
ContextActive >> Virtual1 ^ Virtual1
任意按键
Any 可用于输入和输出表达式。
在输入表达式中，它匹配任何按键；在输出表达式中，它输出匹配的输入。
# 交换 Control 和 Shift
Control{Any} >> Shift{Any}
Shift{Any} >> Control{Any}
要从任何映射中排除某个应用程序，可以在配置顶部添加以下内容：
[title="Remote Desktop"]
Any >> Any
[default]
在输出端，它还可以用于首先释放先前按下的修饰键：
A >> !Any A
无按键
输入表达式可以包含以毫秒为单位的超时，例如 500ms，用于指定没有按键按下的时间：
# 当 CapsLock 长按一段时间后输出 Escape
CapsLock{500ms} >> Escape
# 当 Control 快速按下并释放时输出 Escape
Control{!250ms} >> Escape
# 当 B 紧随 A 之后快速按下时输出 C
A !250ms B >> C
在输出表达式中，它可用于延迟输出或保持按键按住一段时间。例如：
A >> B 500ms C{1000ms}
字符输入
输出表达式可以包含要输入的字符串字面量。可输入的字符取决于你的键盘布局。例如：
AltRight{A} >> '@'
Meta{A} K >> "Kind regards,\nDouglas Quaid"
它们也可以在输入表达式中用于匹配输入的字符。例如：
? 'Abc' >> Backspace Backspace "Matched!"
:warning: 键盘布局在配置加载时评估，目前不支持切换。
按键别名 / 宏
为方便起见，可以定义按键甚至序列的别名。例如：
Win = Meta
Boss = Virtual1
Alt = AltLeft | AltRight # 定义一个逻辑键
proceed = Tab Tab Enter
greet = "Hello"
别名也可以参数化以创建宏。参数在方括号中提供，并通过 $0、$1 等引用。例如：
print = $(echo $0 $1 >> ~/keymapper.txt)
F1 >> print["pressed the key", F1]
有一些内置宏 repeat[EXPR, N]、length[STR]、add/sub/mul/div/mod/min/max[A, B]，它们允许定义一些更高级的宏。例如：
# 当字符串的最后一个字符被输入时，使用退格键撤消并输出新字符串
substitute = ? "$0" >> repeat[Backspace, sub[length["$0"], 1]] "$1"
substitute["Cat", "Dog"]
应用程序启动
$() 可以在输出表达式中使用，以嵌入在触发时应执行的命令。例如：
Meta{C} >> $(C:\windows\system32\calc.exe) ^
Meta{W} >> $(exo-open --launch WebBrowser) ^
# 在 Windows 上，通过在控制台应用程序前加上 'start' 来显示它们
Meta{C} >> $(start powershell) ^
:warning: 你可能想要在末尾添加 ^，以确保在输入保持按住时不会重复执行命令。
指令
以下指令（以 @ 开头的行）可以插入配置文件中：
-
allow-unmapped-commands和enforce-lowercase-commands更改命令的验证方式。最好一起使用，这样仍可检测到按键名称中的输入错误。例如：@allow-unmapped-commands @enforce-lowercase-commands A >> command1 # 正确，即使 'command1' 没有映射输出 command2 >> B # 正确，即使没有输入映射到 'command2' C >> Command3 # 错误：无效的按键 'Command3' Command4 >> D # 错误：无效的按键 'Command4' -
grab-device、skip-device、grab-device-id、skip-device-id允许明确指定keymapperd应抓取的设备（尚不支持 MacOS）。默认情况下，所有键盘设备都会被抓取，鼠标仅在映射了鼠标按钮或滚轮时才会被抓取。 这些过滤器的工作方式类似于上下文过滤器。例如：# 不抓取任何设备，只抓取这一个键盘 @skip-device /.*/ @grab-device "Some Device Name" -
include可用于在配置中包含文件。例如：@include "filename.conf"
示例配置
作者的个人配置可作为灵感来源（该配置本身也受到了 DreymaR's Big Bag Of Keyboard Tricks 的一些启发）。
要了解一个非常高级的配置是什么样子，请查看高级用户的配置。
功能原理
对于高级应用，了解映射的应用方式很有帮助：
- 所有按键操作都被拦截并附加到一个按键序列中。
- 每次按键时，按键序列都会与所有输入表达式按顺序匹配，直到找到匹配的表达式或可能匹配的表达式（当有更多按键跟随时）。非活动上下文中的映射会被跳过。
- 当按键序列不再能匹配任何输入表达式时（因为有更多按键跟随），会寻找最长的精确匹配（通过忽略最后的按键）。只要仍然没有匹配，第一个按键就会被移除并作为输出转发。
- 当输入表达式匹配时，这些按键会从序列中移除，并输出映射的表达式。
- 已经匹配但仍在物理上按下的按键会参与表达式匹配，作为按键序列的可选前缀。
keymapperctl
应用程序 keymapperctl 允许与运行中的 keymapper 进程通信。
它可以使用以下一个或多个参数多次运行：
--set-config "file" 设置新配置。
--type "string" 输入一串字符。
--next-key-info 输出关于下一个按键的信息。
--is-pressed <key> 当虚拟键按下时，将结果代码设为 0。
--is-released <key> 当虚拟键释放时，将结果代码设为 0。
--press <key> 按下虚拟键。
--release <key> 释放虚拟键。
--toggle <key> 切换虚拟键。
--wait-pressed <key> 等待直到虚拟键被按下。
--wait-released <key> 等待直到虚拟键被释放。
--wait-toggled <key> 等待直到虚拟键被切换。
--timeout <millisecs> 为下一个操作设置超时。
--wait <millisecs> 无条件等待给定的时间。
--instance <id> 替换具有相同 id 的另一个 keymapperctl 进程。
--restart 重新开始处理第一个操作。
--stdout 输出结果代码。
安装
程序分为两个部分：
keymapperd是需要获得抓取键盘设备和注入按键权限的服务。keymapper应该在图形环境中以普通用户身份运行。它加载配置，将配置和活动上下文通知服务，并执行映射的终端命令。
出于安全和效率考虑，两部分之间的通信尽可能保持最小化。
可以向两个进程传递命令行参数 -v，以输出详细的日志信息到控制台。
Linux
可以从最新发布页面下载预构建的软件包。Arch Linux 用户可以从 AUR 安装最新版本。
安装后，您可以通过创建配置文件并使用以下命令启动来试用：
sudo systemctl start keymapperd
keymapper
要永久安装，请将 keymapper 添加到桌面环境的自启动应用程序中，并启用 keymapperd 服务：
sudo systemctl enable keymapperd
为了使上下文感知在 Wayland 下工作，合成器必须通知 keymapper 关于焦点窗口的信息。对于基于 wlroots 的合成器，这可以直接工作，其他合成器需要使用 D-Bus 接口发送信息。提供了一个 GNOME Shell 扩展 和一个 KWin 脚本 来实现这一功能。
device-id 上下文过滤器的值可以通过查看 /dev/input/by-id 中的符号链接获得。
MacOS
MacOS 版本依赖于 Karabiner-Element 3.1.0 版本的虚拟设备驱动程序。 可以直接从 Karabiner-DriverKit-VirtualHIDDevice 安装，或者随 Karabiner Elements 14.13.0 一起安装。
提供了一个 Homebrew 公式用于构建和安装 keymapper：
brew tap houmain/tap
brew install --HEAD keymapper
最后，可以通过调用以下命令将 keymapperd 和 keymapper 添加到 launchd 守护进程/代理中：
sudo keymapper-launchd add
Windows
可以从最新发布页面下载安装程序和便携版本。
最方便但可能不是最新版本的安装方式是使用包管理器：
# 使用 winget 安装
winget install keymapper
# 使用 Chocolatey 安装
choco install keymapper
安装程序会配置 Windows 任务计划程序，以在登录时启动 keymapper.exe 和 keymapperd.exe。
要使用便携版本，只需创建一个配置文件并启动 keymapper.exe 和 keymapperd.exe。建议以提升的权限运行 keymapperd.exe。不这样做会有一些限制。最主要的是 Windows 键无法可靠地映射，以管理员身份运行的应用程序（如任务管理器）会抵制任何映射。
虚拟设备驱动程序
设备过滤器需要安装虚拟设备驱动程序。唯一已知的免费可用驱动是 Interception，但不幸的是它有一个严重的 bug，会导致设备在断开连接太多次后停止工作。在修复之前，不建议使用它，只有在绝对需要按设备进行过滤时才应该安装。interception.dll 需要放置在 keymapperd.exe 旁边。
构建
需要一个符合 C++17 标准的编译器。提供了 CMake 构建系统的脚本。
在 Debian Linux 及其衍生版上安装依赖：
sudo apt install build-essential git cmake libudev-dev libusb-1.0-0-dev libx11-dev libdbus-1-dev libwayland-dev libxkbcommon-dev libgtk-3-dev libayatana-appindicator3-dev
检出源代码：
git clone https://github.com/houmain/keymapper
构建：
cd keymapper
cmake -B build
cmake --build build
测试：
要试用，只需创建一个配置文件并使用以下命令启动：
sudo build/keymapperd -v
和
build/keymapper -v
许可证
它基于 GNU GPLv3 发布。它不提供任何保证。有关许可详情，请参阅 LICENSE。
