为Neovim写的一个简单的插件

插件地址：AQchance/flash-zh-simple.nvim

flash插件#

Neovim的flash插件是一个非常强大的搜索和导航工具，它可以帮助用户快速定位到文件中的任何位置。它由Neovim社区大名鼎鼎的插件作者folke开发，基本功能根据字符、单词等进行快速跳转。

flash最常用的最常用的几个功能包括：

字符快速跳转：按下s键后，输入一个或多个字符，每一个匹配的位置都会被高亮显示，并且会在后面显示一个高亮的字母标签，用户只需按下对应的标签即可快速跳转到该位置。
对vim原生的f, F, t, T快捷键功能的扩展：原生vim的f, F, t, T快捷键只能跳转到当前行内的某个字符，而flash插件则可以跨行进行跳转，极大地提升了跳转的灵活性和效率。

对于flash插件的完整功能不在此赘述，具体可以参考其官方文档。

对中文的适配工作#

原版的flash插件只支持对于英文字符的跳转，并不支持对中文字符的跳转。但是由于写博客或者其他的一些需求的时候，往往全篇都是中文字符，而中文之间没有空格分隔，因此基本的w, e, b等跳转命令会很难用。因此基于自己的这个需求，我开始寻找是否有人开发过类似的插件，支持对中文字符的跳转。

经过一番搜索，我找到了rainzm/flash-zh.nvim这个插件，这个插件是对原版flash插件的一个中文适配版本，支持对中文字符的跳转。这个插件对于中文的跳转是基于小鹤双拼输入法的编码规则来实现的，如果你使用的是小鹤双拼输入法，那么你使用这个插件就没有很大的压力。

举一个例子，假设我们要输入的内容是“中国”，那么在小鹤双拼中，“中”的拼音是“vs”，“国”的拼音是“go”，那么在使用这个插件进行跳转的时候，我们只需要输入“vsgo”即可根据标签快速跳转到“中国”，这显然极大的方便了中文用户的跳转需求。

小鹤双拼的键位布局如下图所示：

小鹤双拼

小鹤音形官网

但是很显然这个插件对我这样的只会使用全拼的用户很不友好，而且我并没有想要改变打字习惯的想法。因此我决定基于以上两个插件自己动手写一个简单的全拼插件。

插件实现#

因为flash-zh.nvim这个插件已经实现了基本的功能了，因此我只需要把全拼映射到双拼的键位上，然后调用flash-zh.nvim的跳转函数即可，整体的实现逻辑还是比较简单的。

首先我们需要定义一个小鹤双拼的映射表，把全拼的声母和韵母映射到对应的键位上。对于声母来说，只有zh, ch, sh需要特殊映射，其他的声母都是单字符的，因此不需要特殊处理。对于韵母来说，我们需要把所有的小鹤双拼韵母都映射到对应的键位上。

1
-- 小鹤双拼映射表
2
local map = {
3
  -- 声母映射 (只有非单字符的需要特殊映射，zh, ch, sh)
4
  shengmu = {
5
    ["zh"] = "v",
6
    ["ch"] = "i",
7
    ["sh"] = "u",
8
  },
9
  -- 韵母映射
10
  yunmu = {
11
    ["iu"] = "q",
12
    ["ei"] = "w",
13
    ["e"] = "e",
14
    ["uan"] = "r",
15
    ["ue"] = "t", ["ve"] = "t",
16
    ["un"] = "y",
17
    ["u"] = "u", ["v"] = "v",
18
    ["i"] = "i",
19
    ["o"] = "o", ["uo"] = "o",
20
    ["ie"] = "p",
21
    ["a"] = "a",
22
    ["ong"] = "s", ["iong"] = "s",
23
    ["ai"] = "d",
24
    ["en"] = "f",
25
    ["eng"] = "g",
26
    ["ang"] = "h",
27
    ["an"] = "j",
28
    ["uai"] = "k", ["ing"] = "k",
29
    ["iang"] = "l", ["uang"] = "l",
30
    ["ou"] = "z",
31
    ["ua"] = "x", ["ia"] = "x",
32
    ["ao"] = "c",
33
    ["ui"] = "v",
34
    ["in"] = "b",
35
    ["iao"] = "n",
36
    ["ian"] = "m",
37
  }
38
}

我们需要实现一个转换函数，把输入的全拼字符串转换为小鹤双拼编码。这个函数需要分离声母和韵母的，然后根据映射表进行转换。

1
local function convert_single(pinyin)
2
  if pinyin == "" then return "" end
3

4
  local sm = ""
5
  local ym = ""
6

7
  -- 1. 尝试提取声母
8
  for _, s in ipairs(valid_shengmu) do
9
    if vim.startswith(pinyin, s) then
10
      -- 特殊情况：如果提取的声母会导致剩下的部分不是合法韵母，则可能不是这个声母
11
      -- 但中文拼音相对规范，贪婪匹配声母通常是正确的 (zh, ch, sh 优先于 z, c, s)
12
      sm = s
13
      ym = string.sub(pinyin, #s + 1)
14
      break
15
    end
16
  end
17

18
  -- 如果没找到声母，或者声母就是整个字符串（不应该发生，除非只有声母），则认为是零声母
19
  if sm == "" then
20
    ym = pinyin
21
    -- 特殊处理：flash-zh 对于部分零声母韵母，直接使用拼音作为键，而不是小鹤双拼码
22
    local special_zeros = {
23
      ["ai"] = true,
24
      ["an"] = true,
25
      ["ao"] = true,
26
      ["ei"] = true,
27
      ["en"] = true,
28
      ["ou"] = true,
29
      ["er"] = true, -- er 在小鹤里也是 er，这里一并处理
30
    }
31
    if special_zeros[ym] then
32
      return ym
33
    end
34
  end
35

36
  -- 2. 转换声母
37
  local double_sm = ""
38
  if sm == "" then
39
    -- 零声母规则：小鹤双拼中，零声母字的第一个键通常是韵母的首字母
40
    double_sm = string.sub(ym, 1, 1)
41
  else
42
    double_sm = map.shengmu[sm] or sm
43
  end
44

45
  -- 3. 转换韵母
46
  local double_ym = map.yunmu[ym]
47

48
  -- 如果找不到韵母映射，可能输入有误或者是单韵母直接映射
49
  if not double_ym then
50
    -- 容错：如果是单字母，可能就是它自己
51
    if #ym == 1 then double_ym = ym end
52
  end
53

54
  -- 特殊处理：如果没有韵母（例如用户只输了声母），暂不处理或返回声母
55
  if ym == "" then return double_sm end
56

57
  return double_sm .. (double_ym or "")
58
end
59

60
-- 主转换函数
61
-- 输入: "wo ai ni" or "zhongguo" (如果是连写的，这里的简单逻辑可能处理不了，建议空格分隔)
62
function M.to_xiaohe(input_str)
63
  local result = {}
64
  -- 简单的按非字母字符分割（支持空格、标点分隔）
65
  for word in string.gmatch(input_str, "[a-zA-Z]+") do
66
    table.insert(result, convert_single(string.lower(word)))
67
  end
68
  return table.concat(result, "")
69
end

在转换完成之后，我们只需要调用flash-zh.nvim的跳转函数即可。这里需要注意，在使用插件的时候，输入一个字的全拼之后应该使用空格间隔开来，以保证转换的正确性。因为中文拼音连在一起可能会导致歧义的发生，这种情况比较复杂，暂时没有处理。例如用户输入xian的时候，可能是xi an（西安）也可能是xian（先），这两种情况应该区别开来。

1
-- 新增：输入全拼 -> 转双拼 -> 调用 flash-zh
2
function M.input_and_jump()
3
  vim.ui.input({ prompt = "输入全拼 (空格分隔): " }, function(input)
4
    if not input or input == "" then
5
      return
6
    end
7

8
    -- 1. 转换拼音
9
    local xiaohe = require("flash_zh_simple.xiaohe")
10
    local pattern = xiaohe.to_xiaohe(input)
11

12
    print("转换结果: " .. input .. " -> " .. pattern)
13

14
    -- 2. 调用 flash-zh
15
    -- 尝试加载 flash-zh
16
    local has_flash_zh, flash_zh = pcall(require, "flash-zh")
17

18
    -- 如果未找到，尝试将当前目录下的 flash-zh.nvim 加入 rtp (针对开发环境)
19
    if not has_flash_zh then
20
      local cwd = vim.fn.getcwd()
21
      local local_flash_path = cwd .. "/flash-zh.nvim"
22
      if vim.fn.isdirectory(local_flash_path) == 1 then
23
        vim.opt.rtp:prepend(local_flash_path)
24
        has_flash_zh, flash_zh = pcall(require, "flash-zh")
25
      end
26
    end
27

28
    if has_flash_zh then
29
      -- 使用 flash-zh 的 jump 接口
30
      -- 注意：flash-zh 的 jump 封装了 flash.jump，并自动处理模式
31
      -- 我们传入转换后的双拼码，但 flash-zh 默认是用来接收用户输入的
32
      -- 如果我们要直接跳转到 pattern，需要构造正确的 search 配置
33

34
      -- flash-zh 的 jump(opts) 实际上是打开 flash 界面让用户输。
35
      -- 但如果我们已经有了 text (pattern)，我们希望它直接跳。
36

37
      -- 查看 flash-zh 源码，它会调用 flash.jump(opts)。
38
      -- 我们可以直接调用 flash.jump，并复用 flash-zh 的模式。
39

40
      local flash = require("flash")
41
      -- 构造 flash-zh 的正则匹配器
42
      local search_mode = flash_zh.zh_mode -- 纯中文模式
43

44
      flash.jump({
45
        search = {
46
          mode = search_mode,
47
          text = pattern, -- 传入转换后的双拼码，直接搜索
48
        },
49
        label = { after = false, before = true },
50
        pattern = pattern,
51
      })
52
    else
53
      vim.notify("未找到 flash-zh.nvim，仅显示转换结果。", vim.log.levels.WARN)
54
    end
55
  end)
56
end
57

58
return M

另外，其实我的初衷是只想写一个简单的浮动窗口，用来展示小鹤双拼的键位图，方便自己查看。但是后来仔细一想，为什么不多走一步呢？于是我就把这个全拼功能也加了进来，这样一来，这个插件就比较方便像我这样只会使用全拼的用户使用了。尽管已经实现了全拼跳转的功能，但是键位图我还是保留了下来，毕竟双拼的跳转效率还是要高于全拼的。写这个插件的目的也许是让用户逐渐不要使用这个插件，转而使用flash-zh.nvim和双拼跳转，权且把该插件作为一个过渡工具吧。下面是浮动窗口的代码实现，不得不说，Neovim的API设计得还是很不错的，写起来并不复杂。而且Neovim的浮动窗口功能也非常强大，支持各种样式和配置，非常灵活。

1
-- 打开浮动窗口的主函数
2
function M.open()
3
  -- 1. 创建一个不可列出 (unlisted) 的临时缓冲区 (scratch buffer)
4
  -- 参数1: listed (false = 不在 :ls 中显示)
5
  -- 参数2: scratch (true = 这是一个临时 buffer，没有任何文件关联)
6
  local buf = vim.api.nvim_create_buf(false, true)
7

8
  -- 2. 获取编辑器的大小，用于计算居中位置
9
  local ui = vim.api.nvim_list_uis()[1]
10
  local width = 64
11
  local height = 16
12

13
  -- 计算起始行列，使窗口居中
14
  local row = math.floor((ui.height - height) / 2)
15
  local col = math.floor((ui.width - width) / 2)
16

17
  -- 3. 配置窗口选项
18
  local opts = {
19
    relative = "editor", -- 相对于整个编辑器定位
20
    width = width,
21
    height = height,
22
    row = row,
23
    col = col,
24
    style = "minimal", -- 最小化样式（无行号等）
25
    border = "rounded", -- 圆角边框 (也可选 "single", "double", "solid" 等)
26
    title = " 小鹤双拼 (Xiaohe) ", -- 窗口标题 (Neovim 0.9+)
27
    title_pos = "center",
28
  }
29

30
  -- 4. 打开浮动窗口
31
  -- 参数1: buffer id
32
  -- 参数2: enter (true = 焦点立即进入新窗口)
33
  -- 参数3: config table
34
  local win = vim.api.nvim_open_win(buf, true, opts)
35

36
  -- 5. 设置缓冲区内容
37
  local lines = {
38
    " [Q] iu         [W] ei         [E] e          [R] uan",
39
    " [T] ue         [Y] un         [U] sh / u     [I] ch / i",
40
    " [O] uo / o     [P] ie",
41
    "",
42
    " [A] a          [S] ong/iong   [D] ai         [F] en",
43
    " [G] eng        [H] ang        [J] an         [K] uai/ing",
44
    " [L] iang/uang",
45
    "",
46
    " [Z] ou         [X] ua/ia      [C] ao         [V] zh / ui",
47
    " [B] in         [N] iao        [M] ian",
48
    "",
49
    " --------------------------------------------------------",
50
    "  * 零声母：韵母首字母为零声母",
51
    "  * 按 'q' 关闭此窗口",
52
  }
53
  vim.api.nvim_buf_set_lines(buf, 0, -1, false, lines)
54

55
  -- 6. 设置按键映射：在 Normal 模式下按 'q' 关闭窗口
56
  -- 使用 <cmd>close<CR> 是关闭当前窗口最稳健的方法
57
  vim.keymap.set("n", "q", "<cmd>close<CR>", { buffer = buf, noremap = true, silent = true })
58

59
  -- 7. 设置 Buffer 选项：窗口关闭后自动销毁 Buffer
60
  vim.api.nvim_set_option_value("bufhidden", "wipe", { buf = buf })
61

62
  -- 可选：设置一些高亮或选项
63
  vim.api.nvim_set_option_value("cursorline", true, { win = win })
64
end

本插件的文档#

本插件的完整代码和使用文档(含演示视频)可以参考GitHub仓库：AQchance/flash-zh-simple.nvim