wehub/rvaiya--keyd
1
0
Fork 0
Code Issues Pull Requests Actions Deployments Models Agent Notes Packages Projects Releases Wiki Activity

docs: make Chinese README the default

Browse Source
This commit is contained in:
wehub-resource-sync
2026-07-13 10:18:27 +00:00
parent 2fa2ab7a2c
commit 74ce1d523e
1 changed files with 111 additions and 146 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+111 -146
View File
@@ -1,90 +1,87 @@
<!-- 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 文件为准。
[![Kofi](https://badgen.net/badge/icon/kofi?icon=kofi&label)](https://ko-fi.com/rvaiya)
# Impetus
[![Packaging status](https://repology.org/badge/tiny-repos/keyd.svg)](https://repology.org/project/keyd/versions)
Linux lacks a good key remapping solution. In order to achieve satisfactory
results a medley of tools need to be employed (e.g xcape, xmodmap) with the end
result often being tethered to a specified environment (X11). keyd attempts to
solve this problem by providing a flexible system wide daemon which remaps keys
using kernel level input primitives (evdev, uinput).
Linux 缺少一套好用的按键重映射方案。要想获得满意的效果，往往需要组合使用多种工具（例如 xcape、xmodmap），而最终效果还常常绑定在特定环境（如 X11）上。keyd 试图通过提供一个灵活的全系统守护进程来解决这一问题；它利用内核级输入原语（evdev、uinput）来重映射按键。
# Note on v2
# 关于 v2 的说明
The config format has undergone several iterations since the first
release. For those migrating their configs from v1 it is best
to reread the [man page](https://raw.githubusercontent.com/rvaiya/keyd/refs/heads/master/docs/keyd.scdoc) (`man keyd`).
自首次发布以来，配置格式已经历多次迭代。若要从 v1 迁移配置，最好重新阅读 [man page](https://raw.githubusercontent.com/rvaiya/keyd/refs/heads/master/docs/keyd.scdoc) (`man keyd`)。
See also: [changelog](docs/CHANGELOG.md).
另请参阅：[changelog](docs/CHANGELOG.md)。
# Goals
# 目标
- Speed (a hand tuned input loop written in C that takes <<1ms)
- Simplicity (a [config format](#sample-config) that is intuitive)
- Consistency (modifiers that [play nicely with layers](https://github.com/rvaiya/keyd/blob/6dc2d5c4ea76802fd192b143bdd53b1787fd6deb/docs/keyd.scdoc#L128) by default)
- Modularity (a UNIXy core extensible through the use of an [IPC](https://github.com/rvaiya/keyd/blob/90973686723522c2e44d8e90bb3508a6da625a20/docs/keyd.scdoc#L391) mechanism)
- 速度 （用 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) 机制扩展）
# Features
# 特性
keyd has several unique features many of which are traditionally only
found in custom keyboard firmware like [QMK](https://github.com/qmk/qmk_firmware)
as well as some which are unique to keyd.
keyd 拥有多项独特功能，其中许多传统上只出现在自定义键盘固件（如 [QMK](https://github.com/qmk/qmk_firmware)）中，也有一些是 keyd 独有的。
Some of the more interesting ones include:
其中较有意思的有：
- Layers (with support for [hybrid modifiers](https://github.com/rvaiya/keyd/blob/6dc2d5c4ea76802fd192b143bdd53b1787fd6deb/docs/keyd.scdoc#L128)).
- Key overloading (different behaviour on tap/hold).
- Keyboard specific configuration.
- Instantaneous remapping (no more flashing :)).
- A client-server model that facilitates scripting and display server agnostic application remapping. (Currently ships with support for X, sway, and gnome (wayland)).
- System wide config (works in a VT).
- First class support for modifier overloading.
- Unicode support.
- 层（layer）（支持[混合修饰键（hybrid modifiers）](https://github.com/rvaiya/keyd/blob/6dc2d5c4ea76802fd192b143bdd53b1787fd6deb/docs/keyd.scdoc#L128)).）
- 按键过载（tap/hold 行为不同）。
- 针对特定键盘的配置。
- 即时重映射（无需再刷固件 :))。
- 客户端-服务器模型，便于脚本化以及与显示服务器无关的应用重映射。（当前内置对 X、sway 和 gnome（Wayland）的支持。）
- 全系统配置（在 VT 中也可用）。
- 对修饰键过载的一等支持。
- Unicode 支持。
### keyd is for people who:
### keyd 适合这些人：
- Would like to experiment with custom [layers](https://docs.qmk.fm/feature_layers) (i.e custom shift keys)
and oneshot modifiers.
- Want to have multiple keyboards with different layouts on the same machine.
- Want to be able to remap `C-1` without breaking modifier semantics.
- Want a keyboard config format which is easy to grok.
- Like tiny daemons that adhere to the Unix philosophy.
- Want to put the control and escape keys where God intended.
- Wish to be able to switch to a VT to debug something without breaking their keymap.
- 想尝试自定义[层（layer）](https://docs.qmk.fm/feature_layers)（即自定义 Shift 键）
和 oneshot 修饰键。
- 想在同一台机器上使用多台键盘、各自采用不同布局。
- 希望能够重映射 `C-1`，同时不破坏修饰键语义。
- 想要一种易于理解的键盘配置格式。
- 喜欢遵循 Unix 哲学的小型守护进程。
- 想把 Control 和 Escape 键放到它们本该在的位置。
- 希望切换到 VT 调试问题时，不会弄乱自己的键位映射。
### What keyd isn't:
### keyd 不是：
- A tool for programming individual key up/down events.
- 用于编程单个按键按下/抬起事件的工具。
# Dependencies
# 依赖
- Your favourite C compiler
- Linux kernel headers (already present on most systems)
- 你喜爱的 C 编译器
- Linux 内核头文件（大多数系统上已自带）
## Optional
## 可选
- python (for application specific remapping)
- python-xlib (only for X support)
- dbus-python (only for KDE support)
- python （用于应用特定重映射）
- python-xlib （仅用于 X 支持）
- dbus-python （仅用于 KDE 支持）
# Installation
# 安装
*Note:* master serves as the development branch, things may occasionally break
between releases. Releases are [tagged](https://github.com/rvaiya/keyd/tags), and should be considered stable.
*注意：* master 作为开发分支，版本发布之间偶尔会有问题。发布版本已[打标签](https://github.com/rvaiya/keyd/tags),，可视为稳定版。
## From Source
## 从源码安装
git clone https://github.com/rvaiya/keyd
cd keyd
make && sudo make install
sudo systemctl enable --now keyd
# Quickstart
# 快速入门
1. Install and start keyd (e.g `sudo systemctl enable keyd --now`)
1. 安装并启动 keyd（例如 `sudo systemctl enable keyd --now`）
2. Put the following in `/etc/keyd/default.conf`:
2. 将以下内容放入 `/etc/keyd/default.conf`：
```
[ids]
@@ -100,34 +97,30 @@ capslock = overload(control, esc)
esc = capslock
```
Key names can be obtained by using the `keyd monitor` command. Note that while keyd is running, the output of this
command will correspond to keyd's output. The original input events can be seen by first stopping keyd and then
running the command. See the man page for more details.
可通过 `keyd monitor` 命令获取键名。请注意，在 keyd 运行期间，该命令的输出会对应 keyd 的输出。若要查看原始输入事件，需先停止 keyd，再运行该命令。更多细节请参阅 man page。
3. Run `sudo keyd reload` to reload the config set.
3. 运行 `sudo keyd reload` 以重新加载配置。
4. See the man page (`man keyd`) for a more comprehensive description.
4. 更完整的说明请参阅 man page（`man keyd`）。
Config errors will appear in the log output and can be accessed in the usual
way using your system's service manager (e.g `sudo journalctl -eu keyd`).
配置错误会出现在日志输出中，也可通过系统的服务管理器以常规方式查看（例如 `sudo journalctl -eu keyd`）。
*Note*: It is possible to render your machine unusable with a bad config file.
Should you find yourself in this position, the special key sequence
`backspace+escape+enter` should cause keyd to terminate.
*注意*：错误的配置文件可能使你的机器无法使用。
若遇到这种情况，特殊按键序列
`backspace+escape+enter` 应能让 keyd 终止运行。
Some mice (e.g the Logitech MX Master) are capable of emitting keys and
are consequently matched by the wildcard id. It may be necessary to
explicitly blacklist these.
部分鼠标（例如 Logitech MX Master）能够发出按键事件，
因此会被通配符 id 匹配。可能需要显式将它们加入黑名单。
## Application Specific Remapping (experimental)
## 应用特定重映射（实验性）
- Add yourself to the keyd group:
- 将自己加入 keyd 组：
`usermod -aG keyd <user>`
- Populate `~/.config/keyd/app.conf`:
- 填写 `~/.config/keyd/app.conf`：
E.G
例如
[alacritty]
@@ -139,39 +132,36 @@ E.G
alt.[ = C-S-tab
alt.] = macro(C-tab)
- Run:
- 运行：
`keyd-application-mapper`
You will probably want to put `keyd-application-mapper -d` somewhere in your
display server initialization logic (e.g ~/.xinitrc) unless you are running Gnome.
你可能希望将 `keyd-application-mapper -d` 放在
显示服务器初始化逻辑中的某处（例如 ~/.xinitrc），除非你运行的是 Gnome。
See the man page for more details.
更多细节请参阅 man page。
## SBC support
## SBC 支持
Experimental support for single board computers (SBCs) via usb-gadget
has been added courtesy of Giorgi Chavchanidze.
在 Giorgi Chavchanidze 的贡献下，已通过 usb-gadget 为单板计算机（SBC）加入实验性支持。
See [usb-gadget.md](src/vkbd/usb-gadget.md) for details.
详情请参阅 [usb-gadget.md](src/vkbd/usb-gadget.md)。
## Packages
## 软件包
Third-party packages exist for some distributions. If you wish to add
yours to the list please file a PR. These are kindly maintained by community
members, no personal responsibility is taken for them.
部分发行版已有第三方软件包。若希望将你的发行版加入列表，请提交 PR。这些软件包由社区成员好心维护，作者不对其承担个人责任。
### Alpine Linux
[keyd](https://pkgs.alpinelinux.org/packages?name=keyd) package maintained by [@jirutka](https://github.com/jirutka).
[keyd](https://pkgs.alpinelinux.org/packages?name=keyd) 软件包由 [@jirutka](https://github.com/jirutka). 维护。
### Arch
[Arch Linux](https://archlinux.org/packages/extra/x86_64/keyd/) package maintained by Arch packagers.
[Arch Linux](https://archlinux.org/packages/extra/x86_64/keyd/) 软件包由 Arch 打包者维护。
### Debian
A keyd package is available in Debian 13 ("trixie") and later. To install:
Debian 13（"trixie"）及更高版本提供 keyd 软件包。安装方法：
```shell
sudo apt install keyd
@@ -179,36 +169,36 @@ sudo apt install keyd
### Fedora
[COPR](https://copr.fedorainfracloud.org/coprs/alternateved/keyd/) package maintained by [@alternateved](https://github.com/alternateved).
[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) package maintained by [jack@pngu.org](mailto:jack@pngu.org).
[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) package maintained by [@bubbleguuum](https://github.com/bubbleguuum).
[opensuse](https://software.opensuse.org//download.html?project=hardware&package=keyd) 软件包由 [@bubbleguuum](https://github.com/bubbleguuum). 维护。
Easy install with `sudo zypper in keyd`.
可使用 `sudo zypper in keyd` 轻松安装。
### Ubuntu
A keyd package is available in Ubuntu 25.04 ("plucky") and later. To install:
Ubuntu 25.04（"plucky"）及更高版本提供 keyd 软件包。安装方法：
```shell
sudo apt install keyd
```
In addition, the latest Debian package backported to various Ubuntu releases can
be found in the [`ppa:keyd-team/ppa`
此外，可将最新 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) package maintained by [@Barbaross](https://gitlab.com/Barbaross).
[xbps](https://github.com/void-linux/void-packages/tree/master/srcpkgs/keyd) 软件包由 [@Barbaross](https://gitlab.com/Barbaross). 维护。
Easy install with `sudo xbps-install -Su keyd`.
可使用 `sudo xbps-install -Su keyd` 轻松安装。
# Example 1
# 示例 1
[ids]
@@ -225,10 +215,10 @@ Easy install with `sudo xbps-install -Su keyd`.
f = /
...
# Example 2
# 示例 2
This overrides specific alt combinations macOS users might
be more familiar with, while keeping the rest intact.
这会覆盖 macOS 用户可能更熟悉的一些特定 Alt 组合键，
同时保持其余映射不变。
[ids]
*
@@ -244,11 +234,10 @@ be more familiar with, while keeping the rest intact.
r = C-r
z = C-z
# Recommended config
# 推荐配置
Many users will probably not be interested in taking full advantage of keyd.
For those who seek simple quality of life improvements I can recommend the
following config:
许多用户可能并不想充分利用 keyd 的全部能力。
若你只想获得一些简单的生活质量改进，我推荐以下配置：
[ids]
@@ -266,26 +255,20 @@ following config:
capslock = overload(control, esc)
insert = S-insert
This overloads the capslock key to function as both escape (when tapped) and
control (when held) and remaps all modifiers to 'oneshot' keys. Thus to produce
the letter A you can now simply tap shift and then a instead of having to hold
it. Finally it remaps insert to S-insert (paste on X11).
该配置将 capslock 过载为：轻按作 escape，按住作 control；
并将所有修饰键重映射为 "oneshot" 键。因此，要输入字母 A，
你现在可以轻按 shift 再按 a，而不必一直按住 shift。
最后，它将 insert 重映射为 S-insert（在 X11 上用于粘贴）。
# FAQS
# 常见问题
## Why is my trackpad is interfering with input after enabling keyd?
## 启用 keyd 后，触控板为何会干扰输入？
libinput, a higher level input component used by most wayland and X11 setups,
includes a feature called 'disable-while-typing' that disables the trackpad
when typing.
libinput 是大多数 Wayland 和 X11 环境使用的高级输入组件，其中包含一项称为「打字时禁用」（disable-while-typing）的功能，可在打字时禁用触控板。
In order to achieve this, it needs to distinguish between internal and external
keyboards, which it does by hard coding a rules for specific hardware
('quirks'). Since keyd creates a virtual device which subsumes both external
and integrated keyboards, you will need to instruct libinput to regard the keyd
virtual device as internal.
为实现这一点，它需要区分内置键盘与外接键盘，其做法是为特定硬件硬编码规则（称为 quirks）。由于 keyd 会创建一个虚拟设备，该设备同时涵盖外接键盘与集成键盘，因此你需要让 libinput 将 keyd 虚拟设备视为内置设备。
This can be achieved by adding the following to `/etc/libinput/local-overrides.quirks` (which may need to be created):
可通过在 `/etc/libinput/local-overrides.quirks`（若不存在可能需要新建）中添加以下内容来实现：
```
[Serial Keyboards]
@@ -295,41 +278,23 @@ MatchName=keyd*keyboard
AttrKeyboardIntegration=internal
```
Credit to @mark-herbert42 and @canadaduane for the original solution.
感谢 @mark-herbert42 和 @canadaduane 提供的原始解决方案。
## What about xmodmap/setxkbmap/*?
## xmodmap/setxkbmap/* 呢？
xmodmap and friends are display server level tools with limited functionality.
keyd is a system level solution which implements advanced features like
layering and [oneshot](https://docs.qmk.fm/#/one_shot_keys)
modifiers. While some X tools offer similar functionality I am not aware of
anything that is as flexible as keyd.
xmodmap 及其同类工具是显示服务器（display server）层面的工具，功能有限。keyd 是系统级方案，可实现分层（layering）和 [oneshot](https://docs.qmk.fm/#/one_shot_keys) 修饰键等高级功能。虽然部分 X 工具提供类似功能，但据我所知，没有哪款能像 keyd 这样灵活。
## What about [kmonad](https://github.com/kmonad/kmonad)?
## [kmonad](https://github.com/kmonad/kmonad)? 呢？
keyd was written several years ago to allow me to easily experiment with
different layouts on my growing keyboard collection. At the time kmonad did not
exist and custom keyboard firmware like
[QMK](https://github.com/qmk/qmk_firmware) (which inspired keyd) was the only
way to get comparable features. I became aware of kmonad after having published
keyd. While kmonad is a fine project with similar goals, it takes a different
approach and has a different design philosophy.
keyd 编写于数年前，目的是让我能在我不断扩充的键盘收藏上轻松试验不同布局。当时 kmonad 尚不存在，而像 [QMK](https://github.com/qmk/qmk_firmware)（启发 keyd 的自定义键盘固件）这类方案，是获得可比功能的唯一途径。发布 keyd 之后我才了解到 kmonad。kmonad 是一个目标相近的优秀项目，但采用了不同思路，设计哲学也不同。
Notably keyd was written entirely in C with performance and simplicitly in
mind and will likely never be as configurable as kmonad (which is extensible
in Haskell). Having said that, it supplies (in the author's opinion) the
most valuable features in less than 2000 lines of C while providing
a simple language agnostic config format.
值得注意的是，keyd 完全用 C 编写，兼顾性能与简洁，很可能永远不会像 kmonad（可用 Haskell 扩展）那样可配置。话虽如此，在作者看来，它在不到 2000 行 C 代码内提供了最有价值的功能，并附带一种与语言无关的简单配置格式。
## Why doesn't keyd implement feature X?
## 为什么 keyd 不实现功能 X？
If you feel something is missing or find a bug you are welcome to file an issue
on github. keyd has a minimalist (but sane) design philosophy which
intentionally omits certain features (e.g execing arbitrary executables
as root). Things which already exist in custom keyboard firmware like QMK are
good candidates for inclusion.
如果你觉得缺少某些功能或发现了 bug，欢迎在 GitHub 上提交 issue。keyd 秉持极简（但合理）的设计哲学，有意省略某些功能（例如以 root 身份执行任意可执行文件）。像 QMK 这类自定义键盘固件中已有的功能，是较好的纳入候选。
# Contributing
# 贡献
See [CONTRIBUTING](CONTRIBUTING.md).
IRC Channel: #keyd on oftc
请参阅 [CONTRIBUTING](CONTRIBUTING.md)。
IRC 频道：oftc 上的 #keyd