自定义右键菜单：配置驱动、上下文感知，和三个隐蔽的坑

起因#

刷别人博客的时候见过几回自定义右键菜单：右键出来的不是浏览器原版那一坨，而是主题自己画的一列选项，前进后退、复制链接、进阅读模式一应俱全。这东西不算必要功能，但点开的那一下很有「这站被人认真打理过」的感觉。决定自己也整一个。

先把想要的形态列清楚：

1. 所有菜单项走配置。加一项、删一项、调顺序，改配置文件就行，不碰组件
2. 右键在哪，菜单不一样。选中文本时出「复制、搜索」，链接上出「新窗口打开、复制地址」，图片上出「打开图片、复制图片地址」
3. 页面能力不同，菜单也不一样。文章页才有「回到评论」，装了音乐播放器才出播放控制，能进阅读模式的页面才给「阅读模式」
4. Ctrl+右键保留原版菜单。不赶尽杀绝，偶尔还得用原版的「检查」
5. 只在桌面端生效。窄屏和触屏没这个交互习惯，小于某个宽度直接放行

清单看着长，落到实现上其实就一句话：菜单内容是动态的，但菜单本身必须是声明式的。

思路：一份配置说了算#

组件被压得很薄——配置决定「有什么」，运行时决定「显示什么、放哪」，CSS 只负责「藏」和「放」。

配置长这样：

1
export const contextMenuConfig: ContextMenuConfig = {
2
  enable: true,
3
  minWidth: 1024,
4
  // 在输入框/文本域/可编辑元素内右键时展示原版菜单
5
  showNativeInEditable: true,
6
  // 搜索选中内容用的搜索引擎，{query} 会被替换成选中文本
7
  searchEngine: "https://www.baidu.com/s?wd={query}",
8
  contextItems: {
9
    copySelection: true, // 有选中文本：复制
10
    searchSelection: true, // 有选中文本：搜索
11
    openLink: true, // 右键链接：新窗口打开
12
    copyLink: true, // 右键链接：复制地址
13
    openImage: true, // 右键图片：打开图片
14
    copyImage: true, // 右键图片：复制地址
15
  },
16
  items: [
17
    { action: "history-back" },
18
    { action: "history-forward" },
19
    { action: "reload", divider: true },
20
    { action: "music-toggle-play" },
21
    { action: "music-prev" },
22
    { action: "music-next" },
23
    { action: "music-volume" },
24
    { action: "toggle-theme", divider: true },
25
    { action: "reading-mode" },
26
    { action: "back-to-comment" },
27
    { action: "back-to-top" },
28
    { action: "copy-url" },
29
  ],
30
};

items 里每项是一个内置 action，divider 控制分组分隔线。想加外链或自定义行为，用 action: "custom" 配 link 或者一段函数体，图标不指定时组件会按 item.icon ?? 默认图标 兜底。类型在 src/types/contextMenuConfig.ts 里收着，配置写错了构建期就能报出来。

早期版本试过直接在模板里堆菜单节点，结果改个顺序要动模板，加一项要动模板，上下文显隐逻辑还散落在各处。收进配置之后，这些痛苦全消失了——这也是我坚持「配置驱动」最大的理由：改配置的心智负担和改组件完全不是一个量级。

拦截：先想清楚什么时候「不管」#

写自定义菜单，最先要想清楚的不是怎么接管，而是什么时候不管。放行条件比拦截条件好写——前者每条都是独立的，后者要把所有反例串成一长串否定。

我的放行条件就三条：

1
document.addEventListener("contextmenu", (e) => {
2
  if (e.ctrlKey) return; // Ctrl+右键：放行原版菜单
3
  if (window.innerWidth < minWidth) return; // 窄屏：没这个交互
4
  const target = e.target instanceof Element ? e.target : null;
5
  const isFormField =
6
    !!target?.closest("input, textarea, select") ||
7
    (target instanceof HTMLElement && target.isContentEditable);
8
  if (isFormField && showNativeInEditable) return; // 输入框里：原版菜单更好用
9
  e.preventDefault();
10
});

流程画出来是这样：

另外两个工程细节：绑定前先检查 window.__fireflyContextMenu 防止重复挂监听（Astro 页面脚本在某些跳转场景会重新执行，不设防会越绑越多）；关菜单的途径比开菜单多得多——点遮罩、Esc、窗口失焦、滚动、resize、路由跳转全都要收尾，其中滚动监听用 capture 加 passive 就够了，反正目的只是把菜单收起来。

这段代码里埋着本篇坑二的祸根，先按下不表。

上下文感知：两组标记类#

探测上下文，说穿了就是把一堆布尔判断折算成根元素上的类名：

1
// 右键位置：点在哪
2
menu.classList.toggle("show-selection", hasSelection);
3
menu.classList.toggle("show-link", !!link);
4
menu.classList.toggle("show-image", !!img);
5
// 页面能力：这页有什么
6
menu.classList.toggle("ctx-has-music", typeof music()?.getState === "function");
7
menu.classList.toggle("ctx-has-comments", !!document.getElementById("post-comments"));
8
menu.classList.toggle("ctx-has-reading", isReadingModeAvailable());

两组前缀语义不同：show-* 描述「右键点在哪」，每次打开都重新探测；ctx-has-* 描述「这个页面有什么能力」。CSS 那边配合很机械——扩展项默认藏起来，标记类出现才放行：

1
#context-menu
2
    .ctx-need-selection
3
        display: none
4
    &.show-selection
5
        .ctx-need-selection
6
            display: flex

注意第三行的 &，它是坑一的主角，后面细说。

能力探测里有几个值得展开的点：

音乐播放器是 Svelte island，把实例挂到 window.__fireflyMusic 上。但 island 水合有时机问题——页面刚开就右键，这个全局对象可能还不存在；就算存在了，也得确认它真能用。所以探测写成 typeof getState === "function" 而不是简单判存在：对象在、方法还没挂上的窗口期里，单纯判存在会误报。

评论区探测最朴素：document.getElementById("post-comments") 找得到节点就有评论。因为评论区只渲染在文章页，这一行天然把「文章页」的语义带上了，不用再判断路径。

阅读模式的判断和站内阅读模式按钮共用同一个谓词：路径在 /posts/ 下且视口够宽。两处逻辑一个标准，避免「按钮说能进、菜单里却没有」的尴尬。

定位：先隐身，量完再现身#

弹出位置看着五分钟搞定，实际有个经典陷阱：菜单贴近屏幕右缘时，音量条那组二级菜单会探出屏幕。等渲染出来再发现溢出，视觉上就是闪一下。

做法是显示之前先隐身量尺寸：

1
const SUBMENU_SPACE = 240; // 给二级菜单留的空间
2

3
menu.classList.remove("hidden", "ctx-flip-left");
4
menu.style.visibility = "hidden";
5
const rect = menu.getBoundingClientRect();
6
const flipLeft = x + rect.width + SUBMENU_SPACE > vw;
7
if (flipLeft) menu.classList.add("ctx-flip-left");
8
menu.style.visibility = "";

关键在用 visibility: hidden 而不是 display: none——前者占据布局、能量出真实尺寸，后者量出来全是 0。量完该翻转就加 ctx-flip-left 让二级菜单朝左开，最后再去掉隐身。整个过程在同一帧内完成，肉眼看不到闪。

明暗适配#

这部分反而最省心：颜色全部走站内 CSS 变量，var(--card-bg)、var(--btn-regular-bg-hover) 这类，主题切换时变量一变菜单自动跟上。唯一手写的是深色模式下的文字颜色，站内惯例是 :global(.dark) 里配一个半透明白，照抄即可。

踩坑清单#

下面按踩到的顺序讲三个坑。共同点是：每一个的现象都在暗示「代码是对的」，而真凶全在别处。

1
#context-menu[data-astro-cid-mdguodk3] .ctx-has-music .ctx-need-music {
2
  display: flex;
3
}

1
<div id="context-menu" class="ctx-has-music" data-astro-cid-mdguodk3>
2
  <div class="ctx-need-music">音量</div>
3
</div>

1
#context-menu
2
    .ctx-has-music
3
        .ctx-need-music
4
            display: flex

1
#context-menu
2
    &.ctx-has-music
3
        .ctx-need-music
4
            display: flex

1
#context-menu[data-astro-cid-mdguodk3].ctx-has-music .ctx-need-music {
2
  display: flex;
3
}

1
if (isFormField && !showNativeInEditable) return; // [!code --]
2
if (isFormField && showNativeInEditable) return; // [!code ++]

写在最后#

右键菜单是典型的「平时没人看，写起来细节不少」的功能。回头看，思路层面就三件事：放行条件先于拦截条件想清楚、状态折算成标记类交给 CSS、量完尺寸再显示。剩下的坑大多出在源码和运行时之间的那些层上——Stylus 会编译选择器，Astro 会改写选择器，preview 伺服的是历史产物。每一层都在帮忙，也都在让你离真相远一步。

主题完整代码在这里：