VS Code扩展：异步Hover Provider无法显示悬停内容如何解决？

核心问题分析 #

你遇到的问题主要集中在三个点：

• 返回格式不规范：VS Code的Hover对象要求contents必须是字符串数组、MarkdownString实例或MarkdownString数组，直接返回数据库原始查询结果（比如对象）无法被识别渲染。
• 未实现悬停文本提取：你的代码没有获取用户悬停的字符串，根本没法完成“以悬停字符串为键查询数据库”的核心需求。
• Provider优先级被覆盖：内置或其他扩展的Hover Provider优先级更高，导致你的结果被屏蔽。

分步解决方案 #

1. 提取悬停位置的目标文本 #

先通过VS Code API获取用户悬停的单词，作为数据库查询的键：

const wordRange = document.getWordRangeAtPosition(position);
if (!wordRange) return; // 无有效悬停单词时直接返回
const hoverKey = document.getText(wordRange);

2. 返回符合规范的Hover结构 #

必须返回标准Hover对象，contents建议用MarkdownString包装，支持富文本显示：

// 单段内容
return new vscode.Hover(new vscode.MarkdownString(dbResult));
// 多段内容（数组形式）
return new vscode.Hover([
  new vscode.MarkdownString(`**查询键**: ${hoverKey}`),
  new vscode.MarkdownString(`**结果**: ${dbResult}`)
]);

3. 处理异步操作的取消信号 #

利用传入的token监听用户取消悬停的操作，避免无效的数据库请求：

if (token.isCancellationRequested) {
  return;
}

4. 提高Provider优先级（可选） #

如果你的Provider被其他扩展覆盖，注册时设置更高优先级：

vscode.languages.registerHoverProvider('javascript', {
  async provideHover(document, position, token) {
    // 逻辑代码
  }
}, { priority: 1 }); // 数值越大优先级越高

完整修正代码示例 #

const queryByKey = (key: string): Promise<string> => {
  return new Promise((resolve, reject) => {
    // 替换为你的数据库查询逻辑，用hoverKey作为查询参数
    connection.query('SELECT content FROM your_table WHERE `key` = ?;', [key], (error: any, results: any) => {
      if (error) {
        return reject(error);
      }
      resolve(results[0]?.content || '未找到匹配内容');
    });
  });
};

vscode.languages.registerHoverProvider('javascript', {
  async provideHover(document, position, token) {
    // 获取悬停文本
    const wordRange = document.getWordRangeAtPosition(position);
    if (!wordRange) return;
    const hoverKey = document.getText(wordRange);

    // 监听取消信号
    if (token.isCancellationRequested) return;

    try {
      // 执行数据库查询
      const dbResult = await queryByKey(hoverKey);
      // 返回标准Hover对象
      return new vscode.Hover(new vscode.MarkdownString(`**查询结果**: ${dbResult}`));
    } catch (err) {
      console.error('数据库查询失败:', err);
      return new vscode.Hover(new vscode.MarkdownString('查询出错，请查看控制台日志'));
    }
  }
}, { priority: 1 });

调试技巧 #

• 打开VS Code的“输出”面板，切换到你的扩展日志，排查是否有报错信息。
• 先将数据库查询替换为固定字符串，验证Hover能否正常显示，再逐步接入真实查询逻辑。

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