如何为VSCode设置一个自定义的自动补全提供程序？-VSCode-PHP中文网

如何为vscode设置一个自定义的自动补全提供程序？

为VSCode设置自定义的自动补全提供程序，最直接且功能强大的方式就是开发一个VSCode扩展（Extension）。这听起来可能有点复杂，但说白了，就是利用VSCode提供的Extension API，告诉它在特定场景下应该给出哪些补全建议。它不像你想象的那么遥不可及，更多的是一个结构化的编程任务，用TypeScript或JavaScript就能搞定。核心思想是注册一个“补全项提供者”，让VSCode在用户输入时调用你的逻辑，然后返回你预设好的补全列表。

解决方案

如果你想让VSCode理解一些它本身不认识的特定语法，或者为某个内部项目提供超个性化的代码提示，那么自己动手写一个扩展是必经之路。这过程其实挺有意思的，就像是给VSCode“训练”一个新的语言模型。

首先，你需要一个脚手架来创建扩展项目。VSCode官方推荐使用

yo code

登录后复制

这个工具。

安装Yeoman和VSCode Extension Generator:
```
npm install -g yo generator-code
```
登录后复制
创建新的扩展项目:
```
yo code
```
登录后复制
按照提示选择“New Extension (TypeScript)”或“New Extension (JavaScript)”。我个人更倾向于TypeScript，类型检查能省不少心。

核心逻辑编写 (

src/extension.ts

登录后复制

或
extension.js
登录后复制
): 打开项目后，你会看到一个

extension.ts

登录后复制

（或

.js

登录后复制

）文件，这是扩展的入口。我们需要在这里注册我们的补全提供者。

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
    console.log('你的自定义补全扩展已激活！');

    // 注册一个补全项提供者
    // 这里我们以纯文本文件为例，你可以根据需要修改selector
    const provider = vscode.languages.registerCompletionItemProvider(
        { scheme: 'file', language: 'plaintext' }, // 语言选择器：匹配所有scheme为'file'且语言为'plaintext'的文件
        {
            provideCompletionItems(document: vscode.TextDocument, position: vscode.Position, token: vscode.CancellationToken, context: vscode.CompletionContext) {
                const linePrefix = document.lineAt(position).text.substr(0, position.character);
                // 假设我们想在输入 'my-' 后提供自定义补全
                if (!linePrefix.endsWith('my-')) {
                    return undefined; // 如果不匹配，则不提供补全
                }

                // 创建补全项
                const item1 = new vscode.CompletionItem('my-custom-value', vscode.CompletionItemKind.Value);
                item1.detail = '这是一个自定义的值';
                item1.documentation = new vscode.MarkdownString('这个值可以用于配置某些特定参数。');

                const item2 = new vscode.CompletionItem('my-function-call', vscode.CompletionItemKind.Function);
                item2.insertText = new vscode.SnippetString('myFunction(${1:arg})'); // 支持代码片段
                item2.detail = '调用我的自定义函数';
                item2.documentation = '这是一个用于执行特定操作的函数。';

                return [item1, item2];
            },

            // 这是一个可选的方法，用于在用户选中补全项后，延迟加载更详细的信息
            // 对于性能优化很有用，尤其是当补全项的详细信息需要耗时计算或网络请求时
            resolveCompletionItem(item: vscode.CompletionItem, token: vscode.CancellationToken) {
                // 可以在这里异步获取更多信息并更新item
                // 例如：item.documentation = '加载了更多详细说明...';
                return item;
            }
        },
        '-' // triggerCharacters: 当用户输入'-'时，会触发补全
    );

    // 将提供者添加到扩展的订阅中，以便在扩展停用时自动清理
    context.subscriptions.push(provider);
}

export function deactivate() {} // 扩展停用时执行的逻辑

登录后复制

```
package.json
```
登录后复制
配置: 在
```
package.json
```
登录后复制
文件中，你需要确保
```
activationEvents
```
登录后复制
包含了你的补全提供者所针对的语言。例如，如果你针对的是
```
plaintext
```
登录后复制
，可以添加：
```
"activationEvents": [
    "onLanguage:plaintext"
],
"contributes": {
    // 这里可以定义一些其他贡献点，比如命令、配置等
}
```
登录后复制
```
onLanguage:plaintext
```
登录后复制
意味着只有当VSCode打开一个
```
plaintext
```
登录后复制
文件时，你的扩展才会被激活。
测试: 按下
```
F5
```
登录后复制
键，VSCode会打开一个新的“Extension Development Host”窗口。在这个新窗口中，创建一个
```
plaintext
```
登录后复制
文件，然后输入
```
my-
```
登录后复制
，你应该就能看到你的自定义补全建议了。

开发VSCode自定义补全扩展需要哪些核心API和步骤？

要开发一个VSCode自定义补全扩展，核心在于理解和运用VSCode的Extension API。最关键的API就是

vscode.languages.registerCompletionItemProvider

登录后复制

。它就像是VSCode向你开放的一个插槽，让你能把自己的补全逻辑“插”进去。

步骤上，我们通常会经历以下几个环节：

项目初始化： 使用
```
yo code
```
登录后复制
工具快速生成一个标准的VSCode扩展项目结构。这会帮你省去很多配置上的麻烦，直接进入代码编写阶段。
定义激活事件 (
package.json
登录后复制
)：在
```
package.json
```
登录后复制
里，
```
activationEvents
```
登录后复制
字段至关重要。它告诉VSCode你的扩展应该在什么时候被激活。比如，
```
onLanguage:yourLanguageId
```
登录后复制
意味着只有当用户打开了特定语言的文件时，你的扩展才会被加载。合理设置激活事件可以避免不必要的资源占用，提升VSCode的整体性能。
注册补全提供者 (
extension.ts/.js
登录后复制
)：这是核心。通过调用
```
vscode.languages.registerCompletionItemProvider(selector, provider, ...triggerCharacters)
```
登录后复制
来注册你的补全逻辑。
- ```
selector
```
  登录后复制
  ：一个
```
DocumentSelector
```
  登录后复制
  对象，用来指定你的补全提供者适用于哪些文件。它可以基于语言ID（
```
language
```
  登录后复制
  ）、文件路径模式（
```
pattern
```
  登录后复制
  ）甚至URI方案（
```
scheme
```
  登录后复制
  ）来匹配。
- ```
provider
```
  登录后复制
  ：一个实现了
```
CompletionItemProvider
```
  登录后复制
  接口的对象。这个对象里最重要的方法是
```
provideCompletionItems
```
  登录后复制
  ，它负责根据当前文档内容和光标位置，返回一个
```
CompletionItem
```
  登录后复制
  数组。
- ```
triggerCharacters
```
  登录后复制
  ：可选参数，一个字符串数组。当用户输入这些字符时，会立即触发你的
```
provideCompletionItems
```
  登录后复制
  方法。这对于一些特定语法（如
```
.
```
  登录后复制
  、
```
:
```
  登录后复制
  、
```
-
```
  登录后复制
  等）后的补全非常有用。
实现
provideCompletionItems
登录后复制
方法：这个方法是你的补全逻辑所在地。它接收当前文档(
```
document
```
登录后复制
)、光标位置(
```
position
```
登录后复制
)、取消令牌(
```
token
```
登录后复制
)和补全上下文(
```
context
```
登录后复制
)作为参数。你需要在方法内部分析这些信息，比如获取光标前的文本，然后根据你的规则生成
```
vscode.CompletionItem
```
登录后复制
对象数组并返回。
- ```
vscode.CompletionItem
```
  登录后复制
  ：每个
```
CompletionItem
```
  登录后复制
  代表一个补全建议。你需要设置它的
```
label
```
  登录后复制
  （显示给用户的文本）、
```
kind
```
  登录后复制
  （图标类型，如
```
Method
```
  登录后复制
  、
```
Property
```
  登录后复制
  、
```
Value
```
  登录后复制
  等）、
```
insertText
```
  登录后复制
  （实际插入到文档的文本，可以是
```
string
```
  登录后复制
  或
```
SnippetString
```
  登录后复制
  ）、
```
detail
```
  登录后复制
  （简短描述）和
```
documentation
```
  登录后复制
  （详细文档，支持Markdown）。
（可选）实现
resolveCompletionItem
登录后复制
方法：这个方法在用户选中某个补全项但还未插入时被调用。它的作用是允许你延迟加载或计算更详细的补全信息（比如完整的文档或复杂的代码示例）。这对于性能优化非常关键，可以避免在每次
```
provideCompletionItems
```
登录后复制
调用时都做大量计算。
订阅和清理： 在
```
activate
```
登录后复制
函数中，将
```
registerCompletionItemProvider
```
登录后复制
返回的
```
Disposable
```
登录后复制
对象添加到
```
context.subscriptions
```
登录后复制
中。这样，当扩展被停用时，VSCode会自动清理掉你注册的资源。

坦白讲，理解这些API的参数和返回值，以及如何根据不同的输入场景构建

CompletionItem

登录后复制

，是整个开发过程的核心。一旦掌握了这些，自定义补全的想象空间就非常大了。

如何处理不同文件类型或特定上下文的自动补全逻辑？

处理不同文件类型或特定上下文的自动补全逻辑，是让你的扩展变得智能和实用的关键。这主要通过两个层面来实现：语言选择器（

selector

登录后复制

）和 provideCompletionItems
登录后复制
内部的逻辑判断。

利用
```
selector
```
登录后复制
精确匹配文件类型： 在
```
vscode.languages.registerCompletionItemProvider
```
登录后复制
的第一个参数
```
selector
```
登录后复制
中，你可以定义非常精细的匹配规则。
- 按语言ID匹配： 这是最常见的，例如
```
{ language: 'typescript' }
```
  登录后复制
  、
```
{ language: 'json' }
```
  登录后复制
  。VSCode内置了许多语言ID，你也可以为自定义语言注册ID。
- 按URI方案匹配：
```
scheme: 'file'
```
  登录后复制
  表示只对本地文件系统中的文件生效；
```
scheme: 'untitled'
```
  登录后复制
  表示对未保存的新文件生效。
- 按文件路径模式匹配：
```
pattern: '**/*.myconfig'
```
  登录后复制
  可以匹配所有以
```
.myconfig
```
  登录后复制
  结尾的文件，无论它们是什么语言ID。
- 组合匹配： 你可以将这些条件组合起来，例如
```
{ language: 'json', pattern: '**/package.json' }
```
  登录后复制
  ，只对项目根目录下的
```
package.json
```
  登录后复制
  文件提供补全。
- 多重选择器：
```
[ { language: 'json' }, { pattern: '**/*.mydata' } ]
```
  登录后复制
  允许你的提供者同时为JSON文件和
```
.mydata
```
  登录后复制
  文件服务。
通过合理设置
```
selector
```
登录后复制
，可以确保你的补全逻辑只在它应该生效的文件类型上运行，避免不必要的干扰。
```
provideCompletionItems
```
登录后复制
内部的上下文分析： 即使
```
selector
```
登录后复制
已经过滤了文件类型，很多时候我们还需要根据光标周围的文本环境来提供更智能的补全。在
```
provideCompletionItems
```
登录后复制
方法中，你可以利用
```
document
```
登录后复制
和
```
position
```
登录后复制
对象来获取和分析当前上下文。
- 获取当前行文本：
```
const line = document.lineAt(position);
const linePrefix = line.text.substring(0, position.character);
```
  登录后复制
  通过分析
```
linePrefix
```
  登录后复制
  ，你可以判断用户当前正在输入什么，例如是否在某个特定关键字之后，或者是否在一个字符串字面量内部。
- 分析整个文档：
```
const fullText = document.getText();
// 进一步解析fullText，例如使用正则表达式或自定义解析器
```
  登录后复制
  对于更复杂的补全，比如基于文档中已定义的变量或函数名提供补全，你可能需要解析整个文档。但要注意，频繁地解析整个文档可能会影响性能，需要考虑缓存机制。
- 判断光标位置的语法结构： 如果你的扩展是针对一种结构化的语言，你可能需要一个轻量级的解析器（或者仅仅是正则表达式）来判断光标当前是在一个键名位置、一个值位置，还是在一个数组元素中。例如，在一个自定义的配置文件中：
```
config: {
    "key1": "value1",
    "key2": | // 光标在这里，我们知道应该建议键名
}
```
  登录后复制
  这需要你根据
```
linePrefix
```
  登录后复制
  以及前面的行来推断当前的语法上下文。我通常会写一些小的辅助函数，来判断当前光标是否在一个字符串内部、一个对象键值对的左侧还是右侧。
  
  ShopWind网店系统
  ShopWind网店系统是国内最专业的网店程序之一，采用ASP语言设计开发，速度快、性能好、安全性高。ShopWind网店购物系统提供性化的后台管理界面，标准的网上商店管理模式和强大的网店软件后台管理功能。ShopWind网店系统提供了灵活强大的模板机制，内置多套免费精美模板，同时可在后台任意更换，让您即刻快速建立不同的网店外观。同时您可以对网模板自定义设计，建立个性化网店形象。ShopWind网
  
  0
  
  查看详情

通过这种组合拳，即外部的

selector

登录后复制

进行粗粒度过滤，内部的逻辑进行细粒度上下文分析，你就能构建出既精准又高效的自定义补全逻辑。这就像是给VSCode装上了“火眼金睛”，让它能根据不同的场景给出最恰当的提示。

自定义补全的性能优化与常见陷阱有哪些？

开发自定义补全提供者，性能优化和避开常见陷阱是保证用户体验的关键。一个卡顿的补全体验，会比没有补全更让人抓狂。

性能优化：

```
provideCompletionItems
```
登录后复制
要快： 这是最核心的一点。
```
provideCompletionItems
```
登录后复制
方法会被频繁调用，尤其是在用户快速输入时。
- 避免同步的重度计算： 在这个方法里，尽量不要做耗时的文件I/O、网络请求或复杂的同步解析。如果必须，考虑将这些操作移到
```
resolveCompletionItem
```
  登录后复制
  中，或者在扩展激活时预加载/缓存数据。
- 数据缓存： 如果你的补全数据是静态的或变化不频繁，在扩展激活时一次性加载并缓存起来。这样每次调用
```
provideCompletionItems
```
  登录后复制
  时，可以直接从内存中获取。
- 增量解析： 对于需要解析整个文档才能提供补全的场景，不要每次都从头解析。考虑使用增量解析（如果你的语言服务支持）或只解析光标附近的上下文。
- 限制补全项数量： 返回的
```
CompletionItem
```
  登录后复制
  数量不宜过多，否则VSCode渲染列表也会有开销。如果补全项非常多，考虑根据用户输入进行更严格的过滤。
善用
```
resolveCompletionItem
```
登录后复制
：这是VSCode提供的一个非常棒的优化机制。
- 在
```
provideCompletionItems
```
  登录后复制
  中，你只需要返回带有
```
label
```
  登录后复制
  和
```
kind
```
  登录后复制
  等基本信息的
```
CompletionItem
```
  登录后复制
  。
- 将
```
detail
```
  登录后复制
  、
```
documentation
```
  登录后复制
  等需要耗时获取的详细信息，留到
```
resolveCompletionItem
```
  登录后复制
  中处理。只有当用户真正选中（或悬停在）某个补全项时，
```
resolveCompletionItem
```
  登录后复制
  才会被调用。这大大减少了不必要的计算。
精确的
```
triggerCharacters
```
登录后复制
：避免设置过多的
```
triggerCharacters
```
登录后复制
。每一个触发字符都会导致
```
provideCompletionItems
```
登录后复制
被调用。只设置那些真正能触发有意义补全的字符。

常见陷阱：

补全项
```
insertText
```
登录后复制
不准确：
```
insertText
```
登录后复制
是实际插入到文档中的文本。如果它不正确，可能会导致插入的代码语法错误或格式混乱。
- 使用
```
SnippetString
```
  登录后复制
  可以插入带占位符和光标位置的代码片段，这对于函数调用、代码块等非常有用。
- 注意
```
range
```
  登录后复制
  属性：如果你想替换掉光标前的部分文本，而不是简单地插入，可以设置
```
CompletionItem.range
```
  登录后复制
  来指定替换范围。
```
CompletionItemKind
```
登录后复制
选择不当： 不同的
```
CompletionItemKind
```
登录后复制
（如
```
Function
```
登录后复制
、
```
Variable
```
登录后复制
、
```
Keyword
```
登录后复制
、
```
Class
```
登录后复制
等）对应不同的图标，能帮助用户快速理解补全项的类型。选择最符合语义的
```
kind
```
登录后复制
，能提升用户体验。
与其他扩展冲突： 如果多个扩展为同一种语言提供了补全，VSCode会尝试合并它们。但有时可能会出现意料之外的顺序或重复。这通常不是你的扩展能直接解决的问题，但了解这一点有助于排查问题。
调试困难： VSCode扩展的调试环境（Extension Development Host）与普通应用有所不同。
- 使用
```
console.log
```
  登录后复制
  是调试
```
provideCompletionItems
```
  登录后复制
  和
```
resolveCompletionItem
```
  登录后复制
  最直接的方式，输出会显示在“调试控制台”中。
- 学会设置断点，逐步执行代码，观察变量状态。
资源未清理： 虽然VSCode通常会处理好扩展停用时的资源清理，但如果你手动创建了文件观察器、定时器等，记得在
```
deactivate
```
登录后复制
函数中手动清理它们，避免内存泄漏。