VSCode扩展开发：如何通过API实现类ESLint波浪下划线及文档注释展示

这类波浪下划线的正式名称 #

• 你看到的这种带波浪的文档标记，正式名称是VSCode诊断（Diagnostic），是VSCode语言服务体系内置的标准标记能力。
• 不管是ESLint的代码规范提示、TS内置的类型报错，还是拼写检查扩展的错词提示，全都是基于这个能力实现的。它的交互逻辑是统一的：根据标记的严重级别不同，会渲染为红、黄、蓝、灰不同颜色的波浪下划线，鼠标悬停就会弹出关联的提示文本。

如何通过VSCode API实现和ESLint一致的波浪下划线效果 #

你完全不需要自己写代码在编辑器里绘制波浪线，直接调用VSCode原生的诊断API，就能获得和ESLint一模一样的渲染效果，核心实现流程非常简单：

• 扩展激活的时候，调用vscode.languages.createDiagnosticCollection()创建一个属于自己扩展的诊断集合，相当于给自己的注释标记建一个独立的容器，不会和ESLint、TS等其他扩展的诊断内容混在一起。
• 找到需要加注释的代码范围，构造一个vscode.Diagnostic实例：要传入三个核心参数——标记覆盖的代码范围（vscode.Range）、关联的注释文本、标记的严重级别。给注释类内容选DiagnosticSeverity.Hint就好，对应浅灰色的柔和波浪线，视觉权重低，不会和代码报错、警告的提示混淆。
• 把构造好的诊断列表和对应文档的URI绑定，调用诊断集合的set()方法写进去，VSCode就会自动在对应位置渲染原生的波浪线效果，所有的交互、视觉适配都由VSCode的渲染层处理，不需要额外开发。

简化实现示例代码：

import * as vscode from 'vscode';

// 扩展激活时初始化独立诊断集合
const commentCollection = vscode.languages.createDiagnosticCollection('my-doc-comment');

/**
 * 给指定代码位置添加带波浪线的注释
 */
function addWavyComment(editor: vscode.TextEditor, targetRange: vscode.Range, comment: string) {
  const diagnostic = new vscode.Diagnostic(
    targetRange,
    comment,
    vscode.DiagnosticSeverity.Hint
  );
  // 标记注释来源，会显示在悬停提示的标题位置
  diagnostic.source = '文档注释扩展';
  // 实际使用时需要维护整个文档的诊断列表，避免覆盖其他已有标记
  commentCollection.set(editor.document.uri, [diagnostic]);
}

更适合文档注释场景的可选实现方案 #

纯靠诊断波浪线做注释的逻辑，本质是把注释当成“系统提示类信息”，在部分场景下体验并不是最优的，可以根据你的注释类型选择更贴合需求的实现：

• 诊断标记+自定义悬停组合方案：保留波浪线的视觉关联，但是不要把长注释直接塞在Diagnostic的默认消息里，搭配vscode.languages.registerHoverProvider()自定义悬停弹窗，支持渲染Markdown格式的富文本、代码块、操作按钮，比Diagnostic默认的纯文本弹窗体验好很多，也是ESLint扩展优化提示交互的常用做法。
• 行内装饰器方案：如果是需要长期留存的固定文档注释，可以放弃波浪线的形式，通过vscode.window.createTextEditorDecorationType()创建编辑器装饰器，在代码行的侧边直接展示淡灰色的注释文字，不需要用户鼠标悬停就能看到内容，视觉上更贴近原生的文档注释，也不会和系统的报错、警告提示产生认知上的冲突。
• Code Lens方案：如果你的注释是针对整个函数、类等代码块的说明，可以在代码块上方的行号区域添加淡色的注释摘要，用户点击即可展开查看完整注释，这种方式的可视性比藏在悬停里的波浪线提示强很多，适合做长期维护的文档类注释。

内容的提问来源于stack exchange，提问作者二川村田