SHORTCUTS.md

快捷键速查

注：项目仍处于早期开发阶段，本文档可能与代码存在一定程度的滞后；如有不一致，以代码与实际运行行为为准。

本文件汇总紫霞输入法当前在 IMK 层处理的所有键位与快捷键。功能背景与设计动机参见 FEATURE.md，本文件只承担「按键到行为」的索引职责。

1. 基础提交与编辑

按键	触发条件	行为
Space	缓冲区有候选	提交活跃候选（默认首位，可由活跃候选切换键移动）。
Space	缓冲区无候选	直接输出半角空格。
Space	已翻页（pageOffset > 0）	视作选择当前页第一项，等价于 1。
Enter	缓冲区非空	不走候选，直接提交原始拼音 / 文本。
Esc	缓冲区非空	清空整个缓冲区并重置引擎状态，不向宿主写出任何内容。
Backspace	缓冲区非空	退格一位；空缓冲区时事件回交系统。

2. 候选选取

按键	触发条件	行为
1–9	候选窗有候选	选择当前页第 N 项并提交。
Tab / Shift+Tab	缓冲区含拼音段	进入段聚焦模式，依次切换聚焦段。聚焦段独享候选列表。
< / >（即 Shift+, / Shift+.）	候选窗有候选	候选窗翻页。
< / >	无候选	输出全角书名号「《》」。

3. 活跃候选切换（以词定字相关）

活跃候选指当前候选栏中被高亮的项，是 [ ] 取字、Space 提交的目标。

按键	触发条件	行为
← / →	候选窗有候选	把活跃候选向前 / 向后移动一项。无候选时事件回交系统，光标行为不变。
⌘⇧[ / ⌘⇧]	候选窗有候选	同上。沿用 macOS tab/page 切换的肌肉记忆，手不离开 bracket 区。
Shift+1–Shift+9	候选窗第 N 项存在	把当前页第 N 项设为活跃候选（不提交）。位数越界则不消费事件，保留 !@#$ 等标点输入。
[	缓冲区有活跃候选	取活跃候选首字作为已确认字符。整词消耗参见 FEATURE.md §2。
]	缓冲区有活跃候选	取活跃候选末字。

中英混合输入下（缓冲区含字面块，参见 FEATURE.md §12），[ 与 ] 始终作用于首个拼音段：整段拼音一次性消耗，前置字面块同时作为已确认段并入预编辑文本；若处理后缓冲区不再含拼音段，预编辑文本与剩余字面块按边界空格规则整体提交。

4. 模式切换

按键	触发条件	行为
Shift 单击	无活跃候选、无组合修饰键	在中文与英文直通模式之间切换。光标附近显示「中」或「EN」指示。
i	缓冲区为空或处于段落边界	切换中文 ↔ 临时日文模式。日文输入提交后自动回到中文。

Shift 单击需在 0.3 秒内完成；与其他键同时按下视为组合键，不触发切换。每次激活紫霞输入法时英文模式自动重置为关闭。

5. 标点

按键	触发条件	行为
, . ; : ? ! \ ( ) { } < > " ~ $ ^ _ `	任意	若缓冲区有候选则先提交首选，再附加对应全角标点一并送出；缓冲区空时直接输出全角标点。
'	缓冲区中已存在拼音	充当音节分隔符（如 xi'an 强制切「西安」）。
'	缓冲区无拼音	当作标点提交。
0	缓冲区非空	作为字母追加进缓冲区，用于自定义短语名（如 xl0）。
0	缓冲区为空	事件回交系统，正常输入数字 0。

6. Pin / Unpin 候选

Pin 把候选写入 user 层 pinned 配置文件（字写 pinned_chars.toml、词写 pinned_words.toml），跨进程持久化。守卫通过后操作针对当前活跃组合的拼音键。

按键	触发条件	行为
⌃⇧1–⌃⇧9	候选窗第 N 项存在且在可 pin 上下文	将该候选 pin 到 user 层队首；已存在则上移。
⌃⌥1–⌃⌥9	候选窗第 N 项存在且在可 pin 上下文	与 ⌃⇧<digit> 等价，作为备用组合。
⇧⌘D / ⇧⌃D	候选窗有候选且当前活跃候选位于可 pin 上下文	把当前活跃候选 pin 到 user 层队首，无须指定数字。
⌃⇧⌥1–⌃⇧⌥9	候选窗第 N 项存在	把该候选从 user 层移除。sys 层条目不受影响。

⌃⌥<digit> 作为 ⌃⇧<digit> 的备用组合存在，用于规避 Telegram、WezTerm 等已绑定 ⌃⇧<digit> 的宿主应用。⇧⌘D 与 ⇧⌃D 并行绑定，原因是不带 Shift 的 ⌘D 与 ⌃D 通常被宿主应用消费，加上 Shift 后才会按惯例转发给输入法。

避开了 ⌃⇧⌘<digit>，因其与 macOS 截图快捷键冲突。

中英混合输入下（参见 FEATURE.md §12），Pin 仅对首个拼音段的备选读法生效；整句候选（位置 1）与字面块条目无单一拼音键，不可 pin。

7. 开发与诊断

按键	触发条件	行为
⌃⇧⌘D	任意	循环切换中文词库变体：ice → ice+ → frost → frost+ → ice。光标附近短时显示新变体名。选择写入 UserDefaults（键名 zhDictVariant），下次进程启动自动恢复。
⌃⇧⌘/	缓冲区有活跃组合且 glitch marker 已启用	把当前 rawPinyin、候选列表、Conversion 路径写入 glitch 日志，用于回归收集。

8. 守卫与回交规则

• 凡按下 Control / Option / Command 中任意一项的事件，除上述显式分支外一律不消费，事件回交系统，避免吞掉 ⌘V ⌘C 等系统快捷键。
• 纯 Shift 修饰允许通过守卫，使翻页 < >、Shift+1..9、Shift 切换大写字母等都能正常工作。
• 数字键的 keyCode 直接读自 USB HID 物理位置码，与键盘布局（QWERTY / Dvorak / AZERTY）无关。

9. 配置文件参考

• 用户固顶字：~/Library/Application Support/LaplaceIME/pinned_chars.toml
• 用户固顶词：~/Library/Application Support/LaplaceIME/pinned_words.toml
• 自定义短语：~/Library/Application Support/LaplaceIME/custom_phrases.toml
• 用户词典：~/Library/Application Support/LaplaceIME/user_dict.sqlite
• Glitch 日志：~/Library/Application Support/LaplaceIME/glitch.jsonl（marker 启用后写入）