入门
入门
注释
您可以在配置文件中添加注释。注释以两个分号为前缀。例如：
;; This is a comment in a kanata configuration file.
;; Comments will be ignored and are intended for you to help understand your
;; own configuration when reading it later.您可以使用 #| 开始多行注释块并以 |# 结束：
#|
This is
a multi-line comment block
|#所需的配置条目
定义文件
参考
您的配置文件必须恰好有一个 defsrc 列表。这定义了 deflayer 条目将操作的键的顺序。
句法：
(defsrc $key1 $key2 ... $keyN)$键 | 键的名称。这可以是默认的键名，也可以是 deflocalkeys 中定义的键名。当物理按下该输入键时，将激活活动层上相同顺序位置处定义的动作。 |
描述
defsrc 配置条目定义了 kanata 将处理哪些按键输入以及按键如何映射到定义的图层。 Kanata 不会处理从 defsrc 中排除的密钥，除非您在 defcfg 中设置了 process-unmapped-keys yes。
Kanata 未处理的密钥会对各种操作产生影响。例如：
- 按下排除的键将键入一个字母，而之前的轻按决定仍悬而未决，从而可能导致不正确的结果。
- 排除的按键不会触发诸如敲击按住按下或踢踏舞之类的动作的早期激活
- 排除的键无法通过 fork 或 switch 逻辑读取。
defsrc 条目被视为长序列。空白的数量（空格、制表符、换行符）不相关。您可以使用空格、制表符或换行符，但您可以根据自己的喜好直观地格式化 defsrc。
所有键名称的主要来源是源中的 str_to_oscode 和 default_mappings 函数。如果您无法找到所需的密钥，欢迎提出问题。
包含 US QWERTY 键盘按键作为大约 60% 键盘布局的示例 defsrc：
例子：
(defsrc
grv 1 2 3 4 5 6 7 8 9 0 - = bspc
tab q w e r t y u i o p [ ] \
caps a s d f g h j k l ; ' ret
lsft z x c v b n m , . / rsft
lctl lmet lalt spc ralt rmet rctl
)请注意，某些键盘有菜单键而不是右元键。在这种情况下，您可以使用菜单代替 rmet。
对于非美国键盘，请参阅非美国键盘部分。
deflayer
参考
您的配置文件必须至少有一个 deflayer 条目。这定义了 defsrc 中映射的每个物理键在 kanata 运行时的行为方式。
句法：
(deflayer $layer-name $action1 $action2 ... $actionN)$图层名称 | 表示图层名称的字符串。该名称用于在其他操作中引用该图层。 |
$行动 | 当按下相应的 defsrc 输入键时，该层处于活动状态时激活的操作。 |
描述
deflayer 配置条目后面是层名称，然后是按键或操作列表。可用的键名与 defsrc 中的相同。本文档进一步解释了操作。空白的情况与 defsrc 相同。 deflayer 中按键/操作的顺序对应于 defsrc 中定义的相同序列位置中的物理按键。
配置文件中定义的第一层将是 kanata 运行时的起始层。其他层可以暂时激活或切换到使用操作。
将 QWERTY 重新映射到 Dvorak 布局的 defsrc 和 deflayer 示例如下：
例子：
(defsrc
grv 1 2 3 4 5 6 7 8 9 0 - = bspc
tab q w e r t y u i o p [ ] \
caps a s d f g h j k l ; ' ret
lsft z x c v b n m , . / rsft
lctl lmet lalt spc ralt rmet rctl
)
(deflayer dvorak
grv 1 2 3 4 5 6 7 8 9 0 [ ] bspc
tab ' , . p y f g c r l / = \
caps a o e u i d h t n s - ret
lsft ; q j k x b m w v z rsft
lctl lmet lalt spc ralt rmet rctl
)Windows 托盘菜单构建还允许在 deflayer 和 deflayermap 中指定图层图标，以在图层激活时显示在托盘菜单中，请参阅示例配置
deflayermap
参考
存在另一种定义图层的方法：deflayermap。此方法通过定义输入输出对将输入映射到操作，完全忽略 defsrc。
使用 deflayermap 时，您可能需要启用 process-unmapped-keys 或在 defsrc 中定义大部分键盘按键。否则，许多行为不会按预期进行。有关更多上下文，请参阅链接之一。
句法：
(deflayermap ($layer-name)
$input1 $action1
$input2 $action2
...
$inputN $actionN)$图层名称 | 表示图层名称的字符串。该名称用于在其他操作中引用该图层。 |
$输入 | 输入键映射到相应的输出。 |
$行动 | 当按下相应的输入键时，该层处于活动状态时激活的操作。 |
描述
当只需要映射层上的几个键时，deflayermap 变体具有配置更简洁的优点。在练习新配置时，标准 deflayer 的优点是看起来更像物理键盘布局，这可能对某些人有帮助。
在 deflayermap 中，第一项必须是图层名称。与 deflayer 不同，图层名称必须位于括号中。在层名称之后，层通过成对的项目进行配置：
- 输入键
- 输出动作
将 Caps Lock 映射到 Escape 的完整配置示例是：
;; defsrc is still necessary
(defsrc)
(deflayermap (base-layer)
caps esc)输入键与 defsrc 键具有相同的作用。输出操作承担普通 Deflayer 中的项目所具有的角色。
作为特殊输入名称，您可以使用 、_ 或 ___ 之一来映射图层中未显式映射的所有键，例如在上面的示例中，这些影响除大写之外的键。
_ | 映射 defsrc 中定义的该层中所有未映射的键。 |
__ | 映射该层中未在 defsrc 中定义的所有未映射键。 |
___ | 映射该层中所有未映射的键。 |
审查所需的配置条目
如果您按顺序阅读，您现在已经看到了所有必需的条目：
defsrcdeflayer
最小配置示例是：
(defsrc a b c)
(deflayer start 1 2 3)这将使 kanata 将您的 a b c 键重新映射为 1 2 3。这几乎肯定是不可取的，但却是有效的配置。
| 笔记 | 请仔细阅读已知的平台问题，因为它们可能会影响您应该在 defsrc 中包含/排除的内容。到目前为止，Windows LLHOOK I/O 机制存在的问题最多。 |
defsrc 和 deflayermap 的键名
所有默认键名称的真实来源是keys/mod.rs 文件中的函数str_to_oscode 和add_default_str_osc_mappings。
该在线工具也适用于大多数按键，可以告诉您按键名称。按下该键后，它将在网页中显示为 event.code 字段。
非美国键盘
对于非美式键盘用户，您的键盘上可能有一些键包含默认情况下 defsrc 中不允许的字符，至少根据物理键上显示的符号是这样。下面的两部分可以帮助您了解如何重新映射所有按键。
浏览器 event.code
确保 kanata 和其他键重新映射程序未运行。然后你就可以使用这个在线工具并按 键。 event.code 字段告诉您要在 Kanata 中使用的键名称。或者，您可以通读此参考资料。由于键名很长，如果使用这些键名重新映射，您可能需要使用 deflayermap。
| 重要的 | 在 Windows 上，根据浏览器 event.code 使用键名称时，应使用 kanata_winIOv2.exe 或 Interception。默认的kanata.exe不会根据浏览器event.code键名进行映射。 |
deflocalkeys OS系统配置
参考
您可以使用 deflocalkeys 定义可在 defsrc、deflayer 和配置中的其他任何位置使用的其他键名称。
句法：
(deflocalkeys-$variant
$key-name1 $key-number1
$key-name2 $key-number2
...
$key-nameN $key-numberN)$变体 | 其中之一： win winiov2 Wintercept linux macos |
$键名 | 您选择的键名称可以在配置的其余部分中使用。 |
$钥匙号码 | 关键数字根据您使用的 kanata 变体而变化。 |
每个 deflocalkeys-* 变体仅允许一个。不适用的变体将被忽略，例如使用默认的 Windows kanata.exe 二进制文件时，deflocalkeys-linux 和 deflocalkeys-wintercept 都会被忽略。
描述
deflocalkeys 配置并不是绝对必要的。它们的目的是帮助您将物理键盘的外观与您的 kanata 配置相匹配，希望它更具可读性并减少混乱。在底层硬件中，所有键盘位置根据其位置发送相同的扫描码，而不管键帽上打印的是什么。扫描码名称通常由相应的美国布局名称引用。操作系统的工作是根据配置的区域设置和布局将相同的扫描代码转换为正确的输出。
您可以在本文档中找到其他人所做的配置。如果您在那里没有看到键盘并且对使用可用工具没有信心，欢迎在讨论或问题中寻求帮助。如果可以的话，请为该文档做出贡献！
deflocalkeys 有五种变体：
deflocalkeys-windeflocalkeys-winiov2deflocalkeys-winterceptdeflocalkeys-linuxdeflocalkeys-macos
例子：
(deflocalkeys-win
ì 187
)
(deflocalkeys-winiov2
ì 187
)
(deflocalkeys-wintercept
ì 187
)
(deflocalkeys-linux
ì 13
)
(deflocalkeys-macos
ì 13
)
(defsrc
grv 1 2 3 4 5 6 7 8 9 0 - ì bspc
)用于自定义键的数字表示以 10 为基数的 OsCode 的转换值。这在 Windows 挂钩、Windows 拦截和 Linux 之间有所不同。
使用 --debug 标志运行 kanata 可以让您读取正确的数字，显示在 KeyEvent 日志行中代码的括号中。
也可以使用本机工具，如下所述。
在 Linux 中，evtest 将为您按下的物理键提供正确的数字。
在使用默认钩子机制的Windows中，kanata存储库中键盘测试器的非拦截版本将在代码：<number> 部分中给出正确的数字。 （预构建的二进制文件）
在 Windows uning winIOv2 中，winIOv2 可执行变体将在代码中给出正确的编号：<number> 部分。
在使用拦截的 Windows 中，键盘测试器的拦截版本将在 num: <number> 部分给出正确的数字。在钩子版本和拦截版本之间，某些键可能一致，而另一些则可能不一致；请注意它们不兼容！
然而，Interception 和 winIOv2 通常应该彼此一致。
欢迎提出改进该系统用户友好性的想法！如前所述，如果需要，请在问题或讨论中寻求帮助，并且非常欢迎有关本文档的帮助，以便将来的用户可以更轻松地度过。
defcfg简介
您的配置文件可能包含单个 defcfg 条目。 defcfg 可以为空或省略。有一些选项可以改变 kanata 的行为，但本介绍将仅介绍最流行的条目：process-unmapped-keys。所有其他选项可以在稍后的 defcfg 选项部分中找到。
空 defcfg 的示例：
(defcfg)处理未映射的键
defcfg 中的 process-unmapped-keys 选项可能是最有影响力的选项。启用此配置会使 kanata 处理 defsrc 中未定义的密钥。如果您只映射 defsrc 中的几个键而不是键盘上的大多数键，这可能很有用。
默认情况下，从 defsrc 中排除的键在各种情况下都不起作用。一些例子：
- 先前的轻击-按住-按下操作的早期保持将不会
- 之前的一击动作不会被公开
- 叉子和开关逻辑不会看到钥匙
默认情况下禁用此选项。默认情况下未启用此功能的原因是，如果某些按键被拦截，则可能无法正常工作。一个已知问题是 AltGr/ralt/Right Alt；仅限 Windows：windows-altgr。
例子：
(defcfg process-unmapped-keys yes)
(defcfg process-unmapped-keys (all-except lctl ralt))别名和变量
在了解操作之前，首先了解别名和变量会很有用。
别名
参考
使用 defalias 配置条目，您可以为操作引入快捷方式标签。
句法：
(defalias
$alias-name1 $action1
$alias-name2 $action2
...
$alias-nameN $actionN)$别名 | 为操作的快捷方式标签选择的名称。通过在名称前添加 @ 字符，可以在其余配置中使用它。 |
$行动 | 在引用别名的地方使用的输出操作。 |
描述
defalias 条目按顺序读取成对的项目，其中第一项是别名，第二项是它可以替换的操作。
列表是由空格分隔并由括号包围的字符串或嵌套列表的序列。到目前为止我们看到的所有配置条目都是列表； defalias 是我们在本指南中首先看到嵌套列表的地方。
例子：
(defalias
;; tap for caps lock, hold for left control
cap (tap-hold 200 200 caps lctl)
)该别名可以在 deflayer 中用作长动作的替代品。别名名称以 @ 为前缀，表示它是别名而不是普通键。
(deflayer example
@cap a s d f
)您可以有多个 defalias 条目以及单个 defalias 中的多个别名。别名还可以指之前在配置文件中定义的其他别名。
例子：
(defalias one (tap-hold 200 200 caps lctl))
(defalias two (tap-hold 200 200 esc lctl))
(defalias
three C-A-del ;; Ctrl+Alt+Del
four (tap-hold 200 200 @three ralt)
)您可以选择将操作放入 deflayer 中，而不将其别名化。然而，对于长时间的动作，建议不要这样做，以保持良好的视觉对齐。直观地对齐您的 deflayer 条目有望使您的配置文件更易于阅读。
例子：
(deflayer example
;; this is equivalent to the previous deflayer example
(tap-hold 200 200 caps lctl) a s d f
)变量
参考
使用 defvar 配置条目，您可以为任意字符串或列表引入快捷方式标签。
句法：
(defvar
$var-name1 $var-value1
$var-name2 $var-value2
...
$var-nameN $var-valueN)$var-name | 为操作的快捷方式标签选择的名称。通过在名称前添加 @ 字符，可以在其余配置中使用它。 |
$var-value | 无论何时使用变量，都将替换任意字符串或列表。可以通过在变量名前添加 $ 来使用变量。 |
描述
与别名不同，变量不需要是有效的独立操作。换句话说，变量可以用作动作的组件。
最常见的用例是为诸如“敲击保持”、“踢踏舞”和“一次性”等操作定义通用数字字符串。
与 defalias 的工作原理类似，defvar 读取序列中的项目对，其中该对中的第一项是变量名称，第二项是字符串或列表。变量可以引用先前定义的变量。
变量可用于替换大多数值。一些值得注意的例外是：
- 变量不能在 defcfg、defsrc 或 deflocalkeys 中使用
- 变量不能用来替代操作名称
变量通过在名称前加上 $ 前缀来引用。
例子：
(defvar
tap-timeout 100
hold-timeout 200
tt $tap-timeout
ht $hold-timeout
)
(defalias
th1 (tap-hold $tt $ht caps lctl)
th2 (tap-hold $tt $ht spc lsft)
)defvar 中的连接
在 defvar 的第二项中，以特殊关键字 concat 开头的列表会将列表中的所有后续项连接在一起形成单个字符串值。如果不使用 concat，列表将按原样保存。
例子：
(defvar
rootpath "/home/myuser/mysubdir"
;; $otherpath will be the string: /home/myuser/mysubdir/helloworld
otherpath (concat $rootpath "/helloworld")
)