electron窗口层级与dock窗口列表

背景与目标

• Dock 右键菜单中不显示已打开窗口列表（只留系统项）。
• 悬浮/面板类窗口在“全屏应用之上”，但“系统截图 UI 之下”。
• 需要时可切换成“可截图/不可截图”。

最小实现结论（TL;DR）

1. Dock 右键不列窗口：在需要隐藏的窗口上设置 excludedFromShownWindowsMenu = true 即可。
   • skipTaskbar 与 hiddenInMissionControl 可选，用于更彻底隐藏在任务栏/Mission Control；但“是否出现在 Dock 的窗口列表”主要由 excludedFromShownWindowsMenu 决定。
2. 全屏之上、截图之下：
   • win.setAlwaysOnTop(true, 'status')
   • win.setVisibleOnAllWorkspaces(true, { visibleOnFullScreen: true })
   • macOS 下 type: 'panel'

代码要点

Hover 窗口（面板类）：

hiddenInMissionControl: true,
skipTaskbar: true,
type: process.platform === 'darwin' ? 'panel' : undefined,
...
win.setAlwaysOnTop(true, 'status')
win.setVisibleOnAllWorkspaces(true, { visibleOnFullScreen: true })
win.excludedFromShownWindowsMenu = true

Panel 窗口（面板类）：

skipTaskbar: true,
hiddenInMissionControl: true,
type: process.platform === 'darwin' ? 'panel' : undefined,
...
win.setAlwaysOnTop(true, 'status')
win.setVisibleOnAllWorkspaces(true, { visibleOnFullScreen: true })
win.excludedFromShownWindowsMenu = true

Mini 悬浮球：

win.setVisibleOnAllWorkspaces(true, { visibleOnFullScreen: true })
win.setAlwaysOnTop(true, process.platform === 'darwin' ? 'status' : 'normal')
win.excludedFromShownWindowsMenu = true

主窗口（不强制置顶，避免压过系统 UI）：

// 主窗不再强制置顶，避免压过系统层级（如截图 UI）
win.setAlwaysOnTop(false)
win.setVisibleOnAllWorkspaces(true, { visibleOnFullScreen: true })

win.excludedFromShownWindowsMenu = true

设置/激活窗口（同样隐藏窗口菜单项）：

win.hide()
win.excludedFromShownWindowsMenu = true

win.excludedFromShownWindowsMenu = true

可选强化（按需开启）

• 完全从 Dock 列表/Mission Control 中消失：
  • 在已用 excludedFromShownWindowsMenu = true 的基础上，再补充 skipTaskbar: true 与 hiddenInMissionControl: true。
• 个别全屏 App 仍覆盖你的面板：
  • 将层级短暂抬到 'pop-up-menu' 再观察；避免使用 'screen-saver'（会压过截图 UI）。
• 不被截图/录屏：
  • win.setContentProtection(true)（粒度可到单窗口）。

验证清单

• Dock 右键只显示系统项（选项/显示所有窗口/隐藏/退出），不列已打开窗口。
• 打开任意 App 全屏，mini/hover/panel 仍可见。
• 截图（⌘+Shift+5/4）时：系统截图 UI 不被遮挡；当前默认可被拍到（未开内容保护）。
• Mission Control 里不展示这些面板的缩略图（若启用了 hiddenInMissionControl）。

踩坑与经验

• 仅 skipTaskbar 不足以控制 Dock 的窗口列表展示；核心是 excludedFromShownWindowsMenu。
• 层级建议用 'status'，满足“全屏之上 + 截图之下”的平衡；除非遇到特例再尝试 'pop-up-menu'。
• 记得与 setVisibleOnAllWorkspaces(true, { visibleOnFullScreen: true }) 搭配，否则全屏桌面不可见。
• macOS 上 type: 'panel' 能明显改善面板类窗口的交互与层级表现。

这套“最小实现”足以覆盖 IM/AI 工具常见的悬浮交互场景，也便于在不同窗口上按需启用/关闭“可截图/不可截图”的策略。