如何使用VSCode扩展API实现自定义gutter指示器功能

实现方案 #

基于VS Code现有Decoration能力，搭配编辑器事件监听、鼠标绑定规则即可实现和断点逻辑一致的交互效果，具体实现如下：

1. 定义两类装饰类型 #

分别定义悬停时的虚影装饰、点击后生效的正式指示器装饰：

const vscode = require('vscode');
const path = require('path');
// 存储所有已放置的指示器范围
let pinnedRanges = [];
// 悬停虚影装饰：使用半透明图标，仅悬停时临时显示
const hoverDecorationType = vscode.window.createTextEditorDecorationType({
  gutterIconPath: path.join(__filename, "../..", "assets", "pin-transparent.png"),
  gutterIconSize: "contain",
  rangeBehavior: vscode.DecorationRangeBehavior.ClosedOpen
});
// 正式放置的指示器装饰：保留你现有在用的样式
const pinDecorationType = vscode.window.createTextEditorDecorationType({
  isWholeLine: true,
  borderWidth: `0 0 0 0`,
  backgroundColor: new vscode.ThemeColor("checkbox.border"),
  gutterIconPath: path.join(__filename, "../..", "assets", "pin.png"),
  gutterIconSize: "contain",
  rangeBehavior: vscode.DecorationRangeBehavior.ClosedOpen,
});

2. 监听光标位置，更新虚影显示 #

通过监听编辑器光标位置变化，实时把虚影装饰更新到当前悬停的行：

let activeEditor = vscode.window.activeTextEditor;
// 监听激活编辑器切换
vscode.window.onDidChangeActiveTextEditor(editor => {
  activeEditor = editor;
  if (editor) updateHoverDecoration(editor);
});
// 监听光标位置变化，更新虚影显示位置
vscode.window.onDidChangeTextEditorSelection(e => {
  if (e.textEditor === activeEditor) {
    updateHoverDecoration(e.textEditor);
  }
});
// 更新虚影装饰的位置
function updateHoverDecoration(editor) {
  const currentLine = editor.selection.active.line;
  const hoverRange = new vscode.Range(currentLine, 0, currentLine, 0);
  editor.setDecorations(hoverDecorationType, [hoverRange]);
}

3. 绑定gutter点击事件，实现放置/取消逻辑 #

在扩展的package.json中添加鼠标点击绑定规则，仅当点击gutter区域时触发放置命令：

{
  "contributes": {
    "keybindings": [
      {
        "command": "your-extension-id.add-pin-indicator",
        "key": "mouse1",
        "when": "editorTextFocus && isInGutter"
      }
    ]
  }
}

在扩展代码中注册对应的放置命令：

vscode.commands.registerCommand('your-extension-id.add-pin-indicator', () => {
  if (!activeEditor) return;
  const currentLine = activeEditor.selection.active.line;
  const newPinRange = new vscode.Range(currentLine, 0, currentLine, 0);
  const lineHasPin = pinnedRanges.some(range => range.start.line === currentLine);
  if (!lineHasPin) {
    pinnedRanges.push(newPinRange);
    activeEditor.setDecorations(pinDecorationType, pinnedRanges);
  } else {
    // 点击已放置的行时删除指示器，和断点取消逻辑一致
    pinnedRanges = pinnedRanges.filter(range => range.start.line !== currentLine);
    activeEditor.setDecorations(pinDecorationType, pinnedRanges);
  }
});

相关API查询说明 #

可在VS Code官方扩展API文档中搜索以下关键词查看详细规则：

• TextEditorDecorationType 装饰类型定义
• onDidChangeTextEditorSelection 编辑器选择变化事件
• Keybinding When Clause 快捷键触发条件规则

内容的提问来源于stack exchange，提问作者Neo