Lua Academy · 课时

Neovim Lua API

Q: 「Neovim Lua API」这节课中我会学到什么？

了解插件如何接入。 你通过在浏览器中直接运行的动手代码来练习 Lua Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

了解插件如何接入。

Neovim Lua API 是 CoddyKit 上的免费 Lua Academy 课时。这是第 1 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Lua Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Lua Academy 课程共包含 4 节课。

为什么在 Neovim 中使用 Lua

Neovim 内置了 LuaJIT 运行时，使 Lua 成为与 Vimscript 并列的原生脚本语言。插件作者偏爱 Lua，因为它速度快、拥有真正的数据结构，并且具备简洁的模块系统。

全局 vim 表是通往一切功能的入口：编辑器状态、API、选项以及标准库辅助函数。掌握它是进行现代插件开发的基础。

print(vim.inspect(vim.version()))

vim.api 层

vim.api 提供底层远程 API：所有以 nvim_ 为前缀的函数。这些调用与外部客户端通过 RPC 使用的调用相同，但在进程内运行时会立即执行。

nvim_get_current_buf、nvim_buf_set_lines 和 nvim_command 等函数提供了精确的控制。它们稳定、文档完善，是严肃插件的基础。

local buf = vim.api.nvim_get_current_buf()
local name = vim.api.nvim_buf_get_name(buf)
print(name)

vim.fn — 调用 Vimscript 函数

vim.fn 连接到 Vimscript 的内置函数。Vimscript 中可以调用的任何函数，例如 expand() 或 fnamemodify()，都可以通过 vim.fn.expand(...) 访问。

当尚不存在原生 API 时，这一功能非常有价值。参数和返回值会在 Lua 类型与 Vimscript 类型之间自动转换。

local path = vim.fn.expand('%:p')
local tail = vim.fn.fnamemodify(path, ':t')
print(tail)

选项：vim.o、vim.bo、vim.wo

选项通过元表设置。vim.o 针对全局选项，vim.bo 针对缓冲区局部选项，vim.wo 针对窗口局部选项。

赋值只需写入字段即可。这取代了冗长的 nvim_set_option 调用，也让配置代码更自然易读。

vim.o.number = true
vim.bo.shiftwidth = 2
vim.wo.wrap = false

vim.g 与全局变量

vim.g 用于读取和写入全局 Vim 变量。插件通常会在这里提供配置开关，例如 vim.g.myplugin_enabled。

读取未设置的变量会返回 nil，因此请使用默认值进行保护。缓冲区局部和窗口局部的变体分别是 vim.b 和 vim.w。

vim.g.mapleader = ' '
local enabled = vim.g.myplugin_enabled or false
print(enabled)

通知与回显

请使用 vim.notify 向用户显示消息。它接受消息字符串，以及一个可选的、来自 vim.log.levels 的日志级别。

noice 或 notify 等插件管理器可以拦截这些消息，以提供更好的界面。对于面向用户的输出，请优先使用 vim.notify，而不是直接使用 print。

vim.notify('Plugin loaded', vim.log.levels.INFO)
vim.notify('Missing config', vim.log.levels.WARN)

使用 vim.schedule 进行调度

某些 API 调用禁止在快速事件上下文中执行，例如某些回调内部。vim.schedule 会将函数推迟到主循环中执行，此时可以安全地使用完整 API。

这样可以避免在异步上下文或自动命令上下文中修改缓冲区时出现令人头疼的“E5560”错误。

vim.schedule(function()
  vim.api.nvim_buf_set_lines(0, 0, 0, false, {'Hello'})
end)

在 Lua 中使用自动命令

nvim_create_autocmd 用于注册事件处理程序。请使用 nvim_create_augroup 将它们分组，并设置 clear = true，以避免重新加载时产生重复项。

回调会接收一个事件表，其中包含 buf 和 match 等字段，为处理程序提供精确的上下文。

local grp = vim.api.nvim_create_augroup('MyGrp', { clear = true })
vim.api.nvim_create_autocmd('BufWritePost', {
  group = grp,
  pattern = '*.lua',
  callback = function(ev) print('saved ' .. ev.file) end,
})

vim.tbl 与字符串辅助函数

Neovim 自带功能丰富的标准库。vim.tbl_extend、vim.tbl_keys 和 vim.split 覆盖了常见的表和字符串操作。

vim.tbl_deep_extend('force', defaults, opts) 是将用户配置合并到插件默认配置之上的标准方式。

local defaults = { width = 40, border = 'single' }
local opts = { width = 60 }
local cfg = vim.tbl_deep_extend('force', defaults, opts)
print(cfg.width, cfg.border)

使用 vim.inspect 进行调试

vim.inspect 会将任意 Lua 值序列化为可读字符串，包括嵌套表。它是了解 API 返回值结构最快的方法。

在开发过程中，可以将它与 :lua print(vim.inspect(...)) 或新版 Neovim 中的 :lua= expr 结合使用，以便快速检查值。

local info = vim.api.nvim_get_mode()
print(vim.inspect(info))

API 与 Vimscript 的取舍

对于稳定、结构化的操作，请优先使用 vim.api。没有原生函数时，再使用 vim.fn 或 vim.cmd。

vim.cmd 以字符串形式运行 Ex 命令，适合 vim.cmd('highlight ...') 这样的临时操作，但它不像类型化的 API 调用那样便于检查。

vim.cmd('syntax on')
vim.cmd.colorscheme('habamax')

快速检查

请测试您对 Neovim Lua API 范围的理解。

回顾：Lua API

现在您已经了解核心功能面：vim.api 用于类型化的原生 API，vim.fn 用于 Vimscript 函数，vim.cmd 用于 Ex 命令。

选项通过 vim.o/bo/wo 传递，变量通过 vim.g/b/w 传递，而 vim.tbl_deep_extend、vim.notify 和 vim.schedule 等辅助函数则完善了插件作者的工具集。

常见问题解答

「Neovim Lua API」课时是免费的吗？

是的 — 「Neovim Lua API」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Lua Academy 课程的其余内容，请升级到 CoddyKit PRO。 Lua Academy 课程共包含 4 节课。

「Neovim Lua API」这节课中我会学到什么？

了解插件如何接入。你通过在浏览器中直接运行的动手代码来练习 Lua Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Lua Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Lua Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 1 节课，共 4 节。

「Neovim Lua API」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Lua Academy 课中编写并运行代码吗？

能。每节 Lua Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Lua Academy