Which-key.nvim 中缓冲区本地映射描述失效问题解析

问题背景

在 Neovim 的 which-key.nvim 插件 v3 版本中，用户发现了一个关于缓冲区本地映射描述无法正常显示的问题。具体表现为：当用户尝试为缓冲区本地键映射组设置描述时，预期的描述文本没有出现在 which-key 的浮动窗口中。

技术细节分析

该问题主要涉及 which-key.nvim 插件对缓冲区本地映射的处理机制。在插件内部，映射描述可以通过两种方式指定：

1. 使用 desc 字段：直接为单个映射提供描述文本
2. 使用 group 字段：定义一个映射组的标题

在全局映射场景下，这两种方式都能正常工作。但在缓冲区本地映射场景中，当仅使用 desc 字段为映射组设置描述时，插件未能正确识别和处理这些描述信息。

解决方案

经过项目维护者的排查，确认这是一个实现上的缺陷。修复方案包括：

1. 确保插件正确处理缓冲区本地映射的 desc 和 group 字段
2. 明确区分单个映射和映射组的行为差异

对于用户而言，目前有两种可行的解决方案：

-- 方案1：使用 group 字段
require("which-key").add({
  { "<Leader>g", group = "Test", mode = { "n", "v" }, buffer = buf },
})

-- 方案2：使用 desc 字段（修复后也可用）
require("which-key").add({
  { "<Leader>g", desc = "Test", mode = { "n", "v" }, buffer = buf },
})

技术要点说明

1. 映射与映射组的区别：

   • 单个映射通常对应具体的功能实现
   • 映射组则是多个相关映射的容器，用于组织键位布局

2. 显示行为差异：

   • 没有子节点的单个映射（非组映射）默认会显示
   • 没有子节点的组映射默认不会显示

3. 字段选择建议：

   • 当需要确保某个节点始终显示时，使用 desc
   • 当定义纯组织性节点时，使用 group

最佳实践

1. 对于简单的缓冲区本地键位提示，可以直接使用 desc 字段
2. 对于复杂的键位组织结构，建议使用 group 明确定义映射组
3. 在插件开发中，如果键位需要动态显示/隐藏，应根据实际需求选择合适的字段类型

该问题的修复已经合并到主分支，用户更新插件后即可正常使用缓冲区本地映射描述功能。