kanata

<h1 align="center">Kanata</h1> <h3 align="center"> <img alt="粉色调的带有字母K的键帽图像" title="Kanata" height="160" src="assets/kanata-icon.svg" /> </h3> <div align="center"> 提升您的键盘舒适度 </div>

这个工具有什么作用？

这是一个适用于Linux、macOS和Windows的跨平台软件键盘重映射工具。主要特性简述如下：

• 多层键功能
• 高级按键行为定制（如点按-长按、宏、Unicode）
• 跨平台人类可读配置文件

查看示例目录和在线模拟器。

要了解所有功能，请参阅配置指南。 配置指南旨在与主分支保持同步，可能包含您当前版本中没有的功能。 请查看发布页面中的相关链接。

最相似的项目是kmonad，它是kanata的灵感来源。这里有一份比较文档。

您可以在这里查看已知问题列表。

演示视频

多层功能展示（30秒，1.7 MB）。

为什么这个工具有用？

想象一下，如果我们不用按Shift键来输入大写字母，而是使用巨大的键盘，上面有单独的小写和大写字母键。我希望我们都能同意：那将是一个糟糕的用户体验！

我们可以这样理解Shift键的工作原理：它将您的输入切换到另一个功能层，在那里您可以输入大写字母和符号，而不是小写字母和数字。

kanata允许您将这种Shift键具有的替代层概念应用到任何键上。然后，您可以自定义这些层的功能，以满足您的确切需求和工作流程。

使用方法

目前运行kanata不会将其启动为后台进程。 您需要保持启动kanata的窗口运行以保持kanata处于活动状态。 以下是在后台运行kanata的一些提示：

• Windows：https://github.com/jtroo/kanata/discussions/193
• Linux：https://github.com/jtroo/kanata/discussions/130
• 从系统托盘图标运行：kanata-tray

预构建可执行文件

请查看发布页面获取可执行文件和说明。

自行构建

本项目使用最新的Rust稳定工具链。如果您使用rustup安装了Rust工具链，例如按照官方网站的说明进行安装，您可以通过rustup update stable获取最新的稳定工具链。

<details> <summary>说明</summary>

使用cargo install：

cargo install kanata

# 在Linux和macOS上，如果没有`sudo`可能无法运行，请参见下文
kanata --cfg <您的配置文件>

在Linux上构建和运行：

git clone https://github.com/jtroo/kanata && cd kanata
cargo build   # 可选择添加--release，性能并不是特别敏感

# 使用sudo是因为kanata需要打开/dev/文件
#
# 如果您想避免使用sudo，请参见：
# https://github.com/jtroo/kanata/wiki/Avoid-using-sudo-on-Linux
sudo target/debug/kanata --cfg <您的配置文件>

在Windows上构建和运行：

git clone https://github.com/jtroo/kanata; cd kanata
cargo build   # 可选择添加--release，性能并不是特别敏感
target\debug\kanata --cfg <您的配置文件>

在macOS上构建和运行：

对于macOS 11及更新版本：安装Karabiner VirtualHiDDevice驱动程序。

激活它：

/Applications/.Karabiner-VirtualHIDDevice-Manager.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Manager activate

对于macOS 10及更早版本： 安装Karabiner内核扩展。

git clone https://github.com/jtroo/kanata && cd kanata
cargo build   # 可选择添加--release，性能并不是特别敏感

# 需要sudo来获取拦截键盘的权限

sudo target/debug/kanata --cfg <您的配置文件>

完整的配置指南在这里。

示例配置文件位于cfg_samples目录中。simple.kbd文件包含一个基本的配置文件，希望易于理解，但不包含所有功能。kanata.kbd包含所有功能的示例及文档。发布资产中也有一个kanata.kbd文件，经过测试可与该版本一起使用。所有键名可以在keys模块中找到，您也可以定义自己的键名。

</details>

功能标志

无论是自行构建还是使用cargo install， 您都可以添加功能标志来 启用默认关闭的功能。

<details> <summary>说明</summary>

如果您想启用cmd操作， 添加标志--features cmd。 例如：

cargo build --release --features cmd
cargo install --features cmd

在Windows上， 如果您想编译使用Interception驱动程序的二进制文件， 您应该添加标志--features interception_driver。 例如：

cargo build --release --features interception_driver
cargo install --features interception_driver

要组合多个标志， 使用单个--features标志， 并用逗号分隔功能。 例如：

cargo build --release --features cmd,interception_driver
cargo install --features cmd,interception_driver

</details>

其他安装方法

主要特性

• 人类可读的配置文件。
  • 最小示例
  • 完整指南
  • 带解释的简单示例
  • 所有功能展示
• 配置文件的实时重新加载，方便测试您的更改。
• 多层键功能
• 高级操作，如点按-长按、Unicode输出、动态和静态宏
• 类似Vim的前导序列执行其他操作
• 可选运行TCP服务器与其他程序交互
  • 其他程序可以响应层变化或触发层变化
• Interception驱动程序支持（使用kanata_wintercept.exe）
  • 请注意存在这个问题，这超出了本项目的控制范围： https://github.com/oblitum/Interception/issues/25

贡献

欢迎贡献！

除非另有明确说明，否则您对kanata的贡献将根据LGPL-3.0-only[*]许可进行。

一些目录是例外：

• keyberon：MIT许可
• interception：MIT或Apache-2.0许可

这里有一份kanata的基本低努力设计文档

[*]：https://www.gnu.org/licenses/identify-licenses-clearly.html

您如何提供帮助

• 尝试使用并告诉我您的想法。随时提出问题或开始讨论。
• 可用性问题和无帮助的错误消息被视为应修复的错误。如果您遇到任何此类问题，我将感谢您提出问题。
• 浏览未解决的问题，如果您能够和/或愿意，请提供帮助。如果您想尝试贡献，随时ping jtroo获取一些指导。
• 如果您了解如何为Windows编写键盘驱动程序，开始一个开源的Interception驱动程序替代品将会很棒。

与kanata相关的社区项目

• vscode-kanata：VS Code中的kanata配置文件语言支持
• komokana：为komorebi提供自动应用程序感知层切换（Windows）
• kanata-tray：从系统托盘图标控制kanata
• 应用程序感知层切换：
  • qanata（Linux）
  • kanawin（Windows）
  • window_tools（Windows）

这个名字是什么意思？

我选择了一个"k"开头的单词，因为这与键盘有关。根据维基百科，kanata是一个土著伊洛魁语单词，意思是"村庄"或"定居点"，也是加拿大名称的起源。

还有PPT✧。

动机

简而言之：拥有QMK功能，但适用于任何键盘，不仅限于fancy的机械键盘。

<details> <summary>详细版本</summary>

我有几个运行QMK的键盘。QMK允许用户根据自己的喜好自定义键盘功能。

QMK的一个很好的用例是它能够将按键映射到与主行重叠但可在另一层访问的位置。我不评论生产力，但我发现这极大地提高了我的键盘舒适度。

例如，这些键位于键盘的右侧：

7 8 9
u i o
j k l
m , .

在一层上我有相同位置的方向键，在另一层上我有一个数字键盘。

方向键：       数字键盘：
- - -         7 8 9
- ↑ -         4 5 6
← ↓ →         1 2 3
- - -         0 * .

人们可以添加任意多的自定义设置来提高舒适度、速度等。就我个人而言，我的主要动机是舒适度，因为我过去有过重复性劳损。

然而，QMK并不是随处可用。事实上，它在大多数你能得到的硬件上都无法运行。你无法在笔记本电脑键盘或任何主流办公键盘上运行它。我认为QMK提供的舒适度和赋能应该对任何拥有电脑的人在他们现有的硬件上都可用，而不是必须购买一个爱好者机械键盘（诚然，这些键盘非常好——我拥有几个——但可能会很昂贵）。

我发现对于不运行QMK的键盘，最好的替代解决方案是kmonad。这是一个优秀的项目，如果你想尝试类似的东西，我推荐它。

这个项目存在的原因是kmonad是用Haskell编写的，而我不知道如何开始为Haskell项目做贡献。从局外人的角度来看，我认为Haskell是一种很棒的语言，但我真的无法理解它。而且在撰写本文时，还有一些未解决的问题使kmonad对我的个人工作流程来说并不是最优的。

这个项目是用Rust编写的，因为Rust是我最喜欢的编程语言，而且存在优秀的keyberon crate的先前工作。

</details>

类似项目

• kmonad：kanata的灵感来源（Linux、Windows、Mac）
• QMK：开源键盘固件
• keyberon：用于键盘固件的Rust #[no_std]库
• ktrl：仅限Linux的键盘自定义工具，具有层、TCP服务器和音频支持
• kbremap：仅限Windows的键盘自定义工具，具有层和unicode支持
• xcape：仅限Linux的点按保持修饰键
• karabiner-elements：仅限Mac的键盘自定义工具
• capsicain：仅限Windows的键位重映射工具，具有驱动级按键拦截
• keyd：仅限Linux的键位重映射工具，与QMK、kmonad和kanata非常相似
• xremap：仅限Linux的应用感知键位重映射工具，更多受Emacs键序列而非QMK层/Vim模式启发
• keymapper：上下文感知的跨平台键位重映射工具，具有不同的转换模型（Linux、Windows、Mac）

为什么列出这些项目？

虽然kanata对某些人来说是最好的工具，但它可能不是最适合你的工具。我很乐意向你介绍可能更适合你需求的工具。这个列表也可以作为参考/灵感，用于添加到kanata中的功能。

捐赠/支持？

作者（jtroo）不接受对kanata工作的金钱捐赠。请将你的时间和/或金钱捐赠给慈善机构。

以下是一些链接。这些链接仅供学习和作为有趣的阅读材料。它们不是背书。

• https://www.effectivealtruism.org/
• https://www.givewell.org/