Neovim 插件开发学习指南

欢迎来到 Neovim 插件开发的学习之旅！这个仓库包含了从基础到进阶的示例插件，帮助你逐步掌握 Neovim 插件开发。

🎯 学习目标

通过这些示例，你将学会：

• Neovim 插件的基本结构
• Lua 在 Neovim 中的使用
• 如何操作缓冲区和窗口
• 如何创建用户命令和快捷键
• 如何使用 Neovim API
• 如何创建浮动窗口和 UI

📁 项目结构

nvim_plugin/
├── README.md                    # 本文件
├── 01-hello-world/             # 示例1: 最简单的插件
├── 02-text-manipulator/        # 示例2: 文本操作插件
├── 03-floating-window/         # 示例3: 浮动窗口插件
├── 04-comment-enhancer/        # 示例4: 实用注释插件
└── docs/                       # 学习文档

🚀 快速开始

前置要求

1. Neovim 版本: 0.8.0 或更高

   nvim --version

2. 基本的 Lua 知识: 如果不熟悉，建议先快速浏览 Lua 5.1 入门

安装和测试插件

每个示例插件都可以独立安装和测试。有两种方式：

方式 1: 临时加载（推荐用于学习）

" 在 Neovim 中执行
:set runtimepath+=w:/project/antigravity/nvim_plugin/01-hello-world

方式 2: 使用插件管理器（如 lazy.nvim）

在你的 init.lua 中添加：

{
  dir = "w:/project/antigravity/nvim_plugin/01-hello-world",
  config = function()
    require("hello-world").setup()
  end
}

📖 学习路线

第一步：Hello World (01-hello-world)

学习时间: 30分钟

学习内容:

• 插件的基本目录结构
• 如何编写最简单的 Lua 模块
• 如何创建用户命令
• 如何在 Neovim 中显示消息

实践任务:

• 加载插件并执行 :HelloWorld 命令
• 修改消息内容
• 添加一个新的命令 :HelloName 显示你的名字

---

第二步：文本操作 (02-text-manipulator)

学习时间: 1-2小时

学习内容:

• 如何读取和修改缓冲区内容
• 如何获取光标位置
• 如何操作选中的文本
• 如何创建多个相关命令

实践任务:

• 使用插件转换文本大小写
• 理解 vim.api.nvim_buf_get_lines() 的工作原理
• 添加一个反转文本的功能
• 尝试添加单词计数功能

---

第三步：浮动窗口 (03-floating-window)

学习时间: 2-3小时

学习内容:

• 如何创建浮动窗口
• 如何配置窗口样式和位置
• 如何创建交互式 UI
• 如何处理窗口事件

实践任务:

• 打开示例浮动窗口
• 修改窗口大小和位置
• 更改窗口边框样式
• 添加快捷键关闭窗口

---

第四步：实用插件 (04-comment-enhancer)

学习时间: 3-4小时

学习内容:

• 如何检测当前文件类型
• 如何根据语言使用不同的注释符号
• 如何创建复杂的文本处理逻辑
• 插件配置和用户自定义

实践任务:

• 为代码添加标准注释
• 添加你自己使用的编程语言支持
• 自定义注释模板
• 创建快捷键绑定

🔧 Neovim 核心 API 速查

缓冲区操作

-- 获取当前缓冲区
vim.api.nvim_get_current_buf()

-- 获取缓冲区行
vim.api.nvim_buf_get_lines(buf, start, end, strict)

-- 设置缓冲区行
vim.api.nvim_buf_set_lines(buf, start, end, strict, lines)

-- 获取缓冲区名称
vim.api.nvim_buf_get_name(buf)

窗口操作

-- 获取当前窗口
vim.api.nvim_get_current_win()

-- 创建浮动窗口
vim.api.nvim_open_win(buf, enter, config)

-- 关闭窗口
vim.api.nvim_win_close(win, force)

-- 设置窗口选项
vim.api.nvim_win_set_option(win, option, value)

光标操作

-- 获取光标位置 (row, col)
vim.api.nvim_win_get_cursor(win)

-- 设置光标位置
vim.api.nvim_win_set_cursor(win, {row, col})

命令和快捷键

-- 创建用户命令
vim.api.nvim_create_user_command(name, command, opts)

-- 创建快捷键映射
vim.keymap.set(mode, lhs, rhs, opts)

消息和通知

-- 打印消息
print("message")
vim.notify("message", vim.log.levels.INFO)

-- 错误消息
vim.api.nvim_err_writeln("error message")

📚 推荐学习资源

官方文档

• :help lua-guide - Neovim Lua 指南
• :help api - Neovim API 文档
• :help lua - Lua 相关帮助

在线资源

• Neovim 官方文档
• Learn X in Y minutes: Lua
• Neovim Lua 指南

优秀的开源插件（学习参考）

• telescope.nvim - 模糊查找器
• nvim-tree.lua - 文件树
• Comment.nvim - 注释插件

💡 学习建议

1. 逐步学习: 按顺序完成每个示例，不要跳过
2. 动手实践: 不要只看代码，要实际运行和修改
3. 阅读文档: 遇到不懂的 API 就查 :help api
4. 实验和调试: 使用 :lua print(vim.inspect(value)) 查看变量值
5. 参考优秀插件: 看看流行插件的源代码学习最佳实践

🐛 调试技巧

-- 打印调试信息
print("Debug:", variable)

-- 格式化打印复杂对象
print(vim.inspect(table))

-- 查看错误消息
:messages

-- 重新加载模块（开发时很有用）
:lua package.loaded['your-module'] = nil
:lua require('your-module').setup()

🎓 下一步

完成所有示例后，你可以：

1. 创建自己的实用插件
2. 为现有插件贡献代码
3. 探索更高级的功能（LSP、Treesitter 等）

📝 练习项目建议

尝试创建这些插件来巩固学习：

• 时间追踪插件
• Markdown 目录生成器
• 代码片段管理器
• Git 文件对比查看器
• 项目笔记本

❓ 常见问题

Q: 我需要很强的 Lua 基础吗？ A: 不需要。Neovim 插件使用的 Lua 比较简单，边学边用即可。

Q: 插件修改后需要重启 Neovim 吗？ A: 不需要，可以使用 :lua package.loaded['module'] = nil 然后重新加载。

Q: 如何查看 Neovim API 文档？ A: 在 Neovim 中输入 :help api 或具体的函数名如 :help nvim_buf_set_lines

Q: 插件出错了怎么办？ A: 查看 :messages 获取错误信息，使用 print() 和 vim.inspect() 调试。

🤝 贡献

这是你的学习仓库，随意修改和实验！

---

祝学习愉快！如有问题，记得查看 :help lua-guide 和 :help api！