VSCode书签悬停内容无法自定义,因Bookmarks插件未注册HoverProvider且书签非AST节点;唯一实用方案是使用命名书签配合侧栏列表预览代码行。

VSCode 默认不支持为书签(Bookmark)添加自定义悬停说明(Hover Tooltip),Bookmarks 插件本身不提供 hover 文本配置项,所有书签图标悬停时只显示固定格式的 file:line 信息,无法注入 JSDoc、注释或用户定义文本。
为什么书签悬停内容不能像函数那样用 JSDoc 控制
书签是编辑器侧边栏(gutter)的 UI 标记,不是语言语义节点——它不关联 AST、不参与类型检查,也不触发 LSP 的 provideHover。VSCode 的 hover 系统只响应语言服务器或扩展注册的 HoverProvider,而 Bookmarks 插件没注册该能力,也未暴露 API 给其他扩展劫持书签 hover 行为。
- 你写的
/** @description ... */注释对书签 hover 完全无效 - 即使给某行加了命名书签(如
auth-init),悬停时仍只显示index.ts:42 - 插件作者明确表示:hover 内容硬编码在 UI 层,无配置入口(见 GitHub issue #327)
唯一可行的变通方案:用命名书签 + 侧栏预览代替悬停
虽然不能改悬停,但 Bookmarks 插件的侧栏列表(Bookmarks: List Bookmarks)会显示每条书签的命名和**代码行片段**,这比默认 hover 更实用:
- 打命名书签:
Ctrl+Alt+Shift+K(Win/Linux)→ 输入db-connect-timeout - 打开侧栏:
Ctrl+Shift+P→ 输入Bookmarks: List Bookmarks - 列表中每项含文件名、行号、以及该行前导空格+代码文本(最多约 60 字符)
- 悬停侧栏条目时,VSCode 会显示完整代码行 tooltip —— 这是 VSCode 原生的“列表项 hover”,不可定制但足够看清上下文
想真正自定义悬停?只能自己写扩展注册 HoverProvider
如果你必须让鼠标悬停书签图标时显示自定义文字(比如从注释提取、或读取配置),就得开发一个轻量扩展,监听 gutter click/hover 事件并手动注入 tooltip。但这要绕过插件限制,且有明显缺陷:
- VSCode 不允许扩展直接监听 gutter 图标 hover,只能监听整个 editor 区域的
onDidChangeTextEditorSelection或onDidMouseMove,再手动判断位置是否靠近书签图标 —— 容易误触、性能差 - 返回的
Hover对象必须绑定到某个Range,而书签没有对应 Range(它只是装饰器),你得伪造一个覆盖行首的 range,导致悬停区域错位 - 需重复实现书签状态同步(比如用户删了书签,你的 hover 还挂着旧信息)
-
documentSelector必须匹配当前文件 languageId,否则registerHoverProvider根本不生效 —— 这点极易配错(比如 .ts 文件要用typescript,不是javascript)
真要这么做,核心陷阱只有一个:VSCode 的 gutter 图标不是文档内容的一部分,任何 hover 都是“模拟”的,稳定性和维护成本远高于收益。日常开发中,老老实实用命名书签 + 侧栏预览,是最省心、最可靠的选择。











