354 lines
10 KiB
Markdown
354 lines
10 KiB
Markdown
# Vim 输入法自动切换插件
|
||
|
||
[](./CHANGELOG.md)
|
||
[](#安装要求)
|
||
[](./LICENSE.txt)
|
||
|
||
[English](./README_en.md) | 中文
|
||
|
||
[感谢 github 中的 vim-im-switch这个项目](https://github.com/yourusername/vim-im-switch)
|
||
这个项目不能满足需求，在这个项目基础上改进。
|
||
|
||
作者：Gavin Chan
|
||
|
||
> 🚀 **智能输入法管理工具** - 为 Vim 用户打造的无感知输入法切换体验
|
||
|
||
这是为 **原生 Vim** 和 **Obsidian 编辑器** 的 Vim 模式设计的智能输入法自动切换插件，包含：
|
||
- 🎯 **Obsidian 插件**：适用于 Obsidian 编辑器的 Vim 模式
|
||
- ⚡ **Vim 插件**：适用于原生 Vim/NeoVim 编辑器
|
||
- 🌍 **跨平台支持**：macOS、Linux、Windows 全平台兼容
|
||
|
||
## ✨ 功能亮点
|
||
|
||
- 🔄 **自动切换输入法**：在 Vim 的 Normal 模式和 Insert 模式之间切换时，自动切换输入法
|
||
- 🧠 **智能状态记忆**：记住上次 Insert 模式退出时的输入法状态，下次进入时自动恢复
|
||
- 🎭 **无感知体验**：完全静默切换，无 UI 闪烁或延迟
|
||
- 🌐 **中英混合友好**：完美支持中英文混合输入场景
|
||
- ⚡ **多重保障机制**：三层检测确保切换的可靠性
|
||
|
||
## 核心特性
|
||
### 1. 模式切换自动化
|
||
- 进入 Normal 模式（按 ESC 或其他命令）→ 自动切换到英文输入法
|
||
- 进入 Insert 模式（按 i, a, o 等）→ 自动恢复上次的输入法状态
|
||
|
||
### 2. 输入法状态记忆
|
||
- 退出 Insert 模式时，自动检测并保存当前的输入法（中文/英文）
|
||
- 下次进入 Insert 模式时，自动恢复到上次保存的输入法状态
|
||
- 支持中英文混合输入场景
|
||
|
||
### 3. 智能检测机制
|
||
插件采用**三重检测机制**确保可靠性：
|
||
|
||
| 检测方式 | 优先级 | 说明 |
|
||
|---------|--------|------|
|
||
| 🎯 **键盘事件监听** | 最高 | 使用事件捕获模式监听 ESC 和 Insert 按键，响应最快 |
|
||
| 🔧 **CodeMirror 事件** | 中等 | 监听 vim-mode-change 事件，处理非按键触发的模式切换 |
|
||
| 🔄 **定时轮询** | 兜底 | 100ms 轮询检测模式变化，作为最后保障机制 |
|
||
|
||
### 4. 技术特性
|
||
- ⚡ **异步处理**：使用 `job_start()` 异步执行，避免 UI 阻塞
|
||
- 🛡️ **防抖机制**：100ms 防抖避免重复处理
|
||
- 🎯 **事件捕获优化**：使用 capture 模式确保最快响应
|
||
- 🔧 **自动检测**：智能检测和配置中文输入法
|
||
|
||
## 安装要求
|
||
|
||
#### 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 脚本：
|
||
1. 安装 [AutoHotkey](https://www.autohotkey.com/)
|
||
2. 使用项目中的 `fcitx-remote.ahk` 脚本
|
||
3. 或下载编译好的版本：[fcitx-remote.exe](https://github.com/yuanotes/obsidian-vim-im-switch-plugin/releases/download/1.0.3/fcitx-remote.exe)
|
||
4. 将 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 vim-im-switch.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'
|
||
```
|
||
|
||
#### 使用插件管理器安装
|
||
|
||
**vim-plug**:
|
||
```vim
|
||
Plug 'yourusername/vim-im-switch'
|
||
```
|
||
|
||
**Vundle**:
|
||
```vim
|
||
Plugin 'yourusername/vim-im-switch'
|
||
```
|
||
|
||
### 🚀 一键部署（推荐）
|
||
|
||
使用部署脚本同时安装 Obsidian 插件和 Vim 插件：
|
||
```bash
|
||
# 克隆项目
|
||
git clone https://github.com/yourusername/vim-im-switch.git
|
||
cd vim-im-switch
|
||
|
||
# 构建并部署
|
||
npm install
|
||
./deploy.sh
|
||
```
|
||
|
||
> 💡 **提示**: v2.0.2 修复了终端 Vim 中的标题闪烁问题，详见 [更新日志](./CHANGELOG.md)
|
||
|
||
## 使用方法
|
||
|
||
### 基本使用场景
|
||
|
||
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 模式和输入法状态，在模式转换时自动切换输入法，同时保留用户偏好设置。
|
||
|
||
## 🔧 故障排除
|
||
|
||
### 快速诊断
|
||
使用内置诊断脚本：
|
||
```bash
|
||
./diagnose-im.sh
|
||
```
|
||
|
||
### 常见问题
|
||
|
||
#### 🚫 插件没有效果
|
||
1. **检查依赖**：确认 fcitx-remote 是否正确安装
|
||
```bash
|
||
# macOS
|
||
fcitx-remote -n
|
||
|
||
# Linux
|
||
which fcitx-remote
|
||
|
||
# Windows
|
||
fcitx-remote.exe
|
||
```
|
||
|
||
2. **检查日志**：
|
||
- **Obsidian**: 开发者控制台 (Ctrl+Shift+I)
|
||
- **Vim**: `:messages` 命令
|
||
|
||
3. **验证配置**：确认输入法名称与系统设置匹配
|
||
|
||
#### ⚠️ 输入法切换不正确
|
||
1. **获取正确的输入法名称**：
|
||
```bash
|
||
# 切换到中文输入法后执行
|
||
fcitx-remote -n
|
||
```
|
||
|
||
2. **手动测试**：
|
||
```bash
|
||
# 切换到英文
|
||
fcitx-remote -s com.apple.keylayout.ABC
|
||
|
||
# 切换到中文（替换为你的输入法名称）
|
||
fcitx-remote -s com.tencent.inputmethod.wetype.pinyin
|
||
```
|
||
|
||
3. **检查冲突**：暂时禁用其他 Vim 插件测试
|
||
|
||
#### 🐛 其他问题
|
||
- **权限问题**：确保 fcitx-remote 有执行权限
|
||
- **路径问题**：检查 fcitx-remote 是否在 PATH 中
|
||
- **版本兼容**：确认 Vim 版本支持 `job_start()` (Vim 8+)
|
||
|
||
## 🛠️ 开发指南
|
||
|
||
### 环境要求
|
||
- Node.js 14+
|
||
- TypeScript 4.2+
|
||
- Rollup (构建工具)
|
||
|
||
### 构建项目
|
||
```bash
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 开发模式（监听文件变化）
|
||
npm run dev
|
||
|
||
# 生产构建
|
||
npm run build
|
||
```
|
||
|
||
### 项目结构
|
||
```
|
||
vim-im-switch/
|
||
├── main.ts # Obsidian 插件主文件
|
||
├── vim-im-switch.vim # Vim 插件文件
|
||
├── fcitx-remote.ahk # Windows 支持脚本
|
||
├── fcitx-remote-for-osx/ # macOS 支持工具
|
||
├── deploy.sh # 一键部署脚本
|
||
├── diagnose-im.sh # 诊断脚本
|
||
└── vim-im-switch-plugin/ # 构建输出目录
|
||
```
|
||
|
||
### 调试方法
|
||
|
||
#### Obsidian 插件调试
|
||
插件会在控制台输出关键日志：
|
||
```
|
||
🚀 [VimIMSwitch] Loading plugin...
|
||
🔤 [VimIMSwitch] ESC → English (saved Chinese)
|
||
🈳 [VimIMSwitch] → Chinese
|
||
❌ [VimIMSwitch] Error: ...
|
||
```
|
||
|
||
#### Vim 插件调试
|
||
```vim
|
||
" 查看插件消息
|
||
:messages
|
||
|
||
" 检查插件是否加载
|
||
:echo exists('g:fcitx_remote')
|
||
|
||
" 手动测试函数
|
||
:call Fcitx2en()
|
||
:call Fcitx2zh()
|
||
```
|
||
|
||
### 贡献指南
|
||
1. Fork 项目
|
||
2. 创建功能分支：`git checkout -b feature/amazing-feature`
|
||
3. 提交更改：`git commit -m 'Add amazing feature'`
|
||
4. 推送分支：`git push origin feature/amazing-feature`
|
||
5. 提交 Pull Request
|
||
|
||
## 📋 版本历史
|
||
|
||
| 版本 | 日期 | 主要更新 |
|
||
|------|------|----------|
|
||
| [v2.0.3](./CHANGELOG.md#203---2025-11-09) | 2025-11-09 | 修复 Normal 模式 ESC 键问题 |
|
||
| [v2.0.2](./CHANGELOG.md#202---2025-11-04) | 2025-11-04 | 修复终端兼容性问题 |
|
||
| [v2.0.0](./CHANGELOG.md#200---2025-11-04) | 2025-11-04 | 新增 Vim 原生插件支持 |
|
||
| [v1.0.8](./CHANGELOG.md#108---2025-01-04) | 2025-01-04 | 智能状态记忆功能 |
|
||
| [v1.0.0](./CHANGELOG.md#100---2024-06-01) | 2024-06-01 | 首次发布 |
|
||
|
||
查看 [完整更新日志](./CHANGELOG.md) 获取详细的版本更新历史。
|
||
|
||
## 🔗 相关链接
|
||
|
||
- 📖 [English Documentation](./README_en.md)
|
||
- 📝 [更新日志](./CHANGELOG.md)
|
||
- 🛠️ [fcitx-remote-for-osx](https://github.com/xcodebuild/fcitx-remote-for-osx)
|
||
- 🐛 [问题反馈](https://github.com/yourusername/vim-im-switch
|
||
|
||
## 🙏 致谢
|
||
|
||
感谢以下项目和贡献者：
|
||
- [fcitx-remote-for-osx](https://github.com/xcodebuild/fcitx-remote-for-osx) - macOS 输入法控制工具
|
||
- [Obsidian](https://obsidian.md/) - 强大的知识管理工具
|
||
- [Vim](https://www.vim.org/) / [NeoVim](https://neovim.io/) - 经典的文本编辑器
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
|
||
**如果这个项目对你有帮助，请给个 ⭐ Star！**
|
||
|
||
Made with ❤️ for Vim users
|
||
|
||
</div>
|