深入理解 which-key.nvim 中的函数调用与映射机制

问题现象分析

在 which-key.nvim 插件使用过程中，开发者可能会遇到一个看似奇怪的现象：当使用 vim.cmd.*() 形式带有参数的函数进行键位映射时，这些命令会在 Neovim 启动时自动执行，而不是在按下映射键时执行。例如：

-- 这会使得 "Hello" 在启动时就被打印
require("which-key").register({
    ["<leader>h"] = { vim.cmd.echo('"Hello"'), "测试打印" }
})

技术原理剖析

这种现象并非 which-key.nvim 的 bug，而是 Lua 语言函数调用机制的自然表现。在 Lua 中：

1. 函数引用：直接使用函数名（如 vim.cmd.edit）传递的是函数本身
2. 函数调用：使用括号（如 vim.cmd.edit()）会立即执行函数并传递其返回值

当我们在映射配置中写成 vim.cmd.edit('test_file') 时，实际上是在 Neovim 启动解析配置阶段就执行了这个命令，而不是创建一个等待按键触发的动作。

正确使用方法

方法一：使用匿名函数包装

require("which-key").register({
    ["<leader>e"] = {
        function() vim.cmd.edit("test_file") end,
        "编辑测试文件"
    }
})

方法二：预定义函数后引用

local function editTestFile()
    vim.cmd.edit("test_file")
end

require("which-key").register({
    ["<leader>e"] = { editTestFile, "编辑测试文件" }
})

方法三：使用命令字符串格式

require("which-key").register({
    ["<leader>e"] = { '<cmd>edit test_file<cr>', "编辑测试文件" }
})

高级应用场景

对于需要用户交互的复杂命令，可以结合 vim.fn.input() 实现动态输入：

local function diffOpen()
    local revision = vim.fn.input("请输入要比较的版本号: ")
    vim.cmd("DiffviewOpen " .. revision)
end

require("which-key").register({
    g = {
        name = "Git 操作",
        o = { diffOpen, "打开差异比较" }
    }
}, { prefix = "<leader>" })

最佳实践建议

1. 对于简单命令，优先使用字符串形式的 <cmd>...<cr> 语法
2. 需要参数化或条件逻辑时，使用匿名函数或预定义函数
3. 避免直接在映射配置中调用函数（使用括号形式）
4. 复杂交互逻辑建议封装为独立函数，提高代码可读性

理解这些概念不仅适用于 which-key.nvim，也是 Lua 配置 Neovim 时需要掌握的基础知识。正确区分函数引用和函数调用，能够帮助开发者编写出更符合预期的配置代码。