Kanata键盘映射工具中的单次触发超时动作实现方案

背景介绍

Kanata是一款强大的键盘映射工具，它允许用户高度自定义键盘行为。在实际使用中，用户经常需要实现"单次触发"(one-shot)功能——即按下一个键后，它会临时改变键盘行为(如激活一个修饰键或层)，直到下一个键被按下或超时。

需求分析

用户oblitzitate提出了一个进阶需求：希望在单次触发超时后(即没有后续按键时)能够执行一个自定义动作。这种功能可以用于多种场景：

1. 实现"死人开关"(deadman's switch)：当用户手指离开特定键时触发安全操作
2. 提供触觉反馈：当单次修饰键超时释放时给出提示
3. 执行清理操作：当临时层超时后恢复默认配置

技术实现方案

基础方案：使用虚拟键和空闲事件

最简单的实现方式是结合虚拟键和on-idle事件：

(multi 
  (on-release tap-vkey some-one-shot-vkey) 
  (on-idle 1 tap-vkey some-cmd-vkey)
)

这种方案虽然简单，但不够精确，因为它会在空闲时无条件触发动作，而不管单次触发是否真的超时。

进阶方案：使用switch和输入历史

更精确的方案是利用switch表达式结合输入历史检查：

(defalias
  oneshot-timeout (switch
    ((key-timing oneshot-key 200) (cmd some-command))
    fallthrough
    (one-shot oneshot-key)
  )
)

这个方案通过key-timing检查按键持续时间，只有当单次触发键被按下超过200ms且没有后续按键时，才会执行超时命令。

完整实现：包含前置和后置动作

如果需要更完整的生命周期控制(前置动作+单次触发+超时后置动作)，可以使用以下结构：

(defalias
  full-cycle (multi
    (tap-hold-press 200 
      (cmd pre-action) 
      (one-shot the-key)
    )
    (on-idle 200 (cmd post-timeout-action))
  )
)

技术细节与注意事项

1. 时序控制：动作之间需要有适当的延迟，避免过早触发单次释放
2. 双击处理：需要考虑用户快速双击单次触发键时的特殊处理
3. 层传播：后置动作可能需要考虑当前激活的层状态
4. 性能影响：复杂的条件检查可能会增加输入延迟

实际应用建议

对于大多数用户，建议从简单的虚拟键方案开始，逐步过渡到更精确的switch方案。对于需要高度定制的场景，可以考虑结合tap-hold-press-timeout实现更复杂的生命周期控制。

Kanata的这种灵活性使其成为高级键盘定制领域的强大工具，通过巧妙的配置可以实现各种专业级的人机交互需求。