fix(remote-desktop): 修复 macOS 全屏后工具栏无法唤出 by dashhuang · Pull Request #5466 · makecindy/cindy

dashhuang · 2026-10-05T02:46:00Z

这次改了什么

摘要

桌面版远程桌面窗口在 macOS 全屏后，顶部工具栏会收起，只留 8px 的感应条，原本靠 CSS :hover 唤出。但工具栏整体是 -webkit-app-region: drag，Electron 的拖拽区不会把指针事件交给页面，:hover 永远不触发；同时鼠标触顶时 macOS 菜单栏会滑下覆盖顶端。结果是工具栏一旦收起就回不来，只能退出全屏。

本 PR：

全屏时工具栏改为 -webkit-app-region: no-drag（全屏下没有窗口可拖）。
展开改为指针驱动：指针到达顶端 8px 内即展开；指针停在工具栏范围或移到 macOS 菜单栏上时保持展开，只有移回远程画面（工具栏高度 + 16px 以下）才收起。
原有设置面板 / 下拉框打开、工具栏 :focus-within 时保持展开的规则不变。

变更类型

范围

关联 Issue / 需求：用户反馈「Mac 下远程桌面全屏后菜单栏消失，回不来，除非取消全屏」
本 PR 包含：远程桌面查看窗口全屏工具栏的唤出 / 收起逻辑与对应测试
明确不包含：非全屏窗口的工具栏与拖拽行为、手机端远程桌面
用户可见变化：macOS 全屏远程桌面时，鼠标移到屏幕顶端即可唤出工具栏，向下移回画面后自动收起
是否存在 breaking change：无

UI 变化

不涉及新视觉：工具栏外观、尺寸、动画（150ms translateY，reduced-motion 下无动画）沿用原实现，仅修复唤出条件。平台：macOS 全屏。

引用的设计规范：DESIGN.md §8 Window & Adaptive Behavior（Desktop Window：窗口状态变化下控件保持可达）；颜色与层级继续使用原 --surface / --border-default 语义 token，Light / Dark 行为一致，未新增颜色。

怎么验证的

自动验证

pnpm test:unit:related
结果：PASS apps/desktop unit（related 3 files）

pnpm --dir apps/desktop exec vitest run src/renderer/features/remote-desktop/__tests__/viewerWindow.test.tsx
结果：7 passed（新增：触顶展开、停在工具栏 / 系统菜单栏区域保持展开、移回画面收起）

NODE_OPTIONS=--max-old-space-size=8192 npx tsc --noEmit -p apps/desktop/tsconfig.json
结果：0 errors

npx prettier --check <改动文件>
结果：通过

手工验证

未完成，见下。

未执行的验证

macOS 真机全屏远程桌面的实机验证尚未执行（需连接另一台设备），待 review 期间补测。
Light / Dark 实机目检未执行；本 PR 未改动任何颜色或主题相关样式。

风险

风险分类

影响与回滚

影响范围：仅远程桌面查看窗口在 macOS 全屏状态下（useMacFullscreen 非 mac 恒为 false，Windows / 非全屏行为不变）。
回滚 / 降级方式：直接 revert 本 PR，恢复原 :hover 唤出逻辑。

提交前检查

已 review 完整 diff
每个 commit 都带 DCO 签名（git commit -s，见 DCO）
UI 改动已在「UI 变化」注明引用的设计规范章节（不涉及 UI 则跳过）
未提交凭证、令牌或授权文件
已核对受影响的文档，行为变化涉及的旧结论已同步修订（不涉及则无需修改文档）
已确认测试结果或说明未执行原因

全屏时工具栏收起后只靠 :hover 展开，但工具栏是 -webkit-app-region: drag，拖拽区不会收到指针事件；同时 macOS 菜单栏会滑下覆盖顶端。全屏时取消拖拽区，改为指针触顶展开、移回画面区域才收起。 Signed-off-by: Dash <125997726+dashhuang@users.noreply.github.com>

chatgpt-codex-connector · 2026-10-05T02:46:11Z

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-05T02:49:15.585631Z	`45d01ef`	PR opened
🔒 Security Review	✅ Completed 2026-10-05T02:49:27.948878Z	`45d01ef`	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

greptile-apps · 2026-10-05T02:48:42Z

Confidence Score: 4/5

[Medium risk] Fixes toolbar visibility in fullscreen remote desktop mode.

暂不建议合并；需确认并解决 macOS 菜单栏覆盖顶端时工具栏仍可能无法唤出的问题。

Findings

顶端事件可能无法触发唤出 ▶
测试绕过顶端事件条件 ▶

Fix with agent prompt

### Issue 1
apps/desktop/src/renderer/features/remote-desktop/RemoteDesktopViewerWindow.tsx:82
如果 macOS 全屏菜单栏覆盖窗口顶部后，页面收不到顶端 8px 内的指针移动事件，工具栏就无法通过鼠标唤出。这里仅在收到 `clientY <= 8` 的 `pointermove` 时展开工具栏，而收起后也只露出顶端 8px；因此菜单栏遮挡时，用户可能仍需退出全屏才能使用工具栏。需要不依赖这块被遮挡区域接收事件的唤出方式。

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

### Issue 2
apps/desktop/src/renderer/features/remote-desktop/__tests__/viewerWindow.test.tsx:394
测试直接向 `window` 派发 `clientY=4` 的事件，只验证页面收到事件后会展开工具栏，没有验证 macOS 菜单栏出现时页面能否收到该事件。这会让测试通过，却仍无法确认用户在全屏下能唤出工具栏；建议补充真机验证并记录菜单栏展开时的结果。

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

本 PR 将 macOS 全屏远程桌面工具栏改为非拖拽区域，并以顶端指针移动控制展开与收起。

工具栏原有的设置、下拉框和焦点保持展开规则继续保留。
当前唤出仍依赖系统菜单栏可能覆盖的顶端 8px；新增测试未验证这一实际事件路径。

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[全屏工具栏收起] --> B{页面收到顶端 8px 指针移动?}
  B -- 是 --> C[展开工具栏]
  B -- 菜单栏覆盖，未收到 --> A
  C --> D{指针移至工具栏高度 + 16px 以下?}
  D -- 是 --> A
  D -- 否 --> C

_{Reviews (1) · Last reviewed commit: "fix(remote-desktop): 修复 macOS 全屏后工具栏无法唤出"}

MagicLizi

PR #5466 独立代码审查报告（standard 档）

head=45d01efbf5c633fc0ea027e110e29a4fc1a1c82d base=75516649929fdbb8948f36cd40e08ebd1197bc17（main）
diffHash=32b74f071e8f05712ff2aab148f629af66b98e332ea5cb6a2194539bc258d6bc

Findings

无。没有 P0/P1。

审查过程中的定性记录（非 Findings）：

greptile bot 评论提到「macOS 菜单栏覆盖顶端时可能无法唤出」（soft flag，非 thread，两条
greptile thread 均已 Resolve）。核对实现：指针上移过程中先经过 clientY <= 8 的触顶判定
（早于系统菜单栏接管指针），展开后只有指针移回画面（工具栏高度 + 16px 以下）才收起，
菜单栏滑下覆盖顶端期间没有满足收起条件的 pointermove，工具栏保持展开；新回归测试覆盖了
该三段路径。属设计内权衡，不构成可复现 P1。
UI 证据缺失（format.uiEvidenceMissing=true）：按非阻断提醒规则处理，不打回；PR「UI 变化」
已注明不涉及新视觉，本 PR 未改颜色/尺寸/动画。
P2 级观察（不报告、不阻断）：远程会话内拖拽（viewerInput 的 pointer capture）指针移向
本地屏幕顶端时也会触发工具栏展开覆盖画面顶部；与原 :hover 方案同级别的固有权衡，仅影响
macOS 全屏。

Rule coverage

按 rule-map 命中路径（apps/desktop/src/renderer/**、UI 改动）读取原文：

AGENTS.md + docs/dev-rules/development-workflow.md（严重度口径、PR 模板事实源）：
diff 单一目的（修复 macOS 全屏工具栏唤出），Title/Description 与 diff、测试完全一致，
无夹带；验证一节如实标注未执行项（macOS 真机、Light/Dark 目检）。逐项结论：通过。
docs/dev-rules/electron-security-and-process-boundaries.md §8 Review 清单：
1. Renderer 无新增特权数据/能力（仅 DOM 指针监听 + 一个 data-* 属性）；2-6) 未触碰
  BrowserWindow/WebView/preload/IPC/CSP/Fuses；7) 无新增安全边界；8) 不涉及独立辅助窗口。
  -webkit-app-region: no-drag 仅在 .remote-viewer-fullscreen 作用域内生效，非全屏拖拽
  行为不变（useMacFullscreen 非 mac 恒 false，Windows/非全屏行为不变，与 PR 风险说明一致）。
  逐项结论：通过。
docs/dev-rules/engineering-conventions.md Review 清单：
1. 无新增日志；2-4) 无 IPC/main 侧改动；5) 行为差异被限制在 macOS 全屏，PR 风险字段已声明
  跨平台差异并给出回滚方式，未实测平台已标注；6) 无新增 UI 文案（无 i18n key 变动）；
2. 新增常量带职责注释；8) 动画未改动（150ms translateY，prefers-reduced-motion 原样保留），
  状态切换通过 data-revealed + transform 完成，compositor-only、无跳变。逐项结论：通过。
docs/design-rules/DESIGN.md（UI 改动强制）：不涉及颜色 token、字号、圆角、组件替换或新
视觉，仅交互唤出/收起行为与全屏下 drag region 修正；无硬编码颜色绕过 token、无自造组件。
逐项结论：通过。
共享符号/调用方追踪：useMacFullscreen（未改动）语义一致；CSS :hover 选择器仅被
.remote-viewer-fullscreen .remote-viewer-toolbar 一处使用，改为 [data-revealed='true']
无其他读方；toolbar ref 局部使用；错误/回滚路径无涉（revert 即回原 :hover）。
测试覆盖：viewerWindow.test.tsx 新增触顶展开/保持/收起回归，viewerInput 等 11 个
remote-desktop 测试文件全数通过。

Verification

在本 PR worktree（HEAD=45d01efb）实际执行：

pnpm install --prefer-offline                          → exit 0（15.1s）
npx vitest run .../__tests__/viewerWindow.test.tsx     → 7 passed（exit 0）
npx vitest run src/renderer/features/remote-desktop    → 11 files / 132 tests passed（exit 0）
pnpm --filter desktop run typecheck                    → 0 errors（exit 0）
node scripts/pre-merge-check.mjs 5466 ...              → head/authority/CI/thread 全部核验通过，
                                                          唯一 blocker = 缺另一位维护者 Approve（预期）

未执行：heavy 档专项（本 PR 为 standard 档，不适用）；macOS 真机全屏实测与 Light/Dark 目检
（PR 已如实标注未执行，diff 未触及颜色/主题，UI 证据缺失按非阻断提醒规则处理）。

Overall

pass — 没有 P0/P1。0 条 P0、0 条 P1。

dashhuang requested a review from a team as a code owner October 5, 2026 02:46

greptile-apps Bot reviewed Oct 5, 2026

View reviewed changes

Comment thread apps/desktop/src/renderer/features/remote-desktop/RemoteDesktopViewerWindow.tsx

Comment thread apps/desktop/src/renderer/features/remote-desktop/__tests__/viewerWindow.test.tsx

MagicLizi added status:awaiting-bot-review 等外部审查机器人表态(review-pr 自动维护,仅展示) touches:product-ui 改动碰到产品 / UI 面(review-pr 自动维护,仅展示) labels Oct 5, 2026

MagicLizi approved these changes Oct 5, 2026

View reviewed changes

MagicLizi merged commit 9959ef4 into main Oct 5, 2026
19 checks passed

MagicLizi removed the status:awaiting-bot-review 等外部审查机器人表态(review-pr 自动维护,仅展示) label Oct 5, 2026

Navigation Menu

fix(remote-desktop): 修复 macOS 全屏后工具栏无法唤出 - #5466

fix(remote-desktop): 修复 macOS 全屏后工具栏无法唤出#5466
MagicLizi merged 1 commit into
mainfrom
dash/remote-desktop-fullscreen-menubar

dashhuang commented Oct 5, 2026

Uh oh!

chatgpt-codex-connector Bot commented Oct 5, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot commented Oct 5, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

MagicLizi left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

dashhuang commented Oct 5, 2026

这次改了什么

摘要

变更类型

范围

UI 变化

怎么验证的

自动验证

手工验证

未执行的验证

风险

风险分类

影响与回滚

提交前检查

Uh oh!

chatgpt-codex-connector Bot commented Oct 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codex Review Summary

Uh oh!

greptile-apps Bot commented Oct 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Confidence Score: 4/5

Findings

Uh oh!

Uh oh!

Uh oh!

MagicLizi left a comment

Choose a reason for hiding this comment

PR #5466 独立代码审查报告（standard 档）

Findings

Rule coverage

Verification

Overall

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

chatgpt-codex-connector Bot commented Oct 5, 2026 •

edited

Loading

greptile-apps Bot commented Oct 5, 2026 •

edited

Loading