wip

Author: Yuki-Nagori

devel/216_38.md

@@ -0,0 +1,53 @@
+# 216_38 最近文档列表增加文件不存在提示及自动清理
+
+## 如何测试
+
+1. 编译：`xmake b stem`
+2. 启动 Mogan，打开启动页 **File** 页面。
+3. 正常打开若干个文档，使其出现在 **Recent** 最近文档列表中。
+4. 手动在文件系统中删除或移动其中某一个文档。
+5. 重新打开启动页（或切换标签页后切回），确认该文档已从 **Recent** 列表中自动消失。
+6. 若未重新打开启动页，直接点击该已失效的文档项：
+   - 确认弹出红色 Toast 提示 **"File not found, removed from recent list"**（中文：**"文件未找到，已从最近列表中移除"**）。
+   - 确认该文档项从列表中即时移除。
+   - 确认未触发文档加载，程序无卡死或异常。
+7. 点击其他正常的最近文档项，确认仍可正常打开。
+8. 切换中英文界面，确认 Toast 提示文案正确。
+
+## 2026/05/08 实现说明
+
+### What
+
+为启动页 File 页面的 **Recent** 最近文档列表引入文件存在性校验机制：加载时自动剔除已失效路径，点击时通过浮动 Toast 轻量提示用户并即时移除该条目。同时为后续全局复用新增了 `QtFloatingToast` 组件。
+
+#### 修改文件
+
+**src/Plugins/Qt/qt_floating_toast.hpp / qt_floating_toast.cpp（新增）**
+- 实现无边框浮动 Toast 提示组件，支持 `Success` / `Warning` / `Error` 三种类型。
+- 使用 `QPropertyAnimation` 实现 200ms 淡入/淡出效果，`QTimer` 控制显示时长。
+- 静态工厂方法 `showToast` 自动管理组件生命周期（淡出完成后 `deleteLater`）。
+- `paintEvent` 根据类型绘制不同颜色的圆角矩形背景：
+  - `Success`：绿色 `#2e7d32`
+  - `Warning`：橙色 `#f57c00`
+  - `Error`：红色 `#c62828`
+- 显示位置基于锚定窗口居中偏上（`window->height() / 8`），使用 `DpiUtils` 进行 DPI 适配。
+
+**src/Plugins/Qt/qt_file_page.cpp**
+- `loadRecentDocs()`：在加载最近文档路径后，新增 `QFile::exists` 过滤，仅保留磁盘上仍存在的文件，自动静默清理失效条目。
+- `onRecentDocClicked()`：点击时若检测到文件已不存在，调用 `QtFloatingToast::showToast` 显示 3 秒 Error 类型提示，随后调用 `removeRecentDoc` 从列表移除并直接返回，避免尝试加载不存在的文件。
+
+**TeXmacs/plugins/lang/dic/en_US/zh_CN.scm**
+- 新增翻译：`("File not found, removed from recent list" "文件未找到，已从最近列表中移除")`。
+
+### Why
+
+1. **体验缺陷**：此前用户点击最近列表中已被删除或移动的文件时，Mogan 无任何反馈，既未提示错误，也未清理列表，用户会困惑为何点击无响应。
+2. **列表污染**：随着使用时间的推移，最近文档列表会积累大量失效路径（如文件被删除、移动、重命名），手动清理无入口。
+3. **轻量提示**：相比阻塞式弹窗（`QMessageBox`），Toast 提示不中断用户操作流，更适合"仅告知结果"的场景，且与现代化 UI 习惯一致。
+4. **组件复用**：将 Toast 封装为独立组件 `QtFloatingToast`，便于后续在其他场景（如保存成功、网络异常等）直接复用，避免重复造轮子。
+
+### How
+
+- **双重保障**：加载时过滤（静默清理）+ 点击时检测（即时提示），既保证列表首次呈现即为有效数据，也覆盖了"列表已渲染后文件才被删除"的边界场景。
+- **生命周期自管理**：`showToast` 使用 `new QtFloatingToast` 创建实例，在 `startFadeOut` 的 `finished` 信号中绑定 `deleteLater`，无需调用方关心内存释放。
+- **无边框置顶窗口**：使用 `Qt::FramelessWindowHint | Qt::WindowStaysOnTopHint | Qt::Tool` 配合 `WA_TranslucentBackground`，确保 Toast 悬浮于主窗口之上且不影响焦点。