keymapper

<p> <a href="https://github.com/houmain/keymapper/actions/workflows/build.yml"> <img alt="构建" src="https://yellow-cdn.veclightyear.com/835a84d5/3b1b1c92-0914-4e8a-bd86-562c53bf9910.svg"/></a> <a href="https://github.com/houmain/keymapper/issues"> <img alt="问题" src="https://yellow-cdn.veclightyear.com/835a84d5/5fb3d18a-65ea-4654-9c53-b012ca3db92e.svg"/></a>

<a href="#configuration">配置</a> | <a href="#example-configuration">示例</a> | <a href="#functional-principle">功能原理</a> | <a href="#keymapperctl">keymapperctl</a> | <a href="#installation">安装</a> | <a href="#building">构建</a> | <a href="https://github.com/houmain/keymapper/releases">更新日志</a>

</p>

一个跨平台的上下文感知键盘映射工具。它允许你：

• 重新定义系统范围或特定应用程序的键盘布局和快捷键。
• 在单个配置文件中管理所有键盘快捷键。
• 一次性更改不同应用程序中类似操作的快捷键。
• 在多个系统（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: 紧急情况下： 你始终可以按特殊组合键 <kbd>Shift</kbd>+<kbd>Escape</kbd>+<kbd>K</kbd> 来终止 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。