vim-im-switch/README.md

# Vim 输入法自动切换插件

[English](./README_en.md) | 中文

这是一个为 Vim 和 Obsidian 编辑器的 Vim 模式设计的输入法自动切换插件，包含：
- **Obsidian 插件**：适用于 Obsidian 编辑器的 Vim 模式
- **Vim 插件**：适用于原生 Vim/NeoVim 编辑器

## 功能简介

- 自动切换输入法：在 Vim 的 Normal 模式和 Insert 模式之间切换时，自动切换输入法
- 智能记忆：记住上次 Insert 模式退出时的输入法状态，下次进入时自动恢复
- 无缝体验：在 Insert 模式下正常输入文本时不会触发输入法切换

## 核心特性
### 1. 模式切换自动化
- 进入 Normal 模式（按 ESC 或其他命令）→ 自动切换到英文输入法
- 进入 Insert 模式（按 i, a, o 等）→ 自动恢复上次的输入法状态

### 2. 输入法状态记忆
- 退出 Insert 模式时，自动检测并保存当前的输入法（中文/英文）
- 下次进入 Insert 模式时，自动恢复到上次保存的输入法状态
- 支持中英文混合输入场景

### 3. 智能检测机制
插件使用多重检测机制确保可靠性：
- **键盘事件监听**（主要）：使用事件捕获模式监听 ESC 和 Insert 按键
- **CodeMirror 事件**（辅助）：监听 vim-mode-change 事件
- **定时轮询**（兜底）：100ms 轮询检测模式变化

## 安装要求

#### macOS
1. 安装 [fcitx-remote-for-osx](https://github.com/xcodebuild/fcitx-remote-for-osx):
   ```bash
   brew install fcitx-remote-for-osx
   ```

2. 验证安装：
   ```bash
   fcitx-remote -n
   # 应该输出当前输入法的名称，如：com.apple.keylayout.ABC
   ```

#### Linux
通过你的包管理器安装 `fcitx`：
```bash
# Ubuntu/Debian
sudo apt-get install fcitx

# Fedora
sudo dnf install fcitx

# Arch Linux
sudo pacman -S fcitx
```

#### Windows
下载并安装 AutoHotKey 版本的 fcitx-remote：
- [下载 fcitx-remote.exe](https://github.com/yuanotes/obsidian-vim-im-switch-plugin/releases/download/1.0.3/fcitx-remote.exe)
- 将 exe 文件放到系统 PATH 路径中

## 安装插件

### Obsidian 插件安装

1. 下载插件文件到 Obsidian 插件目录：
   ```bash
   cd /path/to/your/vault/.obsidian/plugins/
   git clone https://github.com/yourusername/vim-im-switch.git
   ```

2. 在 Obsidian 中启用插件：
   - 打开设置 → 社区插件 → 浏览
   - 找到 "Vim Input Method Switch"
   - 点击启用

3. 配置输入法（可选）：
   - 打开插件设置
   - 设置英文输入法（默认：`com.apple.keylayout.ABC`）
   - 设置中文输入法（默认：自动检测）

### Vim 插件安装

1. 复制插件文件到 Vim 配置目录：
   ```bash
   mkdir -p ~/.vim/plugin
   cp fcitx-osx.vim ~/.vim/plugin/
   ```

2. 重启 Vim，插件会自动加载

3. 配置输入法（可选）：
   在 `.vimrc` 中添加：
   ```vim
   " 英文输入法 ID（默认值）
   let g:fcitx_english_im = 'com.apple.keylayout.ABC'
   
   " 中文输入法 ID（可选，插件会自动检测）
   " let g:fcitx_chinese_im = 'com.tencent.inputmethod.wetype.pinyin'
   ```

### 一键部署（推荐）

使用部署脚本同时安装两个插件：
```bash
./deploy.sh
```

Note: v2.0.2 fixes a terminal-specific title/flash issue when using terminal Vim (see CHANGELOG for details).

## 使用方法

### 基本使用场景

1. **中文输入**：
   ```
   按 i → 进入 Insert 模式 → 输入法切换到中文（如果上次是中文）
   输入中文内容
   按 ESC → 退出到 Normal 模式 → 输入法切换到英文
   ```

2. **英文输入**：
   ```
   按 i → 进入 Insert 模式 → 输入法保持英文（如果上次是英文）
   输入英文内容
   按 ESC → 退出到 Normal 模式 → 输入法保持英文
   ```

3. **中英混合**：
   ```
   按 i → 自动恢复上次的输入法
   输入中文，然后手动切换到英文继续输入
   按 ESC → 保存当前输入法状态（英文）
   按 i → 自动恢复英文输入法
   ```

### 支持的 Vim 命令

- **进入 Insert 模式**：`i`, `I`, `a`, `A`, `o`, `O`, `s`, `S`, `c`, `C`
- **退出 Insert 模式**：`ESC`, 以及其他触发 Normal 模式的命令

## 工作原理

```mermaid
graph TD
    A[Normal 模式<br/>英文输入法] -->|按 i/a/o 等| B[检测模式切换]
    B --> C[恢复上次保存的<br/>输入法状态]
    C --> D[Insert 模式<br/>自动恢复的输入法:<br/>中文/英文]
    D -->|按 ESC| E[保存当前输入法<br/>状态 中/英]
    E --> F[切换到英文输入法]
    F --> A

    style A fill:#e1f5ff,stroke:#01579b,stroke-width:2px
    style D fill:#fff9c4,stroke:#f57f17,stroke-width:2px
    style E fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    style F fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
```

插件维护一个状态机，跟踪 Vim 模式和输入法状态，在模式转换时自动切换输入法，同时保留用户偏好设置。

## 故障排除

### 问题：插件没有效果
1. 检查 fcitx-remote 是否正确安装
2. 检查插件日志（开发者控制台）
3. 验证输入法名称是否与设置匹配

### 问题：输入法切换不正确
1. 确认设置中的输入法名称正确
2. 手动切换输入法后，在开发者控制台查看日志
3. 检查是否有其他插件冲突

## 开发

### 构建
```bash
npm install
npm run build
```

### 部署
一键部署 Obsidian 插件和 Vim 插件：
```bash
./deploy.sh
```

### 调试

#### Obsidian 插件
插件会在控制台输出关键日志：
- `Loading plugin...` - 插件加载
- `ESC → English` - ESC 切换到英文
- `→ Chinese` - 切换到中文
- `Error...` - 错误信息

#### Vim 插件
在 Vim 中查看消息：
```vim
:messages
```

## 更新日志
查看 [CHANGELOG.md](./CHANGELOG.md) 获取详细的版本更新历史。

## 相关链接
- [更新日志](./CHANGELOG.md)
- [English Documentation](./README_en.md)
- [fcitx-remote-for-osx](https://github.com/xcodebuild/fcitx-remote-for-osx)