VSCode的扩展如何贡献自定义的自动补全项排序规则？-VSCode-PHP中文网

答案：通过设置CompletionItem的sortText属性可自定义VSCode自动补全排序，其值按字典序决定优先级，数字前缀如"0\_abc"可使项靠前；filterText用于匹配输入但不直接参与排序；默认排序依据匹配度、CompletionItemKind和label字典序；结合上下文（如导入模块、光标位置）动态调整sortText能优化体验。

vscode的扩展如何贡献自定义的自动补全项排序规则？

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

登录后复制

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

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

Tellers AI

Tellers是一款自动视频编辑工具，可以将文本、文章或故事转换为视频。

查看详情

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"

登录后复制

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

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

根据导入模块：如果当前文件导入了
```
lodash
```
登录后复制
库，那么
```
lodash
```
登录后复制
相关的函数（如
```
_.map
```
登录后复制
,
```
_.filter
```
登录后复制
）就应该比其他不相关库的函数拥有更高的优先级。
根据光标位置：当光标在一个对象属性访问的后面（例如
```
user.
```
登录后复制
），我们应该优先推荐
```
user
```
登录后复制
对象可能拥有的属性（如
```
name
```
登录后复制
,
```
age
```
登录后复制
），而不是全局函数。这需要我们解析AST或依赖语言服务器提供的语义信息。
类型推断：如果语言服务器能够推断出当前位置期望的类型（比如，一个函数参数期望一个
```
string
```
登录后复制
），那么补全列表应该优先显示字符串常量或返回字符串的函数。
智能推荐：这可能更复杂，涉及到一些简单的模式识别。比如，如果用户刚定义了一个
```
const users = []
```
登录后复制
，接下来输入
```
users.
```
登录后复制
时，可能就会推荐
```
push
```
登录后复制
,
```
map
```
登录后复制
,
```
filter
```
登录后复制
等数组方法。