fix: 🐛 修复启动主窗口出现{死窗口、完全透明}问题

sqmw · sqmw · commit 34a177e62ef2 · 2026-02-05T19:47:07.000+08:00
diff --git a/docs/auto_hide.md b/docs/auto_hide.md
@@ -11,6 +11,8 @@
 - 热区位于屏幕左上，宽 `screenWidth / 4`、高 6~24px，仅在按住 Ctrl 且鼠标位于热区时才从托盘唤醒，避免全屏或移动时误触。
 - 唤醒时短暂设置窗口 TopMost，防止被全屏应用遮挡，随后恢复原状态。
 - 托盘菜单唤起走同一流程，确保第一下就能拿到窗口句柄。
+- 热区 watcher 在应用启动时即创建定时器，但会通过 `shouldWatch()` 动态判定是否需要工作；避免因为启动瞬间不满足条件而“永远不启动”。
+- 热区触发改为“边沿触发”（进入热区且按住 Ctrl 的第一次触发），避免按住 Ctrl 停留在热区时重复唤起导致时序竞态。
 
 ### 磁吸与吸附条件
 - 磁吸区更宽：`screenWidth / 6` × `screenHeight / 3`，越界（x < 0 或 y < 0）也视为需要靠边。
@@ -35,3 +37,7 @@
   - **原因**：设置页面属于沉浸式配置场景，用户可能需要频繁切换窗口（如选择背景图片、查阅资料），或者进行长时间的微调操作。
   - **实现**：在 `onWindowBlur` 和自动隐藏定时器中检查当前 `selectedIndex`，如果是设置页（Index 2）则直接返回。
   - **效果**：即使窗口失去焦点（如点击了外部或切换了应用），只要 DeskTidy 停留在设置页，窗口就会保持显示，直到用户主动关闭或切换页面。
+
+## 热区响应性（2026-02-05）
+- 之前热区检测使用秒级轮询（1.2s~1.5s），会让“Ctrl+鼠标进热区”看起来需要晃两下才触发（本质是错过了 tick）。
+- 现在热区 watcher 使用 `80ms` 轮询 + “边沿触发”，进入热区且按住 Ctrl 的第一次 tick 立刻触发，停留不会重复触发。
diff --git a/docs/behavior/search_input.md b/docs/behavior/search_input.md
@@ -0,0 +1,19 @@
+# 搜索输入（Type-to-Search）行为说明
+
+## 目标
+在应用主页或其他 Tab 页面中，用户直接键盘输入时，应自动聚焦到搜索框并把输入内容写入。
+
+## 现状实现
+- 在主页根部增加全局 `Focus`，监听 `onKeyEvent`（仅在没有文本输入焦点时生效）。
+- 当捕获到可打印字符：
+  1. 自动切换到 **应用 Tab**
+  2. 聚焦搜索框
+  3. 将字符写入搜索框并更新搜索结果
+
+## 关键代码
+- `lib/screens/desk_tidy_home/state.dart`：根部 `Focus` 与全局焦点节点
+- `lib/screens/desk_tidy_home/logic_search.dart`：`_handleGlobalKeyEvent()` 输入转发逻辑
+
+## 注意事项
+- 如果当前已有文本输入控件聚焦，则不会劫持按键，避免干扰设置页输入。
+
diff --git a/docs/hotkey.md b/docs/hotkey.md
@@ -197,6 +197,11 @@ await windowManager.show();
 
 补充：唤起后会自动聚焦搜索框；当搜索框已有内容时，会尝试全选，便于直接覆盖输入。
 另外：热键唤起时会优先切到“应用”Tab 再显示窗口，避免窗口出现后再发生 Tab 跳转带来的卡顿/不流畅观感。
+如遇到透明空白窗口，唤起流程会强制恢复窗口不透明度（防止被异常中断卡在 0.0）。
+如果出现“窗口可点击但完全透明/无UI”的情况，窗口聚焦时会强制恢复面板可见性，避免卡在隐藏态。
+补充：唤起前会等待一帧完成 UI 构建，并且会取消“延迟隐藏”的过期任务，避免出现“刚显示又被隐藏/白屏”的竞态问题。
+补充：当“延迟隐藏”被新唤起打断时，会自动恢复面板可见性，防止窗口保持透明但仍可点击的异常状态。
+补充：为规避极低概率的 Release 渲染不同步，`show()` 后会额外延迟追加两次 1px 尺寸“震动”（160ms/420ms）来强制触发 `WM_SIZE`。
 
 ## 窗口布局配置
 
diff --git a/docs/rendering_glitch_debug.md b/docs/rendering_glitch_debug.md
@@ -53,6 +53,11 @@ await windowManager.setSize(currentSize);
 
 **原理**：通过 1 像素的尺寸往返跳变，强制产生 `WM_SIZE` 消息，从而触发 C++ 端的 `SyncChildContentSize()`。
 
+### 4. 额外兜底：延迟二次“震动”（2026-02-05）
+在极少数情况下（尤其是“刚隐藏/刚启动应用 -> 立刻热键唤起”这类时序），一次性震动可能发生在窗口尚未完全进入可呈现状态的时间点，导致仍然出现“白/透明/死界面（可点击但不刷新）”。
+
+兜底策略：在 `show()` 后除了立刻震动外，再延迟追加 160ms / 420ms 两次震动，并通过 token 校验避免在隐藏流程中误触发。
+
 ## 涉及文件
 
 | 文件 | 变更内容 |
diff --git a/lib/screens/desk_tidy_home/logic_bootstrap.dart b/lib/screens/desk_tidy_home/logic_bootstrap.dart
@@ -33,30 +33,104 @@ extension _DeskTidyHomeBootstrap on _DeskTidyHomePageState {
     service.stopPolling();
   }
 
+  void _pokeUi() {
+    if (!mounted) return;
+    _setState(() {});
+    SchedulerBinding.instance.scheduleFrame();
+  }
+
+  Future<void> _awaitUiFrame({
+    Duration timeout = const Duration(milliseconds: 120),
+  }) async {
+    final binding = WidgetsBinding.instance;
+    final frameFuture = binding.endOfFrame;
+    binding.scheduleFrame();
+    try {
+      await frameFuture.timeout(timeout);
+    } catch (_) {}
+  }
+
+  Future<void> _prepareUiForShow({bool forceAppTab = false}) async {
+    _visibilityToken++;
+    if (mounted) {
+      _setState(() {
+        _panelVisible = true;
+        if (forceAppTab) _selectedIndex = 0;
+      });
+    }
+    await _awaitUiFrame();
+  }
+
+  Future<void> _nudgeWindowSizeForRedraw({required int token}) async {
+    if (!mounted) return;
+    if (_trayMode || !_panelVisible) return;
+    if (_visibilityToken != token) return;
+    try {
+      final currentSize = await windowManager.getSize();
+      await windowManager.setSize(
+        Size(currentSize.width + 1, currentSize.height),
+      );
+      await windowManager.setSize(currentSize);
+    } catch (_) {}
+    _pokeUi();
+  }
+
+  void _scheduleRedrawNudges() {
+    final token = _visibilityToken;
+    unawaited(_nudgeWindowSizeForRedraw(token: token));
+    unawaited(
+      Future.delayed(
+        const Duration(milliseconds: 160),
+        () => _nudgeWindowSizeForRedraw(token: token),
+      ),
+    );
+    unawaited(
+      Future.delayed(
+        const Duration(milliseconds: 420),
+        () => _nudgeWindowSizeForRedraw(token: token),
+      ),
+    );
+  }
+
+  Future<void> _ensureWindowOpaque() async {
+    try {
+      await windowManager.setOpacity(1.0);
+    } catch (_) {}
+    unawaited(
+      Future.delayed(const Duration(milliseconds: 120), () async {
+        try {
+          await windowManager.setOpacity(1.0);
+        } catch (_) {}
+      }),
+    );
+  }
+
+  void _ensurePanelVisible() {
+    if (!mounted) return;
+    if (_trayMode) return;
+    if (!_panelVisible) {
+      _setState(() => _panelVisible = true);
+    }
+  }
+
   Future<void> _bringWindowToFrontFromHotkey() async {
     _windowHandle = findMainFlutterWindowHandle() ?? _windowHandle;
     _trayMode = false;
     _lastActivationMode = _ActivationMode.hotkey;
     _ignoreBlurUntil = DateTime.now().add(const Duration(milliseconds: 600));
-
-    if (mounted) {
-      // Switch to App tab before showing the window to avoid a visible
-      // "tab jump" (e.g. from Settings -> Apps) after the window is already up.
-      if (!_panelVisible || _selectedIndex != 0) {
-        _setState(() {
-          _panelVisible = true;
-          _selectedIndex = 0;
-        });
-      }
-    }
+    await _prepareUiForShow(forceAppTab: true);
 
     await windowManager.setAlwaysOnTop(true);
     await windowManager.setSkipTaskbar(true);
     await windowManager.restore();
     await windowManager.show();
+    _scheduleRedrawNudges();
 
     _dockManager.onPresentFromHotkey();
     _updateHotkeyPolling();
+    await _ensureWindowOpaque();
+    _ensurePanelVisible();
+    _pokeUi();
 
     forceSetForegroundWindow(_windowHandle);
     await windowManager.focus();
@@ -97,14 +171,7 @@ extension _DeskTidyHomeBootstrap on _DeskTidyHomePageState {
       _ignoreBlurUntil = DateTime.now().add(const Duration(milliseconds: 600));
 
       // 先准备内容，避免白屏闪烁
-      if (mounted) {
-        // Prepare content and switch to App tab before showing the window.
-        // This makes hotkey wake-up feel immediate and avoids a delayed tab swap.
-        _setState(() {
-          _panelVisible = true;
-          _selectedIndex = 0;
-        });
-      }
+      await _prepareUiForShow(forceAppTab: true);
 
       // 加载快捷键专属窗口布局并应用
       final layout = await AppPreferences.loadHotkeyWindowLayout();
@@ -117,24 +184,15 @@ extension _DeskTidyHomeBootstrap on _DeskTidyHomePageState {
         Offset(bounds.x.toDouble(), bounds.y.toDouble()),
       );
 
-      // [Anti-Flash] 先设置透明度为0，防止白屏闪烁
-      await windowManager.setOpacity(0.0);
-
       await windowManager.setAlwaysOnTop(true);
       await windowManager.setSkipTaskbar(true);
       await windowManager.restore(); // 先恢复窗口状态
       await windowManager.show(); // 再显示窗口
 
-      // [Fix] Force a tiny resize to trigger WM_SIZE and sync child HWND in Release mode
-      final currentSize = await windowManager.getSize();
-      await windowManager.setSize(
-        Size(currentSize.width + 1, currentSize.height),
-      );
-      await windowManager.setSize(currentSize);
+      _scheduleRedrawNudges();
 
-      // 等待一帧渲染
-      await Future.delayed(const Duration(milliseconds: 50));
-      await windowManager.setOpacity(1.0);
+      await _ensureWindowOpaque();
+      _ensurePanelVisible();
 
       _dockManager.onPresentFromHotkey();
       _updateHotkeyPolling();
@@ -144,6 +202,7 @@ extension _DeskTidyHomeBootstrap on _DeskTidyHomePageState {
       await windowManager.focus(); // 也调用 Flutter 的 focus 作为补充
       await _syncDesktopIconVisibility();
       // _startDesktopIconSync removed (handled by service)
+      _pokeUi();
 
       unawaited(
         Future.delayed(const Duration(milliseconds: 800), () {
@@ -162,6 +221,9 @@ extension _DeskTidyHomeBootstrap on _DeskTidyHomePageState {
         });
       });
     } finally {
+      unawaited(_ensureWindowOpaque());
+      _ensurePanelVisible();
+      _pokeUi();
       _hotkeyPresentInFlight = false;
       if (_hotkeyRefocusRequested) {
         _hotkeyRefocusRequested = false;
@@ -233,11 +295,14 @@ extension _DeskTidyHomeBootstrap on _DeskTidyHomePageState {
             await windowManager.setSkipTaskbar(false);
             await windowManager.show();
             await windowManager.restore();
+            _scheduleRedrawNudges();
             await windowManager.focus();
             await _syncDesktopIconVisibility();
             if (mounted) _setState(() => _panelVisible = true);
             // _startDesktopIconSync removed
             _onMainWindowPresented();
+            unawaited(_ensureWindowOpaque());
+            _pokeUi();
           }
           _updateHotkeyPolling();
         },
diff --git a/lib/screens/desk_tidy_home/logic_runtime.dart b/lib/screens/desk_tidy_home/logic_runtime.dart
@@ -9,7 +9,7 @@ extension _DeskTidyHomeRuntime on _DeskTidyHomePageState {
     _lastActivationMode = _ActivationMode.hotCorner;
 
     // 先准备内容，避免白屏闪烁
-    if (mounted) _setState(() => _panelVisible = true);
+    await _prepareUiForShow();
 
     // 加载热区专属窗口布局并应用
     final layout = await AppPreferences.loadHotCornerWindowLayout();
@@ -26,18 +26,13 @@ extension _DeskTidyHomeRuntime on _DeskTidyHomePageState {
     await windowManager.setSkipTaskbar(true);
     await windowManager.restore(); // 先恢复窗口状态
     await windowManager.show(); // 再显示窗口
-
-    // [Fix] Force a tiny resize to trigger WM_SIZE and sync child HWND in Release mode
-    final currentSize = await windowManager.getSize();
-    await windowManager.setSize(
-      Size(currentSize.width + 1, currentSize.height),
-    );
-    await windowManager.setSize(currentSize);
+    _scheduleRedrawNudges();
 
     _dockManager.onPresentFromHotCorner();
     await windowManager.focus();
     await _syncDesktopIconVisibility();
     _onMainWindowPresented();
+    _pokeUi();
     // Drop always-on-top after we are visible.
     unawaited(
       Future.delayed(const Duration(milliseconds: 800), () {
@@ -54,16 +49,18 @@ extension _DeskTidyHomeRuntime on _DeskTidyHomePageState {
     _lastActivationMode = _ActivationMode.tray;
 
     // 先准备内容，避免白屏闪烁
-    if (mounted) _setState(() => _panelVisible = true);
+    await _prepareUiForShow();
 
     await windowManager.setAlwaysOnTop(true);
     await windowManager.setSkipTaskbar(true);
     await windowManager.restore(); // 先恢复窗口状态
     await windowManager.show(); // 再显示窗口
+    _scheduleRedrawNudges();
     _dockManager.onPresentFromTray();
     await windowManager.focus();
     await _syncDesktopIconVisibility();
     _onMainWindowPresented();
+    _pokeUi();
     unawaited(
       Future.delayed(const Duration(milliseconds: 800), () {
         windowManager.setAlwaysOnTop(false);
@@ -75,10 +72,19 @@ extension _DeskTidyHomeRuntime on _DeskTidyHomePageState {
     _dockManager.onDismissToTray();
     _trayMode = true;
     _updateHotkeyPolling();
+    final hideToken = ++_visibilityToken;
     if (mounted) _setState(() => _panelVisible = false);
     _setupAutoRefresh();
     await windowManager.setSkipTaskbar(true);
     await Future<void>.delayed(_DeskTidyHomePageState._hotAnimDuration);
+    if (!mounted) return;
+    if (_visibilityToken != hideToken || !_trayMode) {
+      if (mounted && !_panelVisible) {
+        _setState(() => _panelVisible = true);
+        _pokeUi();
+      }
+      return;
+    }
     await windowManager.hide();
   }
 
diff --git a/lib/screens/desk_tidy_home/logic_search.dart b/lib/screens/desk_tidy_home/logic_search.dart
@@ -150,6 +150,47 @@ extension _DeskTidyHomeSearchLogic on _DeskTidyHomePageState {
     return KeyEventResult.handled;
   }
 
+  bool _isTextInputFocused() {
+    final primary = FocusManager.instance.primaryFocus;
+    if (primary == null) return false;
+    return primary.context?.widget is EditableText;
+  }
+
+  KeyEventResult _handleGlobalKeyEvent(FocusNode node, KeyEvent event) {
+    if (event is! KeyDownEvent) return KeyEventResult.ignored;
+
+    if (HardwareKeyboard.instance.isControlPressed ||
+        HardwareKeyboard.instance.isAltPressed ||
+        HardwareKeyboard.instance.isMetaPressed) {
+      return KeyEventResult.ignored;
+    }
+
+    if (_isTextInputFocused() || _appSearchFocus.hasFocus) {
+      return KeyEventResult.ignored;
+    }
+
+    final ch = event.character;
+    if (ch == null || ch.isEmpty) return KeyEventResult.ignored;
+    if (ch == '\n' || ch == '\r' || ch == '\t') {
+      return KeyEventResult.ignored;
+    }
+
+    if (_selectedIndex != 0) {
+      _setState(() => _selectedIndex = 0);
+    }
+
+    final current = _appSearchController.text;
+    final next = '$current$ch';
+    _appSearchController.text = next;
+    _appSearchController.selection = TextSelection.collapsed(
+      offset: next.length,
+    );
+    _updateSearchQuery(next);
+    _focusSearchField(selectAllIfHasText: false);
+
+    return KeyEventResult.handled;
+  }
+
   // ...
 
   // 提取 LayoutMetrics 类或方法来统一计算
diff --git a/lib/screens/desk_tidy_home/state.dart b/lib/screens/desk_tidy_home/state.dart
diff --git a/lib/screens/desk_tidy_home_page.dart b/lib/screens/desk_tidy_home_page.dart
diff --git a/lib/services/hot_corner_service.dart b/lib/services/hot_corner_service.dart
