0Pricing
Lua Academy · 课时

命令与按键映射

添加面向用户的操作。

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

用户命令概览

用户命令是插件提供的冒号命令，例如 :Format 或 :Telescope。它们必须以大写字母开头。

nvim_create_user_command 在 Lua 中定义用户命令，接受名称、回调或字符串，以及一个选项表。这取代了 Vimscript 的 :command。

vim.api.nvim_create_user_command('Hello', function()
  print('Hello from my plugin')
end, {})

命令参数

请设置 nargs 以接受参数：'0'、'1'、'*'、'?' 或 '+'。回调会接收一个 opts 表，其中包含 args、fargs 和 bang。

fargs 是已经按空白字符拆分好的参数列表，通常正是您需要的形式。

vim.api.nvim_create_user_command('Greet', function(opts)
  print('Hi ' .. opts.args)
end, { nargs = 1 })

范围与强制命令

传入 range = true 以接受行范围；回调随后会读取 opts.line1 和 opts.line2。添加 bang = true 可允许使用 :Cmd!，并通过 opts.bang 检测。

这些标志让同一个命令能够针对可视选择或强制变体执行不同的行为。

vim.api.nvim_create_user_command('Sum', function(o)
  print(o.line1 .. ' to ' .. o.line2)
end, { range = true })

命令补全

请使用 complete 选项提供制表符补全。您可以使用 'file' 或 'buffer' 等内置补全，也可以使用自定义 Lua 函数。

自定义补全函数会接收部分参数和命令行，并返回候选字符串列表。

vim.api.nvim_create_user_command('Pick', function(o) print(o.args) end, {
  nargs = 1,
  complete = function() return { 'red', 'green', 'blue' } end,
})

缓冲区局部命令

若要将命令限定到一个缓冲区，请将该缓冲区句柄传给 nvim_buf_create_user_command。文件类型插件中经常采用这种方式。

例如，Markdown 插件可以只在 Markdown 缓冲区内定义 :Preview，从而保持全局命名空间整洁。

vim.api.nvim_buf_create_user_command(0, 'Preview', function()
  print('previewing this buffer')
end, {})

介绍 vim.keymap.set

vim.keymap.set 是现代映射 API。它接受一个模式、左侧按键、右侧字符串或 Lua 函数，以及一个选项表。

与旧的 nvim_set_keymap 不同，它可以直接将 Lua 回调作为右侧内容，无需使用 <cmd>lua 包装。

vim.keymap.set('n', '<leader>w', function()
  vim.cmd('write')
end, { desc = 'Save file' })

模式与多重映射

模式参数可以是 'n' 这样的单个字符串，也可以是 { 'n', 'v' } 这样的表，以便同时映射多个模式。

常见模式包括：n 普通模式、i 插入模式、v 可视模式、x 仅可视模式以及 t 终端模式。空字符串 '' 表示普通模式、可视模式和操作符待决模式。

vim.keymap.set({ 'n', 'v' }, '<leader>y', '"+y', { desc = 'Yank to clipboard' })

映射选项

opts 表控制行为。silent = true 会隐藏命令回显，出于安全考虑，noremap 默认为 true，而 buffer = 0 会将映射限定到当前缓冲区。

请始终添加 desc，这样 which-key 和 :map 的输出才易于阅读。

vim.keymap.set('n', 'gd', vim.lsp.buf.definition, {
  buffer = 0, silent = true, desc = 'Go to definition',
})

表达式映射

使用 expr = true 时，右侧函数会返回要输入的按键。这可以实现智能映射，例如在补全菜单可见时让 <Tab> 执行不同的操作。

返回空字符串表示不执行任何操作，或者返回要插入的字面按键。

vim.keymap.set('i', '<Tab>', function()
  return vim.fn.pumvisible() == 1 and '<C-n>' or '<Tab>'
end, { expr = true })

删除映射

请使用 vim.keymap.del 删除映射，并传入相同的模式和按键；如果映射属于缓冲区局部映射，还要传入 buffer 字段。

这对清理例程很有用，也适用于插件关闭某项功能后需要恢复用户原有按键绑定的情况。

vim.keymap.del('n', '<leader>w')
vim.keymap.del('n', 'gd', { buffer = 0 })

结合命令与按键映射

一种简洁的模式是只定义一次逻辑，将其公开为用户命令，再绑定一个调用该命令的按键。这样可以保持唯一的逻辑来源。

映射到 <cmd>Hello<cr> 可以避免退出可视模式，并且比 :Hello<cr> 更加可预测。

vim.api.nvim_create_user_command('Toggle', function() end, {})
vim.keymap.set('n', '<leader>t', '<cmd>Toggle<cr>', { desc = 'Toggle' })

快速检查

请检查您对命令和按键映射的掌握程度。

回顾：命令与按键映射

现在您可以使用 nvim_create_user_command 创建命令，通过 nargs、range、bang 和 complete 控制命令，并将命令限定到指定缓冲区。

对于映射，vim.keymap.set 支持 Lua 回调、多个模式，以及 desc、silent、buffer 和 expr 等选项；清理时可以使用 vim.keymap.del。

常见问题解答

「命令与按键映射」课时是免费的吗？

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

「命令与按键映射」这节课中我会学到什么？

添加面向用户的操作。 你通过在浏览器中直接运行的动手代码来练习 Lua Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Lua Academy 需要有经验吗？

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

「命令与按键映射」课时需要多长时间？

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

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

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

此课程中的所有课时

  1. Neovim Lua API
  2. 命令与按键映射
  3. 缓冲区与窗口
  4. 打包插件
← 返回 Lua Academy