如何为VSCode设置一个自定义的代码透镜（CodeLens）提供程序？

betcha

发布时间：2025-09-21 22:37:01

813人浏览过

来源于php中文网

原创

答案：自定义CodeLens提供程序需实现接口并注册，通过正则匹配或AST解析在代码上方显示可操作标签，适用于展示版本控制、测试状态等上下文信息。

如何为vscode设置一个自定义的代码透镜（codelens）提供程序？

要在VSCode里搞定一个自定义的代码透镜（CodeLens）提供程序，说白了，就是得写一个VSCode扩展。核心在于实现

CodeLensProvider

这个接口，然后把它注册到VSCode的语言服务里。这玩意儿能让你在代码行上方，像小标签一样显示一些上下文信息或者可执行的命令，挺有意思的。

解决方案

搞一个自定义的CodeLens提供程序，其实没想象中那么玄乎，但确实需要一点点耐心去理解VSCode扩展的套路。

初始化项目： 首先，你需要一个VSCode扩展的脚手架。如果你还没装
```
yo code
```
，先
```
npm install -g yo generator-code
```
。然后跑
```
yo code
```
，选“New Extension (TypeScript)”，一路回车，给你的扩展起个名字，比如
```
my-custom-codelens
```
。

package.json

配置： 打开生成的

package.json

文件。这里有几个关键点：

```
activationEvents
```
：告诉VSCode你的扩展什么时候被激活。对于CodeLens，通常是当某个语言文件被打开时。比如，如果你想在TypeScript文件里显示CodeLens，可以写
```
"onLanguage:typescript"
```
。
```
contributes.commands
```
：如果你的CodeLens需要执行一个命令（比如点击后跳转、运行测试），你得在这里声明这个命令。
```
contributes.languages
```
：虽然不是直接为CodeLens配置，但它定义了你的扩展支持哪些语言，间接影响CodeLens的显示。

// package.json 示例
{
  "name": "my-custom-codelens",
  "displayName": "My Custom CodeLens",
  "version": "0.0.1",
  "engines": {
    "vscode": "^1.80.0"
  },
  "categories": [
    "Other"
  ],
  "activationEvents": [
    "onLanguage:typescript", // 当TypeScript文件打开时激活
    "onCommand:myCustomCodelens.doSomething" // 当特定命令被执行时激活
  ],
  "main": "./out/extension.js",
  "contributes": {
    "commands": [
      {
        "command": "myCustomCodelens.doSomething",
        "title": "执行我的自定义操作"
      }
    ]
  },
  "scripts": {
    "vscode:prepublish": "npm run compile",
    "compile": "tsc -p ./",
    "watch": "tsc -watch -p ./",
    "pretest": "npm run compile && npm run lint",
    "lint": "eslint src --ext ts",
    "test": "node ./out/test/runTest.js"
  },
  "devDependencies": {
    "@types/vscode": "^1.80.0",
    "@types/node": "^18.17.1",
    "@typescript-eslint/eslint-plugin": "^6.4.1",
    "@typescript-eslint/parser": "^6.4.1",
    "eslint": "^8.47.0",
    "typescript": "^5.1.6"
  }
}

实现

CodeLensProvider

：这是核心逻辑所在。在

src/extension.ts

里，你需要创建一个类来实现

vscode.CodeLensProvider

接口。这个接口有两个主要方法：

provideCodeLenses

和

resolveCodeLens

。

```
provideCodeLenses(document: vscode.TextDocument, token: vscode.CancellationToken)
```
：这个方法是VSCode用来“扫描”文档，找出哪些地方应该显示CodeLens的。你需要遍历文档内容，根据你的逻辑（比如正则匹配、AST解析等）来创建
```
vscode.CodeLens
```
对象。每个
```
CodeLens
```
对象至少需要一个
```
range
```
（它将显示在哪一行代码的上方）。为了性能考虑，你可以在这里只返回带有
```
range
```
的
```
CodeLens
```
，而将实际的
```
command
```
（标题和要执行的动作）留到
```
resolveCodeLens
```
里处理。
```
resolveCodeLens?(codeLens: vscode.CodeLens, token: vscode.CancellationToken)
```
：这个方法是可选的，但非常推荐实现。当VSCode需要显示CodeLens时，它会按需调用这个方法来“解析”CodeLens，填充它的
```
command
```
属性。这样做的好处是，当文档很大或者CodeLens很多时，可以避免一次性计算所有CodeLens的完整信息，从而提高性能和响应速度。

// src/extension.ts 示例
import * as vscode from 'vscode';

// 定义一个正则表达式，用于匹配我们想要添加CodeLens的特定模式
// 比如，我们想在所有包含 "TODO:" 的行上方显示一个CodeLens
const TODO_REGEX = /(TODO:)\s*(.*)/g;

class MyCodeLensProvider implements vscode.CodeLensProvider {
    // 当文档内容变化或CodeLens需要刷新时，VSCode会调用这个方法
    public provideCodeLenses(document: vscode.TextDocument, token: vscode.CancellationToken): vscode.ProviderResult {
        const codeLenses: vscode.CodeLens[] = [];
        const text = document.getText();
        let match;

        // 遍历文档，查找所有匹配我们正则表达式的行
        while ((match = TODO_REGEX.exec(text)) !== null) {
            // 获取匹配到的行的位置
            const line = document.lineAt(document.positionAt(match.index).line);
            const range = new vscode.Range(line.range.start, line.range.end);

            // 创建一个CodeLens对象。注意，这里我们暂时不设置command，留给resolveCodeLens处理
            if (range) {
                codeLenses.push(new vscode.CodeLens(range));
            }
        }
        return codeLenses;
    }

    // VSCode会按需调用这个方法来填充CodeLens的command
    public resolveCodeLens(codeLens: vscode.CodeLens, token: vscode.CancellationToken): vscode.ProviderResult {
        // 在这里，我们可以根据CodeLens的range，获取对应行的文本
        // 然后根据文本内容，决定CodeLens要显示什么标题和执行什么命令
        const lineText = vscode.window.activeTextEditor?.document.getText(codeLens.range);

        if (lineText?.includes("TODO:")) {
            codeLens.command = {
                title: `找到一个待办事项: ${lineText.trim().substring(5)}`, // 显示CodeLens的标题
                command: 'myCustomCodelens.doSomething', // 点击CodeLens时执行的命令
                arguments: [lineText] // 命令的参数
            };
        }
        return codeLens;
    }
}

// 激活扩展的入口点
export function activate(context: vscode.ExtensionContext) {
    console.log('Congratulations, your extension "my-custom-codelens" is now active!');

    // 注册CodeLens提供程序
    // 'typescript' 是语言ID，确保和 package.json 中的 activationEvents 匹配
    context.subscriptions.push(vscode.languages.registerCodeLensProvider(
        { language: 'typescript', scheme: 'file' }, // 也可以是 ['typescript', 'javascript'] 等数组
        new MyCodeLensProvider()
    ));

    // 注册一个命令，供CodeLens点击时调用
    context.subscriptions.push(vscode.commands.registerCommand(
        'myCustomCodelens.doSomething',
        (todoText: string) => {
            vscode.window.showInformationMessage(`你点击了待办事项: ${todoText}`);
            // 在这里可以实现更复杂的逻辑，比如打开一个新的文件、跳转到某个位置等
        }
    ));
}

// 当你的扩展被禁用时，会调用这个方法
export function deactivate() {}

调试和测试： 按下F5，VSCode会打开一个新的“扩展开发主机”窗口。在这个新窗口里打开一个TypeScript文件，随便写几行带
```
TODO:
```
的注释，你就能看到CodeLens在行上方出现了。点击它，看看命令是否正确执行。

这套流程走下来，一个基本的自定义CodeLens就搭起来了。实际应用中，你可能需要更复杂的逻辑来解析代码，但核心思路就是这样。

自定义CodeLens有哪些实际应用场景？

说实话，CodeLens这东西，用好了简直是提升开发体验的神器。它把一些原本需要你手动查找或切换上下文才能获取的信息，直接“钉”在代码旁边，减少了认知负担。

在我看来，最实用的场景包括：

版本控制信息： 比如显示当前行代码的Git提交者、提交时间和提交信息。想象一下，你不用再开Git Blame视图，直接在代码行上方就能看到是谁在什么时候改了这行，多方便。很多IDE都有类似功能，VSCode通过扩展也能实现。
测试状态和运行： 对于单元测试，CodeLens可以直接显示某个测试用例的通过/失败状态，甚至提供一个点击就能运行该测试的按钮。这对于TDD或者快速验证代码改动非常有帮助。
引用计数与实现： 显示一个函数、类或接口被引用了多少次，或者一个接口有多少个实现。点击CodeLens可以直接跳转到所有引用或实现的地方。这在大型代码库中，快速理解代码影响范围时特别有用。
性能指标： 在某些特定代码块（比如数据库查询、API调用）上方显示其平均执行时间。这需要一些运行时数据收集，但一旦集成，就能直观地看到代码的性能瓶颈。
文档链接与外部资源： 如果你的代码中使用了某个库的特定API，CodeLens可以提供一个链接，直接跳转到该API的官方文档。这比在浏览器里搜索快多了。
TODO/FIXME管理： 就像我们示例里做的，把代码里的
```
TODO
```
、
```
FIXME
```
等标记变成可点击的CodeLens，点击后可以快速打开一个任务管理工具，或者标记为已完成。
代码覆盖率： 在测试报告中，CodeLens可以显示每行代码是否被测试覆盖，或者覆盖率百分比。

总的来说，CodeLens的价值在于它提供了一种“即时上下文”的信息展示方式，让开发者能更专注于代码本身，同时又不会错过重要的辅助信息。

如何避免CodeLens导致VSCode卡顿？

性能问题，尤其是在VSCode这种高频使用的工具里，是绝对不能忽视的。CodeLens如果写得不好，确实可能让VSCode变得迟钝。这方面，有几个关键点我觉得特别重要：

善用
```
resolveCodeLens
```
：这几乎是CodeLens性能优化的黄金法则。
```
provideCodeLenses
```
应该尽可能快地返回CodeLens的
```
range
```
信息，而把计算CodeLens的
```
command
```
（标题、参数等）的耗时操作放到
```
resolveCodeLens
```
里。VSCode会按需、异步地调用
```
resolveCodeLens
```
，这样可以避免在文档加载时一次性计算所有CodeLens的完整信息，大大减少首次加载和滚动时的卡顿。
高效地扫描文档：
- 避免全文档正则匹配： 如果你的逻辑是基于正则匹配的，尽量限制匹配的范围，或者使用更高效的正则表达式。对于超大文件，全文档正则匹配是性能杀手。
- 增量更新： 如果可能，只处理文档中发生变化的部分。虽然
```
provideCodeLenses
```
  每次都会收到整个文档，但你可以内部维护一个状态，只对修改过的行进行重新计算。
- AST解析： 对于复杂的语言结构，使用抽象语法树（AST）解析器通常比正则表达式更准确也更高效，因为它理解代码的结构，而不是简单的文本模式。但引入AST解析器也会增加扩展的复杂性和依赖。
异步操作： 确保你的CodeLens提供程序中的任何潜在耗时操作都是异步的（例如，网络请求、文件I/O）。使用
```
async/await
```
，并确保不会阻塞主线程。
```
vscode.CancellationToken
```
也很有用，可以在用户快速滚动或切换文件时取消正在进行的计算。
限制CodeLens数量： 如果一个文件中有成百上千个CodeLens，即使每个CodeLens的计算量很小，累积起来也会造成性能问题。考虑对CodeLens的数量进行限制，或者只在用户关注的特定区域显示。

Avactis购物车
Avactis是一个强大的PHP在线购物系统拥有多个版本包括开源版本。它具备一个在线购物系统所需要的所有功能从产品到会员管理，订单和营销。可以无限分类和为产品指定任务数量的图片（支持自动生成缩略图）。使用自定义字段功能，让你可以更好地定义一个产品。该系统提供以非常灵活的方式来创建任意类型的促销活动如设置折扣代码，基于价格的折扣或基于数量的折扣等。

下载
内存管理： 避免在
```
provideCodeLenses
```
或
```
resolveCodeLens
```
中创建大量临时对象，尤其是在循环内部。注意内存泄漏，确保不再需要的资源被正确释放。
Debounce和Throttle： 如果你的CodeLens逻辑需要在用户输入时频繁更新，考虑使用
```
debounce
```
或
```
throttle
```
技术来限制更新频率。例如，当用户键入时，不是每次按键都重新计算CodeLens，而是在用户停止输入一段时间后再计算。

总之，CodeLens的性能优化，很大程度上就是权衡“即时性”和“资源消耗”。优先保证用户界面的流畅性，然后才是信息的丰富度。

CodeLens与Hover、Diagnostic有什么区别？

在VSCode里，有多种方式可以给开发者提供上下文信息，CodeLens、Hover和Diagnostic就是其中最常用的三种。它们各自有其特点和最佳使用场景，了解它们的区别能帮助你选择最合适的扩展点。

CodeLens (代码透镜)
- 展示位置： 直接显示在代码行的上方，像一个小标签或提示。
- 交互性： 通常是可点击的，点击后可以执行一个命令（比如跳转、运行测试、显示更多信息）。
- 特点：
  - 主动性： 信息是“推”给用户的，无需用户主动触发。
  - 上下文关联： 紧密关联到它所在的特定代码行。
  - 动作导向： 往往提供一个快速操作的入口。
- 最佳用途： 适用于提供即时、可操作的上下文信息，比如 Git blame 信息、测试运行/状态、引用计数、快速导航链接。
Hover (悬停提示)
- 展示位置： 当鼠标悬停在代码元素（变量、函数、类等）上时，弹出一个小窗口显示信息。
- 交互性： 通常是只读的，但可以包含链接，点击后跳转到其他地方。
- 特点：
  - 被动性： 需要用户主动将鼠标悬停才能触发。
  - 详细信息： 适合展示较多的、详细的、解释性的信息。
  - 按需获取： 信息是“拉”给用户的，只在需要时才显示。
- 最佳用途： 适用于显示类型定义、函数签名、文档注释、错误详情、变量值等，这些信息通常比较丰富，不适合直接显示在代码行上方。
Diagnostic (诊断信息)
- 展示位置： 在代码编辑器中以波浪线、下划线等形式标记出来，同时在“问题”面板（Problems panel）中列出所有诊断信息。
- 交互性： 通常不可点击，但点击问题面板中的条目可以跳转到代码位置。某些诊断可以通过“快速修复”（Quick Fix）功能提供建议操作。
- 特点：
  - 问题导向： 主要用于报告代码中的错误、警告、信息或提示。
  - 持久性： 诊断信息会一直显示，直到问题解决。
  - 全局视图： “问题”面板提供了一个所有问题的集中视图。
- 最佳用途： 适用于静态代码分析、Linting、编译器错误、语法错误、潜在的运行时问题等，这些信息需要被开发者关注并修复。