VSCode自定义语言中配置DocumentSymbol实现粘性滚动的方法

问题现象 #

自定义VSCode语言扩展中，已在language-configuration.json添加folding: {offSide: true}，但粘性滚动仅生效一秒，大纲面板加载后立即消失。尝试使用new vscode.DocumentSymbol处理textDocument/documentSymbol请求，未达到预期效果。

核心问题点 #

你的代码存在三个关键问题：

1. SymbolKind不匹配：使用vscode.SymbolKind.Field作为标题类符号的类型，VSCode粘性滚动对不同符号类型的处理逻辑不同，非标题类符号无法有效触发粘性滚动。
2. 范围设置错误：将符号的range和selectionRange都设为当前行范围，粘性滚动需要符号覆盖自身及所有子内容的完整范围，仅单行范围无法让VSCode识别对应的粘性区域。
3. 缺少层级结构：平级添加符号而非通过children数组构建嵌套层级，导致大纲和粘性滚动无法识别内容的层级关系。

修正步骤 #

1. 替换正确的SymbolKind #

将符号类型改为vscode.SymbolKind.Heading，匹配标题类内容的语义：

new vscode.DocumentSymbol(
  name,
  "Heading",
  vscode.SymbolKind.Heading, // 替换为Heading类型
  line.fullRange,
  line.lineRange
);

2. 修正符号范围 #

• range：设置为当前标题到下一个同级标题（或文档末尾）的完整范围，包含该标题下的所有子内容。
• selectionRange：设置为标题所在行的范围，用于点击大纲时快速定位到标题行。

3. 构建正确的层级结构 #

如果语言存在嵌套层级（比如缩进的子内容），将子符号添加到父符号的children数组中，而非平级推入symbols数组。示例代码：

const symbols = [];
let currentParent = null;

// 假设lines是按顺序解析的标题行，包含name、lineRange（标题行范围）、fullRange（标题+子内容范围）、level（层级）
for (const line of lines) {
  const symbol = new vscode.DocumentSymbol(
    line.name,
    "Heading",
    vscode.SymbolKind.Heading,
    line.fullRange,
    line.lineRange
  );

  if (line.level === 1) {
    // 顶级标题直接加入根数组
    symbols.push(symbol);
    currentParent = symbol;
  } else {
    // 子标题添加到对应父级的children中
    currentParent.children.push(symbol);
    currentParent = symbol;
  }
}

return symbols;

4. 验证兼容性 #

• 临时注释documentSymbolProvider的注册代码，测试粘性滚动是否正常。如果正常，说明问题确实出在符号提供逻辑上。
• 确保language-configuration.json中的folding设置与符号范围逻辑兼容，offSide模式依赖缩进层级，符号的fullRange需正确覆盖对应缩进区域。

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