edit | blame | history | raw

26.0701 Taglauncher / Coder3 / 设置ESC与语言居中

用户目标

  • UI 小改动：设置页“语言”页的语言列表整体偏左，需要作为一个整体移动到视觉居中的位置。
  • 功能修复：AppGrid 可见且 Settings 窗口覆盖在 AppGrid 上方时，按 ESC 的行为应为：
  • 第一次 ESC 关闭 Settings。
  • 第二次 ESC 关闭 AppGrid。
  • 用户要求先和架构师、代码审核员讨论方案，再落地。

已完成事项

  • 已拉架构师 explorer 和代码审核员 explorer 做只读方案讨论。
  • 已实现语言页列表居中：语言页改用独立的 languageContentWidth = 820，不再使用 settingsContentWidth = 940。
  • 已实现 Settings 覆盖 AppGrid 时的 ESC 局部处理：
  • Settings 自己安装本地 NSEvent keyDown monitor。
  • 只在 Settings 作为 OverlayPanel 子窗口显示时接管 ESC。
  • 文件面板 / sheet 打开时放行 ESC。
  • Pro 弹层、确认框、快捷键录制优先于关闭 Settings。
  • 普通状态下第一次 ESC 调用 window.performClose(nil) 关闭 Settings；第二次 ESC 仍走既有 AppGrid 关闭路径。
  • 已更新 pro_feature_gate_qa.sh，把本次语言页宽度和 Settings ESC monitor 纳入静态门禁。

关键决策

  • 不使用 .padding(.leading) 或 .offset 硬推语言列表，避免做成相对偏移；改为语言页独立内容宽度。
  • 不修改 QuickSearch.swift 的点击、回车、ESC 路径。
  • 不修改 OverlayPanel.sendEvent，不移除 AppGrid 的 isSettingsVisible 保护。
  • ESC 的第一优先级放在 Settings 内部状态，而不是 AppGrid 层硬关窗口。

文件变更

  • /Users/ar/Projects/Taglauncher/src/Apptag/PreferencesView.swift
  • 新增 languageContentWidth = 820。
  • 语言页 centeredSettingsScrollContent(width:) 改为使用 languageContentWidth。
  • 新增 settingsEscapeMonitor、installSettingsEscapeMonitor()、removeSettingsEscapeMonitor()。
  • 新增 isSettingsOverlayEscapeEvent(_:) 和 handleSettingsEscapeKey()。
  • /Users/ar/Projects/Taglauncher/src/Scripts/pro_feature_gate_qa.sh
  • 更新语言页居中宽度断言。
  • 新增 Settings ESC monitor 和处理顺序断言。

核心事实 / 变更快照

  • 变更对象：Settings 语言页布局宽度。
  • 变更前：语言页使用 settingsContentWidth = 940，语言矩阵在该宽度内左对齐。
  • 变更后：语言页使用 languageContentWidth = 820，与固定设置面板宽度视觉一致，整体居中。
  • 范围边界：不改变语言列表内容、顺序、列数、语言文案、Tab bar、Pro 状态行。
  • 变更对象：Settings over AppGrid 的 ESC 行为。
  • 变更前：handleOverlayEscapeKey() 在 isSettingsVisible 时返回 false，AppGrid 不关闭，但 Settings 也不关闭，导致 ESC 无效。
  • 变更后：Settings 层本地处理 ESC；普通状态第一次 ESC 关 Settings，第二次 ESC 关 AppGrid。
  • 保护边界：文件面板 / sheet、Pro 弹层、确认框、快捷键录制优先处理，不直接关 Settings。

QA 结论

  • 通过：
  • bash build.sh
  • bash Scripts/quick_search_launch_contract_qa.sh
  • bash Scripts/pro_custom_hotkeys_qa.sh
  • bash Scripts/pro_feature_gate_qa.sh
  • bash Scripts/pro_localization_qa.sh
  • git diff --check -- src/Apptag/PreferencesView.swift src/Scripts/pro_feature_gate_qa.sh
  • 真实 GUI 窄版验证通过：
  • 打开本地构建 AppGrid。
  • 点击 AppGrid 右上角设置齿轮，Settings 覆盖在 AppGrid 上方。
  • 将 TagLauncher 置前后按 ESC：第一次只关闭 Settings，AppGrid 仍在。
  • 再按 ESC：AppGrid 关闭。
  • 未完全通过：
  • bash Scripts/window_logic_qa.sh 未跑到本次 ESC 场景，在旧的“隐藏 Dock 模式不应出现 Dock 图标”场景失败：
    • 失败信息：FAIL: expected no QA build TagLauncher Dock tile, got 1
    • 该失败发生在脚本切换 showDockIcon=false 后的旧 Dock 图标检查处，和本轮 PreferencesView.swift 改动路径无直接关联。

可复用命令 / Runbook

常规构建与静态 QA

用途：验证本轮 Settings ESC、语言页居中、Quick Search 点击/回车、Pro 门禁、本地化未回归。

前置条件：在 /Users/ar/Projects/Taglauncher/src 下执行；本地构建输出为 build/TagLauncher.app。

cd /Users/ar/Projects/Taglauncher/src
bash build.sh
bash Scripts/quick_search_launch_contract_qa.sh
bash Scripts/pro_custom_hotkeys_qa.sh
bash Scripts/pro_feature_gate_qa.sh
bash Scripts/pro_localization_qa.sh
git -C /Users/ar/Projects/Taglauncher diff --check -- src/Apptag/PreferencesView.swift src/Scripts/pro_feature_gate_qa.sh

Settings over AppGrid 双 ESC GUI 验证

用途：验证 AppGrid 上方打开 Settings 后，第一次 ESC 只关 Settings，第二次 ESC 关 AppGrid。

前置条件：已执行 bash build.sh，并允许本机 GUI 自动化点击。

cd /Users/ar/Projects/Taglauncher/src
open -n /Users/ar/Projects/Taglauncher/src/build/TagLauncher.app
open 'taglauncher://show'

验证步骤：

  1. 点击 AppGrid 右上角设置齿轮，确认 Settings 覆盖在 AppGrid 上方。
  2. 如自动化按键发给了其他前台 App，先让 TagLauncher 置前：
osascript -e 'tell application "System Events" to tell process "TagLauncher" to set frontmost to true'
  1. 第一次发送 ESC：
osascript -e 'tell application "System Events" to key code 53'

期望：Settings 关闭，AppGrid 仍然可见。

  1. 第二次发送 ESC：
osascript -e 'tell application "System Events" to key code 53'

期望：AppGrid 关闭。

清理：

osascript -e 'tell application "TagLauncher" to quit' >/dev/null 2>&1 || true
pkill -f '/TagLauncher.app/Contents/MacOS/TagLauncher' >/dev/null 2>&1 || true

搜索关键词：settingsEscapeMonitor、languageContentWidth、key code 53、taglauncher://show、Settings over AppGrid、双 ESC

未决问题 / 后续建议

  • window_logic_qa.sh 的隐藏 Dock 图标场景需要后续单独排查或稳定化；本轮未修改 Dock 策略。
  • 如果后续要把双 ESC 纳入完整 GUI 自动化，应在 window_logic_qa.sh 的旧 Dock 场景之前或独立脚本中增加 Settings-over-AppGrid ESC 子场景，避免被无关前置场景中断。