wehub-resource-sync
301 lines
10 KiB
Markdown
301 lines
10 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!NOTE]
|
||
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
|
||
> [English](./README.en.md) · [原始项目](https://github.com/rvaiya/keyd) · [上游 README](https://github.com/rvaiya/keyd/blob/HEAD/README.md)
|
||
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
|
||
|
||
[](https://ko-fi.com/rvaiya)
|
||
|
||
# Impetus
|
||
|
||
[](https://repology.org/project/keyd/versions)
|
||
|
||
Linux 缺少一套好用的按键重映射方案。要想获得满意的效果，往往需要组合使用多种工具（例如 xcape、xmodmap），而最终效果还常常绑定在特定环境（如 X11）上。keyd 试图通过提供一个灵活的全系统守护进程来解决这一问题；它利用内核级输入原语（evdev、uinput）来重映射按键。
|
||
|
||
# 关于 v2 的说明
|
||
|
||
自首次发布以来，配置格式已经历多次迭代。若要从 v1 迁移配置，最好重新阅读 [man page](https://raw.githubusercontent.com/rvaiya/keyd/refs/heads/master/docs/keyd.scdoc) (`man keyd`)。
|
||
|
||
另请参阅：[changelog](docs/CHANGELOG.md)。
|
||
|
||
# 目标
|
||
|
||
- 速度 （用 C 编写、手工调优的输入循环，耗时 <<1ms）
|
||
- 简洁 （直观易懂的[配置格式](#sample-config)）
|
||
- 一致性 （修饰键默认就能与[层（layer）配合良好](https://github.com/rvaiya/keyd/blob/6dc2d5c4ea76802fd192b143bdd53b1787fd6deb/docs/keyd.scdoc#L128)）
|
||
- 模块化 （遵循 UNIX 哲学的核心，可通过 [IPC](https://github.com/rvaiya/keyd/blob/90973686723522c2e44d8e90bb3508a6da625a20/docs/keyd.scdoc#L391) 机制扩展）
|
||
|
||
# 特性
|
||
|
||
keyd 拥有多项独特功能，其中许多传统上只出现在自定义键盘固件（如 [QMK](https://github.com/qmk/qmk_firmware)）中，也有一些是 keyd 独有的。
|
||
|
||
其中较有意思的有：
|
||
|
||
- 层（layer）（支持[混合修饰键（hybrid modifiers）](https://github.com/rvaiya/keyd/blob/6dc2d5c4ea76802fd192b143bdd53b1787fd6deb/docs/keyd.scdoc#L128)).）
|
||
- 按键过载（tap/hold 行为不同）。
|
||
- 针对特定键盘的配置。
|
||
- 即时重映射（无需再刷固件 :))。
|
||
- 客户端-服务器模型，便于脚本化以及与显示服务器无关的应用重映射。（当前内置对 X、sway 和 gnome（Wayland）的支持。）
|
||
- 全系统配置（在 VT 中也可用）。
|
||
- 对修饰键过载的一等支持。
|
||
- Unicode 支持。
|
||
|
||
### keyd 适合这些人：
|
||
|
||
- 想尝试自定义[层（layer）](https://docs.qmk.fm/feature_layers)（即自定义 Shift 键）
|
||
和 oneshot 修饰键。
|
||
- 想在同一台机器上使用多台键盘、各自采用不同布局。
|
||
- 希望能够重映射 `C-1`，同时不破坏修饰键语义。
|
||
- 想要一种易于理解的键盘配置格式。
|
||
- 喜欢遵循 Unix 哲学的小型守护进程。
|
||
- 想把 Control 和 Escape 键放到它们本该在的位置。
|
||
- 希望切换到 VT 调试问题时，不会弄乱自己的键位映射。
|
||
|
||
### keyd 不是：
|
||
|
||
- 用于编程单个按键按下/抬起事件的工具。
|
||
|
||
# 依赖
|
||
|
||
- 你喜爱的 C 编译器
|
||
- Linux 内核头文件（大多数系统上已自带）
|
||
|
||
## 可选
|
||
|
||
- python （用于应用特定重映射）
|
||
- python-xlib （仅用于 X 支持）
|
||
- dbus-python （仅用于 KDE 支持）
|
||
|
||
# 安装
|
||
|
||
*注意：* master 作为开发分支，版本发布之间偶尔会有问题。发布版本已[打标签](https://github.com/rvaiya/keyd/tags),，可视为稳定版。
|
||
|
||
## 从源码安装
|
||
|
||
git clone https://github.com/rvaiya/keyd
|
||
cd keyd
|
||
make && sudo make install
|
||
sudo systemctl enable --now keyd
|
||
|
||
# 快速入门
|
||
|
||
1. 安装并启动 keyd（例如 `sudo systemctl enable keyd --now`）
|
||
|
||
2. 将以下内容放入 `/etc/keyd/default.conf`：
|
||
|
||
```
|
||
[ids]
|
||
|
||
*
|
||
|
||
[main]
|
||
|
||
# Maps capslock to escape when pressed and control when held.
|
||
capslock = overload(control, esc)
|
||
|
||
# Remaps the escape key to capslock
|
||
esc = capslock
|
||
```
|
||
|
||
可通过 `keyd monitor` 命令获取键名。请注意，在 keyd 运行期间，该命令的输出会对应 keyd 的输出。若要查看原始输入事件，需先停止 keyd，再运行该命令。更多细节请参阅 man page。
|
||
|
||
3. 运行 `sudo keyd reload` 以重新加载配置。
|
||
|
||
4. 更完整的说明请参阅 man page（`man keyd`）。
|
||
|
||
配置错误会出现在日志输出中，也可通过系统的服务管理器以常规方式查看（例如 `sudo journalctl -eu keyd`）。
|
||
|
||
*注意*：错误的配置文件可能使你的机器无法使用。
|
||
若遇到这种情况，特殊按键序列
|
||
`backspace+escape+enter` 应能让 keyd 终止运行。
|
||
|
||
部分鼠标（例如 Logitech MX Master）能够发出按键事件，
|
||
因此会被通配符 id 匹配。可能需要显式将它们加入黑名单。
|
||
|
||
## 应用特定重映射（实验性）
|
||
|
||
- 将自己加入 keyd 组：
|
||
|
||
`usermod -aG keyd <user>`
|
||
|
||
- 填写 `~/.config/keyd/app.conf`：
|
||
|
||
例如
|
||
|
||
[alacritty]
|
||
|
||
alt.] = macro(C-g n)
|
||
alt.[ = macro(C-g p)
|
||
|
||
[chromium]
|
||
|
||
alt.[ = C-S-tab
|
||
alt.] = macro(C-tab)
|
||
|
||
- 运行：
|
||
|
||
`keyd-application-mapper`
|
||
|
||
你可能希望将 `keyd-application-mapper -d` 放在
|
||
显示服务器初始化逻辑中的某处（例如 ~/.xinitrc），除非你运行的是 Gnome。
|
||
|
||
更多细节请参阅 man page。
|
||
|
||
## SBC 支持
|
||
|
||
在 Giorgi Chavchanidze 的贡献下，已通过 usb-gadget 为单板计算机（SBC）加入实验性支持。
|
||
|
||
详情请参阅 [usb-gadget.md](src/vkbd/usb-gadget.md)。
|
||
|
||
## 软件包
|
||
|
||
部分发行版已有第三方软件包。若希望将你的发行版加入列表，请提交 PR。这些软件包由社区成员好心维护，作者不对其承担个人责任。
|
||
|
||
### Alpine Linux
|
||
|
||
[keyd](https://pkgs.alpinelinux.org/packages?name=keyd) 软件包由 [@jirutka](https://github.com/jirutka). 维护。
|
||
|
||
### Arch
|
||
|
||
[Arch Linux](https://archlinux.org/packages/extra/x86_64/keyd/) 软件包由 Arch 打包者维护。
|
||
|
||
### Debian
|
||
|
||
Debian 13（"trixie"）及更高版本提供 keyd 软件包。安装方法：
|
||
|
||
```shell
|
||
sudo apt install keyd
|
||
```
|
||
|
||
### Fedora
|
||
|
||
[COPR](https://copr.fedorainfracloud.org/coprs/alternateved/keyd/) 软件包由 [@alternateved](https://github.com/alternateved). 维护。
|
||
|
||
### Gentoo
|
||
|
||
[GURU](https://gitweb.gentoo.org/repo/proj/guru.git/tree/app-misc/keyd) 软件包由 [jack@pngu.org](mailto:jack@pngu.org) 维护。
|
||
|
||
### openSUSE
|
||
[opensuse](https://software.opensuse.org//download.html?project=hardware&package=keyd) 软件包由 [@bubbleguuum](https://github.com/bubbleguuum). 维护。
|
||
|
||
可使用 `sudo zypper in keyd` 轻松安装。
|
||
|
||
### Ubuntu
|
||
|
||
Ubuntu 25.04（"plucky"）及更高版本提供 keyd 软件包。安装方法：
|
||
|
||
```shell
|
||
sudo apt install keyd
|
||
```
|
||
|
||
此外，可将最新 Debian 软件包反向移植到各 Ubuntu 版本，见
|
||
[`ppa:keyd-team/ppa`
|
||
archive](https://launchpad.net/~keyd-team/+archive/ubuntu/ppa).
|
||
|
||
### Void Linux
|
||
|
||
[xbps](https://github.com/void-linux/void-packages/tree/master/srcpkgs/keyd) 软件包由 [@Barbaross](https://gitlab.com/Barbaross). 维护。
|
||
|
||
可使用 `sudo xbps-install -Su keyd` 轻松安装。
|
||
|
||
# 示例 1
|
||
|
||
[ids]
|
||
|
||
*
|
||
|
||
[main]
|
||
|
||
leftshift = oneshot(shift)
|
||
capslock = overload(symbols, esc)
|
||
|
||
[symbols]
|
||
|
||
d = ~
|
||
f = /
|
||
...
|
||
|
||
# 示例 2
|
||
|
||
这会覆盖 macOS 用户可能更熟悉的一些特定 Alt 组合键，
|
||
同时保持其余映射不变。
|
||
|
||
[ids]
|
||
*
|
||
|
||
[alt]
|
||
|
||
x = C-x
|
||
c = C-c
|
||
v = C-v
|
||
|
||
a = C-a
|
||
f = C-f
|
||
r = C-r
|
||
z = C-z
|
||
|
||
# 推荐配置
|
||
|
||
许多用户可能并不想充分利用 keyd 的全部能力。
|
||
若你只想获得一些简单的生活质量改进，我推荐以下配置：
|
||
|
||
[ids]
|
||
|
||
*
|
||
|
||
[main]
|
||
|
||
shift = oneshot(shift)
|
||
meta = oneshot(meta)
|
||
control = oneshot(control)
|
||
|
||
leftalt = oneshot(alt)
|
||
rightalt = oneshot(altgr)
|
||
|
||
capslock = overload(control, esc)
|
||
insert = S-insert
|
||
|
||
该配置将 capslock 过载为：轻按作 escape，按住作 control；
|
||
并将所有修饰键重映射为 "oneshot" 键。因此，要输入字母 A，
|
||
你现在可以轻按 shift 再按 a，而不必一直按住 shift。
|
||
最后，它将 insert 重映射为 S-insert（在 X11 上用于粘贴）。
|
||
|
||
# 常见问题
|
||
|
||
## 启用 keyd 后，触控板为何会干扰输入？
|
||
|
||
libinput 是大多数 Wayland 和 X11 环境使用的高级输入组件，其中包含一项称为「打字时禁用」（disable-while-typing）的功能，可在打字时禁用触控板。
|
||
|
||
为实现这一点，它需要区分内置键盘与外接键盘，其做法是为特定硬件硬编码规则（称为 quirks）。由于 keyd 会创建一个虚拟设备，该设备同时涵盖外接键盘与集成键盘，因此你需要让 libinput 将 keyd 虚拟设备视为内置设备。
|
||
|
||
可通过在 `/etc/libinput/local-overrides.quirks`（若不存在可能需要新建）中添加以下内容来实现：
|
||
|
||
```
|
||
[Serial Keyboards]
|
||
|
||
MatchUdevType=keyboard
|
||
MatchName=keyd*keyboard
|
||
AttrKeyboardIntegration=internal
|
||
```
|
||
|
||
感谢 @mark-herbert42 和 @canadaduane 提供的原始解决方案。
|
||
|
||
## xmodmap/setxkbmap/* 呢？
|
||
|
||
xmodmap 及其同类工具是显示服务器（display server）层面的工具，功能有限。keyd 是系统级方案，可实现分层（layering）和 [oneshot](https://docs.qmk.fm/#/one_shot_keys) 修饰键等高级功能。虽然部分 X 工具提供类似功能，但据我所知，没有哪款能像 keyd 这样灵活。
|
||
|
||
## [kmonad](https://github.com/kmonad/kmonad)? 呢？
|
||
|
||
keyd 编写于数年前，目的是让我能在我不断扩充的键盘收藏上轻松试验不同布局。当时 kmonad 尚不存在，而像 [QMK](https://github.com/qmk/qmk_firmware)（启发 keyd 的自定义键盘固件）这类方案，是获得可比功能的唯一途径。发布 keyd 之后我才了解到 kmonad。kmonad 是一个目标相近的优秀项目，但采用了不同思路，设计哲学也不同。
|
||
|
||
值得注意的是，keyd 完全用 C 编写，兼顾性能与简洁，很可能永远不会像 kmonad（可用 Haskell 扩展）那样可配置。话虽如此，在作者看来，它在不到 2000 行 C 代码内提供了最有价值的功能，并附带一种与语言无关的简单配置格式。
|
||
|
||
## 为什么 keyd 不实现功能 X？
|
||
|
||
如果你觉得缺少某些功能或发现了 bug，欢迎在 GitHub 上提交 issue。keyd 秉持极简（但合理）的设计哲学，有意省略某些功能（例如以 root 身份执行任意可执行文件）。像 QMK 这类自定义键盘固件中已有的功能，是较好的纳入候选。
|
||
|
||
# 贡献
|
||
|
||
请参阅 [CONTRIBUTING](CONTRIBUTING.md)。
|
||
IRC 频道：oftc 上的 #keyd
|