defcfg 选项

危险启用 cmd

此选项可用于在您的配置中启用 cmd 操作。 cmd 操作允许 kanata 执行带有传递给它们的参数的程序。

这需要使用在启用 cmd 操作的情况下编译的 kanata 程序。这样做的原因是，如果您选择这样做，即使您从互联网上下载一些随机配置，kanata 也无法执行任意程序。

默认情况下禁用此配置，可以通过为其指定值 yes 来启用它。

例子：

(defcfg
  danger-enable-cmd yes
)

序列超时

该选项自定义按键序列超时（单位：ms）。它的默认值为 1000。此项的用途在序列中进行了解释。

例子：

(defcfg
  sequence-timeout 2000
)

序列输入模式

该选项自定义按键顺序输入模式。未配置时其默认值为隐藏抑制。

选项有：

可见退格：在输入时键入序列字符。键入的字符将用退格键删除，以实现有效的序列终止。
隐藏抑制：隐藏键入的序列字符。不输出无效序列终止的隐藏字符。
hide-delay-type：隐藏键入的序列字符。在超时后或键入非序列键后输出无效序列终止的隐藏字符。

对于可见退格和隐藏延迟类型，如果序列已经处于活动状态，则序列引导输入将被忽略。由于历史原因，并且如果这是所需的行为，使用隐藏抑制的序列引导输入将重置按键序列。

有关序列的更多信息，请参阅序列。

例子：

(defcfg
  sequence-input-mode visible-backspaced
)

序列-回溯-modcancel

此选项可自定义使用修饰符时按键序列的行为。默认值为 yes，如果需要，可以将其覆盖为 no。

设置为 yes 可以在下面的配置中同时激活 fk1 和 fk2，但是如果设置为 no，则 fk1 将无法激活

(defseq
  fk1 (lsft a b)
  fk2 (S-(c d))
)

有关序列的更多信息，请参阅序列，有关此特定配置的更多上下文，请参阅本文档。

例子：

(defcfg
  sequence-backtrack-modcancel no
)

日志层更改

默认情况下，kanata 将记录图层更改。然而，日志记录有一些处理开销。如果您不关心日志记录，可以选择禁用它。

例子：

(defcfg
  log-layer-changes no
)

如果 --log-layer-changes 作为命令行参数传递，则配置文件中的 no 将被覆盖，并且将再次记录层更改。当测试新的配置更改时，此标志很有用，同时保持默认行为“无日志记录”以节省处理时间，以便在试验与稳定使用时不需要来回调整 defcfg 项。

委托给第一层

默认情况下，当在由层切换激活的层上找到时，层上的透明键将委托给相应的 defsrc 键。

此配置条目更改行为以委托给配置中定义的第一层上相同位置的操作，该层是启动时的活动层。

有关更多上下文，请参阅#435。

例子：

(defcfg
  delegate-to-first-layer yes
)

移动鼠标继承加速状态

默认情况下，movemouse-accel 操作将分别跟踪垂直轴和水平轴的加速状态。

启用此设置后，movemouse-accel 的行为将与 QMK 中的鼠标移动完全相同，即，如果其他鼠标移动操作已被按下，则将继承新鼠标移动操作的加速状态。

例子：

(defcfg
  movemouse-inherit-accel-state yes
)

移动鼠标-平滑对角线

默认情况下，鼠标移动一次向一个方向移动，垂直/水平移动使用独立的计时器。

在某些应用程序中绘制线条时，这可能会导致对角线不平滑。此选项会增加少量难以察觉的延迟来同步鼠标移动。

例子：

(defcfg
  movemouse-smooth-diagonals yes
)

动态宏最大压力

此配置允许您自定义动态宏的长度限制。默认长度限制为 128 个键。

例子：

(defcfg
  dynamic-macro-max-presses 1000
)

并发点击保持

此配置使得在接近时间激活的多个点击保持操作的超时时间更快。默认情况下此功能被禁用。禁用后，下一次点击保持的超时将从上一次点击保持到期后的 0 毫秒开始。启用后，一旦按下点击保持操作，即使先前的点击保持操作仍保持且尚未过期，超时也会立即开始。

例子：

(defcfg
  concurrent-tap-hold yes
)

块未映射键

如果您只想使用键盘的子集，则可以使用 block-unmapped-keys 使除 defsrc 中存在的键以外的每个键都成为无操作。


笔记	仅当您还将 process-unmapped-keys 设置为 yes 时，此功能才能正确运行。

例子：

(defcfg
  block-unmapped-keys yes
)

快速事件延迟

此配置适用于以下事件：

释放一键激活
在点击保持激活中释放点击的按键
由于另一个键的中断而导致的非急切的踢踏舞激活
输入激活和弦，v1 和 v2

按键事件处理暂停定义的毫秒数（大约）。默认值为 5。

在上述场景中，输入延迟会受到轻微影响。由于 200 Hz 刷新率下 5 毫秒为 1 帧，因此在大多数情况下这不会被察觉。

存在此配置的原因是某些环境由于关键事件的快速性而无法正确处理场景。 Kanata 确实以正确的顺序发送事件，因此故障更多地出在环境中，但 kanata 无论如何都提供了解决方法。

如果您受到这些事件的延迟增加的负面影响，并且您的环境未受到速度增加的影响，则可以将该值减少到 0 到 4 之间的数字。

例子：

(defcfg
  ;; If your environment is particularly buggy, might need to delay even more
  rapid-event-delay 20
)

和弦-v2-最小空闲

此配置会影响计时器，在此期间和弦处理将被禁用。注意：有关详细信息，请参阅输入和弦/组合 (v2)。

默认（也是最小值）值为 5，单位为毫秒。

例子：

(defcfg
  chords-v2-min-idle 200
)

激活时覆盖释放

此配置项更改 deoverrides 的激活行为。

以覆盖这个例子为例：

(defoverrides (lsft a) (lsft 9))

默认行为是，如果 lsft 在释放 a 之前被释放，kanata 的行为将是发送 a。

未来的改进可能是让 9 继续成为关键，但目前尚未实施。

如果上述行为对您的工作流程产生负面影响，解决方法是启用此配置。一旦覆盖激活，此配置将按下并立即释放 9 输出，这意味着作为人类，您不太可能首先释放 lsft。

此配置的效果是，当被覆盖激活时，9 键无法保持按住状态，这对于您的用例来说很重要。

例子：

(defcfg
  override-release-on-activation yes
)

允许硬件重复

默认情况下，物理键盘（或操作系统）生成的任何重复键事件都将传递到应用程序。在 Linux 上，在 Wayland 下，这是浪费精力，因为 DE 自己处理按键重复。在使用 evtest 等调试配置时，此类事件也可能会分散注意力。

将此选项设置为“false”将导致此类事件被丢弃，并且不会被传递。这主要适用于 Linux，但也可能在 Mac 上找到一些用处。它没有在 Windows 上实现，并且会被默默地忽略。

例子：

(defcfg
   allow-hardware-repeat false
)

负载触发别名

选择首次启动时以及每次实时重新加载配置后要执行的别名。您可以使用它来运行外部命令，或堆叠层（使用保持层）。

不带前导“@”的别名名称应作为参数。下面的示例将在启动时发出蜂鸣声（假设您的系统有蜂鸣声命令），并且已经阻止了交换的“i”和“o”键。

例子：

(defcfg
  alias-to-trigger-on-load S
  danger-enable-cmd yes
)

(deffakekeys B (layer-while-held block))

(defalias
  P (on-press toggle-vkey B)
  S (macro @P (cmd beep))
)

(defsrc i o p )
(deflayer base o i @P )
(deflayer block • • _ )

使用多个 defcfg 选项

defcfg 条目被视为具有字符串对的列表。例如：

(defcfg a 1 b 2)

这将被视为具有值 1 的配置 a 和具有值 2 的配置 b。

下面显示了包含许多选项的 defcfg 示例。应该注意的是，在不适用的操作系统上使用时，仅 Linux、仅 Windows 或仅 macOS 的选项将被忽略。

;; Don't actually use this exact configuration,
;; it's almost certainly not what you want.
(defcfg
  process-unmapped-keys yes
  danger-enable-cmd yes
  sequence-timeout 2000
  sequence-input-mode visible-backspaced
  sequence-backtrack-modcancel no
  log-layer-changes no
  delegate-to-first-layer yes
  movemouse-inherit-accel-state yes
  movemouse-smooth-diagonals yes
  dynamic-macro-max-presses 1000
  linux-dev (/dev/input/dev1 /dev/input/dev2)
  linux-dev-names-include ("Name 1" "Name 2")
  linux-dev-names-exclude ("Name 3" "Name 4")
  linux-continue-if-no-devs-found yes
  linux-unicode-u-code v
  linux-unicode-termination space
  linux-x11-repeat-delay-rate 400,50
  windows-altgr add-lctl-release
  windows-interception-mouse-hwid "70, 0, 60, 0"
)

defcfg - 仅限 Linux

仅限 Linux：linux-dev

默认情况下，kanata 会尝试检测哪些输入设备是键盘并尝试拦截它们。但是，您可以使用 linux-dev 配置从 /dev/input 目录指定确切的键盘设备。

例子：

(defcfg
  linux-dev /dev/input/by-path/platform-i8042-serio-0-event-kbd
)

如果要指定多个键盘，可以用冒号 : 分隔路径。

例子：

(defcfg
  linux-dev /dev/input/dev1:/dev/input/dev2
)

由于使用冒号分隔设备，如果您的设备文件名中包含冒号，则必须使用反斜杠转义这些冒号：

(defcfg
  linux-dev /dev/input/path-to\:device
)

或者，您可以使用列表语法，其中反斜杠和冒号都按字面解析。列表项由空格或换行符分隔。对每个项目使用引号是可选的，并且仅当项目包含空格时才需要。

(defcfg
  linux-dev (
    /dev/input/path:to:device
    "/dev/input/path to device"
  )
)

仅限 Linux：linux-dev-names-include

如果省略 linux-dev，则此选项定义应包含的设备名称列表。列表中不存在的设备名称将被忽略。该选项的解析方式与 linux-dev 相同。

Kanata 将在启动时打印设备名称，日志行如下所示：

registering /dev/input/eventX: "Name goes here"

例子：

(defcfg
  linux-dev-names-include (
    "Device name 1"
    "Device name 2"
  )
)

仅限 Linux：linux-dev-names-exclude

如果省略 linux-dev，则此选项定义应排除的设备名称列表。该选项的解析方式与 linux-dev 相同。

linux-dev-names-include 和 linux-dev-names-exclude 选项并不相互排斥，但实际上，可能只使用其中之一才有意义，而不是同时使用两者。

例子：

(defcfg
  linux-dev-names-exclude (
    "Device Name 1"
    "Device Name 2"
  )
)

仅限 Linux：linux-continue-if-no-devs-found

默认情况下，如果找不到输入设备，kanata 将崩溃。您可以通过设置 linux-continue-if-no-devs-found 来更改此行为。

例子：

(defcfg
  linux-continue-if-no-devs-found yes
)

仅限 Linux：linux-device-detect-mode

当没有使用任何显式设备配置时，Linux 上的 Kanata 会自动检测并获取输入设备。如果 kanata 意外地抓取类似鼠标的设备，您可以使用配置项来更改检测行为。

配置是 linux-device-detect-mode ，它有以下选项：


`仅键盘`	抓住看起来只有键盘的设备。
`键盘鼠标`	获取似乎只有键盘的设备以及声明键盘和鼠标功能的设备。
`任何`	抓住所有类似键盘和鼠标的设备。

默认行为是：


`键盘鼠标`	当 defsrc 中没有鼠标事件时。
`任何`	当任何鼠标按钮或鼠标滚动事件位于 defsrc 中时。

Linux 上的 Unicode 工作原理是按 Ctrl+Shift+U，输入 unicode 十六进制值，然后按 Enter。但是，如果您在用户空间中进行重新映射，例如通过 xmodmap/xkb，kanata 输出的键码“U”在用户空间重新映射后可能不会变成键符号“u”。如果您在 kanata 上使用非美国、非欧洲键盘，则可能会出现这种情况。为了使 unicode 工作，kanata 需要使用输出键符号“u”的键码，该键码可能不是键码“U”。

您可以使用 evtest 或 kanata --debug，设置用户空间键重新映射，然后按输出键符号“u”的键以查看发送的底层键码。然后你可以使用这个配置来改变 kanata 的行为。

例子：

(defcfg
  linux-unicode-u-code v
)

仅限 Linux：linux-unicode-termination

Linux 上的 Unicode 默认情况下以 Enter 键终止。这在某些应用程序中可能不起作用。终止可通过以下选项进行配置：

enter
space
enter-space
space-enter

例子：

(defcfg
  linux-unicode-termination space
)

仅限 Linux：linux-x11-repeat-delay-rate

在 Linux 上，您可以通过配置项 linux-only-x11-repeat-rate 告诉 kanata 在启动时和实时重新加载时运行 xset r rates <delay> <rate>。这需要两个用逗号分隔的数字。第一个数字是以毫秒为单位的延迟，第二个数字是以重复/秒为单位的重复率。

该配置项不影响 Wayland 或无桌面环境。

例子：

(defcfg
  linux-x11-repeat-delay-rate 400,50
)

仅限 Linux：linux-use-trackpoint-property

在 Linux 上，您可以要求 kanata 将自己标记为轨迹点。这对 libinput 有几个影响，包括启用鼠标中键滚动和使用不同的加速曲线。否则，被 kanata 拦截的轨迹点可能不会按预期运行。

如果使用此功能，建议仅使用 Linux：linux-dev-names-include、仅 Linux：linux-dev-names-exclude 或仅 Linux：linux-dev 过滤掉任何非轨迹点指向设备，以避免更改它们行为也是如此。

例子：

(defcfg
  linux-use-trackpoint-property yes
)

仅限 Linux：linux-output-device-bus-type

Linux 上的 Kanata 需要为其 evdev 输出设备声明“总线类型”。选项有 USB 和 I8042，默认为 I8042。使用 USB 可能会破坏在 Wayland 上打字时禁用触摸板的功能。但使用 I8042 似乎会破坏其他一些场景。因此，输出总线类型是可配置的。

例子：

(defcfg
   linux-output-device-bus-type USB
)

defcfg - 仅限 macOS

仅限 macOS：macos-dev-names-include

此选项定义应包含的设备名称列表。默认情况下，kanata 会尝试检测哪些输入设备是键盘并尝试拦截它们。但是，您可以使用 macos-dev-names-include 配置指定要拦截的确切键盘设备。列表中不存在的设备名称将被忽略。该选项的解析方式与 linux-dev 相同。

使用 kanata -l 或 kanata --list 列出可用的键盘。

例子：

(defcfg
  macos-dev-names-include (
    "Device name 1"
    "Device name 2"
  )
)

defcfg - 仅限 Windows

仅限 Windows：windows-altgr

如果您正在使用或 defsrc 中有该键，Windows 有一个选项可以缓解 AltGr (ralt) 的奇怪行为 process-unmapped-keys yes。这适用于许多非美国布局。您可以使用列出的值之一来更改 kanata 对该键的操作：

cancel-lctl-press
- 这将删除与 ralt 一起生成的 lctl press
add-lctl-release
- 这会在 ralt 释放时添加 lctl 释放

如果没有这些解决方法，您应该使用 process-unmapped-keys（除了 lctl ralt 之外的所有）），或者使用 process-unmapped-keys no 并从 defsrc 中省略 ralt 和 lctl。

例子：

(defcfg
  windows-altgr add-lctl-release
)

有关更多上下文，请参阅：#55。

Note

即使使用这些解决方法，将 lctl 和 ralt 放入 defsrc 中可能无法与也使用键盘拦截的其他应用程序正常工作。已知存在问题的应用程序：GWSL/VcXsrv

仅 Windows：windows-interception-mouse-hwid

此 defcfg 项允许您拦截特定鼠标设备的鼠标按钮。这只适用于拦截驱动程序（发布二进制文件的 -wintercept 变体）。

最初的用例是针对 Thinkpad 等笔记本电脑，这些笔记本电脑具有可能需要用来激活 kanata 操作的鼠标按钮。

要知道要在字符串中放入哪些数字，您可以使用用任何数字定义的 defcfg 项来运行变体。然后，当第一次按下鼠标设备上的按钮时，kanata 将在日志中打印其 hwid；然后您可以将其复制粘贴到此配置条目中。如果没有定义这个 defcfg 项，则不会打印日志。

Kanata 中的 Hwids 是 ASCII 硬件 id 串联的字节数组表示形式，可以在 Windows 上的设备管理器中看到。因此，它们是任意长度并且可以非常长。

仅限 Windows：windows-interception-mouse-hwids

该项目与上面记录的单一版本具有类似的用途，但它是一个允许拦截多个鼠标的字符串列表。

如果同时使用单数和列表项，则单数版本的行为就像添加到列表中一样。

例子：

(defcfg
  windows-interception-mouse-hwids (
    "70, 0, 60, 0"
    "71, 0, 62, 0"
  )
)

仅 Windows：windows-interception-keyboard-hwids

这个 defcfg 项允许您仅拦截特定的键盘。它的值必须是一个字符串列表，每个字符串代表一个硬件 ID。

要知道要在字符串中放入哪些数字，您可以运行该 defcfg 项为空的变体。然后，当第一次按下键盘上的按钮时，kanata 将在日志中打印其 hwid。然后，您可以将其复制粘贴到此配置条目中。如果没有定义这个 defcfg 项，则不会打印日志。

Kanata 中的 Hwids 是 ASCII 硬件 id 串联的字节数组表示形式，可以在 Windows 上的设备管理器中看到。因此，它们是任意长度并且可以非常长。

例子：

(defcfg
  windows-interception-keyboard-hwids (
    "70, 0, 60, 0"
    "71, 72, 73, 74"
  )
)

仅限 Windows：托盘图标

仅显示适用于 Windows 的自定义托盘图标文件：Windows 上支持 win-tray gui 的 kanata 版本。接受图标文件的完整路径（包括带扩展名的文件名）或仅接受文件名，然后在以下位置搜索该文件：

默认父文件夹：
- 配置文件、可执行文件
- 环境变量：XDG_CONFIG_HOME、APPDATA (C:\Users<名称>\AppData\Roaming)、USERPROFILE /.config (C:\Users<名称>.config)
默认配置子文件夹：kanata kanata-tray
默认图像子文件夹（可选）： icon img Icons
支持的图像文件格式： ico jpg jpeg png bmp dds tiff

如果未指定，则尝试从相同位置加载名称与配置名称匹配且扩展名替换为受支持的扩展名之一的任何图标文件。有关更多详细信息，请参阅示例配置。

例子：

;; in a config file C:\Users\<U>\AppData\Roaming\kanata\kanata.kbd
(defcfg
  tray-icon base.png ;; will load C:\Users\<U>\AppData\Roaming\kanata\base.png
)

没有文件链接到当前文件