# Vim 模式：按应用在 Esc 后切换英文

在 Vim 或启用 Vim 插件的编辑器中，中文输入完成后按 Esc，编辑器可以正常回到 normal 模式，但水杉仍停留在中文状态。可按应用启用 Vim 模式，让这次 Esc 同时将水杉切到英文，随后直接输入 `hjkl` 等命令。

在数据目录的 `config.toml`（默认 `%LOCALAPPDATA%\metasequoiaime\config.toml`，安装时若选了别的位置就在那里；`METASEQUOIA_IME_DATA_DIR` 环境变量优先）的 `[input]` 段填写要启用的应用：

```toml
[input]
# 可执行文件名，不填写路径；ASCII 大小写不敏感。
vim_mode_apps = ["Code.exe", "gvim.exe"]
```

出厂值是空列表，即默认关闭。这个键在出厂配置模板里，升级合并会保留你填写的值。

配置修改通常在下一次 Esc 时生效，文件检查间隔最长一秒，无需重新部署或重启编辑器。从列表中删除应用或改回 `[]` 即可关闭。列表格式无效（不是字符串数组、缺逗号、未闭合等）时整项视为关闭，保留现有按键行为。

行为约定：

- 保留现有的 Esc 处理及透传判定，只在 Esc 已决定交给应用时切换到水杉的英文状态。不会切换系统输入法。
- 未完成拼音或候选仍按现有逻辑由 Esc 取消；取消后重新按一次 Esc 才会切英文。长按 Esc 的重复事件不触发切换。
- 有待处理的异步按键时不抢先切换，避免改变队列中输入的含义。
- Shift/Ctrl/Alt/Win + Esc 不触发；进入 insert 模式时也不自动恢复中文。
- 只按宿主进程匹配；例如 VS Code 的所有窗口都属于 `Code.exe`，无法区分其中是否启用了 Vim 插件。终端内的 Vim 需要配置终端宿主，终端中的其他程序也会受影响。
- 切换中英文及标点沿用现有 compartment 通路和标点锁定配置。`input.ime_mode_scope = "global"` 时，英文状态也会同步到其他应用；需要应用间独立状态时使用 `"app"`。

手工验证：

1. 在已配置的编辑器中切到中文，输入并提交中文；按 Esc 后编辑器进入 normal 模式、水杉进入英文状态，再按 `hjkl` 应执行移动。
2. 输入尚未提交的拼音，按 Esc 应保留原有取消输入行为；释放后再次按 Esc 才切英文。长按第一次 Esc 不应触发切换。
3. 在未配置的应用、关闭配置后及使用带修饰键的 Esc 时，确认原有行为不变。
4. 修改配置并等待一秒，确认无需重启即可启停；检查默认数据目录和非 ASCII 的自定义数据目录。
5. 验证 Server 重启、失焦/回焦、中文/英文标点锁定、`app` / `global` 状态范围，以及不先调用 `OnTestKeyDown` 的宿主路径。

自动回归目标 `vim_mode` 验证 `vim_mode_apps` 解析、按应用匹配、无效配置和按键策略。真实宿主的 normal/insert 状态和 TSF 回调顺序仍需按以上步骤验证。