在blink.cmp中处理多行文本补全项的显示与匹配问题

问题背景

在使用blink.cmp实现自定义补全源时，开发者可能会遇到多行文本作为补全项的情况。当直接使用多行文本作为补全项的label时，功能可以正常工作。但如果尝试对多行文本进行截断或分割处理，补全菜单中就无法正确显示和匹配这些项。

技术分析

补全项匹配机制

补全引擎在匹配用户输入时，默认会使用label字段作为匹配依据。当开发者对多行文本进行截断处理后，原始的匹配内容可能丢失，导致引擎无法正确识别补全项。

关键字段解析

1. label字段：用于在补全菜单中显示的文本，也是默认的匹配依据
2. filterText字段：专门用于匹配的文本内容，不影响显示
3. insertText字段：实际插入到文档中的内容

解决方案

正确配置补全项

要实现既能显示简洁的label，又能正确匹配多行内容，需要合理配置补全项的各个字段：

{
  label = "截断后的文本",  -- 用于显示的简短文本
  filterText = "完整的多行文本",  -- 用于匹配的原始内容
  insertText = "完整的多行文本$0",  -- 实际插入的内容
  -- 其他字段...
}

实现建议

1. 保持label简洁明了，便于用户快速浏览
2. 将原始多行文本同时赋值给filterText和insertText
3. 对于代码片段，可以使用insertTextFormat指定为片段格式
4. 通过documentation字段提供完整的多行预览

实际应用示例

local items = {}
for _, result in ipairs(data) do
  table.insert(items, {
    label = result:sub(1, 20) .. "...",  -- 显示前20个字符
    filterText = result,  -- 完整内容用于匹配
    insertText = result .. "$0",  -- 插入完整内容
    documentation = {
      kind = "markdown",
      value = "```" .. vim.bo.ft .. "\n" .. result .. "\n```",
    },
    insertTextFormat = 2,  -- 使用片段格式
    kind = require("blink.cmp.types").CompletionItemKind.Snippet,
  })
end

总结