如何为VSCode扩展添加自定义自动补全项排序规则？

本文共计2512个文字，预计阅读时间需要11分钟。

VSCode扩展需要提供自定义的自动补全项排序规则，核心在于巧妙地利用CompletionItem对象中的sortText和filterText属性。VSCode的自动补全机制会根据这些属性来确定最终的显示顺序。因此，作为扩展开发者，我们的主要任务是通过精确设置这些值来指引最终展示的顺序。

解决方案

要实现自定义的自动补全项排序，关键在于为每个

CompletionItem设置其

sortText属性。这个属性是一个字符串，VSCode会根据它的字典序（lexicographical order）来对补全项进行排序。这意味着，如果你希望某个补全项排在前面，就给它的

sortText赋予一个字典序上靠前的字符串值。

例如，你可以使用数字前缀来控制优先级：

"0_exactMatch"会排在

"1_commonItem"之前，而

"1_commonItem"又会排在

"2_lessUsed"之前。通过这种方式，我们可以将最相关、最常用的补全项“顶”到列表顶部，而将那些次要的、或需要用户进一步思考的项排在后面。

filterText则主要用于匹配用户输入，它决定了哪些补全项会被显示出来。虽然它不直接参与最终的排序，但在某些情况下，如果

sortText缺失，VSCode可能会回退到使用

filterText进行辅助排序。但通常，我们更多地依赖

sortText来精确控制顺序。

VSCode自动补全的默认排序逻辑是怎样的？

在没有明确指定

sortText的情况下，VSCode的自动补全功能有一套自己的默认排序逻辑，这套逻辑通常是基于以下几个因素综合判断的：

首先，它会优先考虑与用户当前输入字符串匹配度最高的项。这包括了前缀匹配、子串匹配，以及一些模糊匹配算法。如果一个补全项的

label（或者

filterText）能完全匹配用户输入，那它的优先级自然会很高。

其次，

CompletionItemKind也会在一定程度上影响排序。比如，函数（

Function）、变量（

Variable）或类（

Class）通常会比文本（

Text）或文件（

File）等通用类型获得更高的权重。这是一种语义上的优先级，VSCode认为在编程语境下，代码结构相关的补全项更有价值。

再者，如果多个项的匹配度和类型都相似，VSCode可能会回退到按

label的字典序进行排序。这意味着，即使你没有设置

sortText，你的补全项也会有一个相对稳定的默认顺序。

我个人觉得，理解这个默认逻辑非常重要，因为这能帮助我们判断什么时候需要介入自定义排序，以及如何最小化地进行干预，以达到最佳效果。有时候，默认行为已经足够好，我们就不必画蛇添足了。

如何通过

sortText实现精确控制自动补全的显示顺序？

要精确控制自动补全的显示顺序，

sortText就是我们的核心工具。它的工作原理其实很简单：VSCode会取所有符合当前输入条件的补全项，然后按照它们

sortText的字符串字典序进行排序。所以，我们只需要精心构造这些字符串即可。

一个非常实用的策略是使用数字前缀结合语义标识。比如：

import * as vscode from 'vscode'; export class MyCompletionProvider implements vscode.CompletionItemProvider { public provideCompletionItems( document: vscode.TextDocument, position: vscode.Position, token: vscode.CancellationToken, context: vscode.CompletionContext ): vscode.ProviderResult<vscode.CompletionItem[] | vscode.CompletionList> { const items: vscode.CompletionItem[] = []; // 最常用的函数，优先级最高 const createItem = new vscode.CompletionItem('createObject', vscode.CompletionItemKind.Function); createItem.detail = '创建一个新的对象实例'; createItem.sortText = '0_createObject'; // 数字越小，排序越靠前 items.push(createItem); // 常用变量，优先级次之 const configItem = new vscode.CompletionItem('config', vscode.CompletionItemKind.Variable); configItem.detail = '全局配置对象'; configItem.sortText = '1_config'; items.push(configItem); // 不太常用的辅助函数 const helperItem = new vscode.CompletionItem('formatData', vscode.CompletionItemKind.Function); helperItem.detail = '格式化数据'; helperItem.sortText = '2_formatData'; items.push(helperItem); // 甚至可以根据上下文动态生成sortText // 比如，如果用户正在输入一个特定类型的属性，可以提升该类型相关项的优先级 if (document.lineAt(position.line).text.includes('user.')) { const userNameItem = new vscode.CompletionItem('name', vscode.CompletionItemKind.Property); userNameItem.detail = '用户姓名'; userNameItem.sortText = '0_userName'; // 在特定上下文中，这个属性可能比其他项更重要 items.push(userNameItem); } return items; } }

这里，

"0_createObject"会排在

"1_config"之前，而

"1_config"又排在

"2_formatData"之前。即使它们在字母表顺序上并非如此，

sortText也强制了它们的显示顺序。这种方法非常灵活，你可以根据自己的需求设计不同的前缀，甚至结合字母来进一步细分同优先级下的排序。比如，

"0_a_alpha"会排在

"0_b_beta"之前。

filterText在自动补全过滤和排序中扮演什么角色？

filterText和

sortText虽然都是字符串，但它们在自动补全流程中扮演的角色是不同的，但又互补。简单来说，

filterText主要负责“过滤”，而

sortText主要负责“排序”。

当用户输入字符时，VSCode会使用

filterText（如果未指定，则回退到

label）来判断当前输入的字符串是否与某个补全项匹配。只有匹配成功的项才会被显示在补全列表中。例如，你可能有一个补全项的

label是

"My Awesome Component"，但它的实际组件名是

"my-awesome-component"。这时，你可以设置

filterText为

"my-awesome-component"。这样，当用户输入

"my-awesome"时，

"My Awesome Component"就会被匹配并显示出来，即使

label本身没有完全匹配。

filterText的作用在于提供一个备用的、或者说是更“匹配友好”的字符串，让用户能够通过不同的输入方式找到同一个补全项。它解决了

label可能不够灵活，或者不适合直接作为匹配目标的问题。

一旦通过

filterText过滤出了一组补全项，接下来才是

sortText登场，对这组已过滤的项进行优先级排序。所以，你可以把

filterText看作是进入补全列表的“门槛”，而

sortText则是列表内部的“排位赛”。它们各自承担着不同的职责，共同构成了VSCode强大而灵活的自动补全体验。

结合用户习惯和上下文，优化自动补全排序的策略有哪些？

优化自动补全排序，不仅仅是静态地设置

sortText，更高级的玩法是结合用户习惯和当前的编程上下文，动态地调整补全项的优先级。这能让补全功能变得更加智能和贴心。

一个很直接的策略是基于使用频率的动态排序。我们可以记录用户在当前工作区或项目中对哪些补全项使用得更多。比如，一个函数

logInfo()在一个项目中被频繁调用，那么它的

sortText就可以动态调整为

"0_logInfo"，使其在补全列表中更靠前。当然，这需要扩展具备一定的状态管理能力，来存储和更新这些使用数据。

上下文敏感的排序也是一个非常强大的方向。例如：

1. 根据导入模块：如果当前文件导入了

   lodash库，那么

   lodash相关的函数（如

   _.map,

   _.filter）就应该比其他不相关库的函数拥有更高的优先级。

2. 根据光标位置：当光标在一个对象属性访问的后面（例如

   user.），我们应该优先推荐

   user对象可能拥有的属性（如

   name,

   age），而不是全局函数。这需要我们解析AST或依赖语言服务器提供的语义信息。

3. 类型推断：如果语言服务器能够推断出当前位置期望的类型（比如，一个函数参数期望一个

   string），那么补全列表应该优先显示字符串常量或返回字符串的函数。

4. 智能推荐：这可能更复杂，涉及到一些简单的模式识别。比如，如果用户刚定义了一个

   const users = []，接下来输入

   users.时，可能就会推荐

   push,

   map,

   filter等数组方法。

实现这些策略，往往需要我们的扩展与VSCode的语言服务器协议（LSP）深度结合，或者在扩展内部进行更复杂的代码分析。这不仅仅是技术层面的挑战，更是对用户体验设计的一次深入思考。我的经验是，即便是最简单的上下文感知，比如根据当前文件中的

import语句来提升相关项的优先级，也能显著提升开发效率和用户满意度。毕竟，没有人喜欢在长长的补全列表中大海捞针。