[0120] 在 Mogan STEM 中初步实现 PDF 阅读功能 (#3351)

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: da-liii

TeXmacs/progs/texmacs/texmacs/tm-files.scm

@@ -1571,7 +1571,6 @@
   (or (url-rooted-web? u)
       (not (in? (url-root u) (list "tmfs" "file" "default" "blank" "ramdisc")))
       (file-of-format? u "image")
-      (file-of-format? u "pdf")
       (file-of-format? u "postscript")
       (file-of-format? u "generic")))
 
@@ -1580,6 +1579,18 @@
     (set! u (url-relative (current-buffer) u)))
   (open-url u))
 
+(tm-define (load-pdf-buffer u)
+  (when (not (url-rooted? u))
+    (set! u (url-relative (current-buffer) u)))
+  (if (buffer-exists? u)
+      (switch-to-buffer u)
+      (begin
+        (buffer-set u '(document))
+        (buffer-set-title u (url->system (url-tail u)))
+        (switch-to-buffer u)))
+  (buffer-notify-recent u)
+  (remember-file-dialog-directory u))
+
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;; Loading buffers
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@@ -1679,7 +1690,9 @@
       (if (current-buffer)
           (set! name (url-relative (current-buffer) name))
           (set! name (url-append (url-pwd) name))))
-  (load-buffer-check-autosave name opts))
+  (if (== (url-suffix name) "pdf")
+      (load-pdf-buffer name)
+      (load-buffer-check-autosave name opts)))
 
 ;; The load flowgraph:
 ;; load-buffer
@@ -1705,6 +1718,8 @@
 (tm-define (load-browse-buffer name)
   (:synopsis "Load a buffer or switch to it if already open")
   (cond ((buffer-exists? name) (switch-to-buffer name))
+        ((== (url-suffix name) "pdf")
+         (load-pdf-buffer name))
         ((and (buffer-external? name)
          (!= (url-suffix name) "tm")
          (!= (url-suffix name) "tmu"))
@@ -1800,13 +1815,21 @@
   (:argument u smart-file "File name")
   (:default  u (propose-name-buffer))
   (when (not (url-none? u))
-    (if (window-per-buffer?) (load-buffer-in-new-window u) (load-buffer u))))
+    (if (== (url-suffix u) "pdf")
+        (load-pdf-buffer u)
+        (if (window-per-buffer?)
+            (load-buffer-in-new-window u)
+            (load-buffer u)))))
 
 (tm-define (load-document* u)
   (:argument u smart-file "File name")
   (:default  u (propose-name-buffer))
   (when (not (url-none? u))
-    (if (window-per-buffer?) (load-buffer u) (load-buffer-in-new-window u))))
+    (if (== (url-suffix u) "pdf")
+        (load-pdf-buffer u)
+        (if (window-per-buffer?)
+            (load-buffer u)
+            (load-buffer-in-new-window u)))))
 
 (tm-define (switch-document u)
   (:argument u smart-file "File name")

TeXmacs/progs/texmacs/texmacs/tm-print.scm

@@ -220,7 +220,7 @@
   (:proposals last  (list (number->string (get-page-count)) "")))
 
 (tm-define (preview-file u)
-  (open-url u))
+  (load-pdf-buffer u))
 
 (tm-define (preview-buffer)
   (with-default-view

devel/0120.md

@@ -0,0 +1,132 @@
+# [0120] 在 Mogan STEM 中实现 PDF 阅读功能
+
+## 1 相关文档
+- [dddd.md](dddd.md) - 任务文档模板
+- [216_22.md](216_22.md) - PDF 预览控件悬停按钮修复（`QTPdfPreviewWidget` 文件缓存、HTTP 条件请求）
+- [216_25.md](216_25.md) - 模板页面缩略图缓存与 UI 优化（`QTPdfPreviewWidget` 会话级验证、即时加载缓存）
+
+## 2 任务相关的代码文件
+- `src/Plugins/Qt/qt_utilities.cpp`
+- `src/Plugins/Qt/qt_utilities.hpp`
+- `src/Plugins/Qt/qt_tm_widget.cpp`
+- `src/Plugins/Qt/qt_tm_widget.hpp`
+- `TeXmacs/progs/texmacs/texmacs/tm-files.scm`
+- `tests/Plugins/Qt/qt_pdf_tab_utils_test.cpp`
+- `tests/Plugins/Qt/qt_pdf_preview_widget_test.cpp`
+- `xmake/tests.lua`
+
+## 3 如何测试
+
+### 3.1 确定性测试（单元测试）
+```bash
+xmake run qt_pdf_tab_utils_test
+xmake run qt_pdf_preview_widget_test
+```
+
+### 3.2 非确定性测试（文档验证）
+```bash
+# 启动 Mogan STEM，通过 File -> Open 打开 PDF 文件
+# 验证：
+# 1. PDF 在标签页内打开，而不是外部软件
+# 2. 可以正常翻页阅读
+# 3. 窗口大小调整时 PDF 自适应
+# 4. PDF 标签页和普通文档标签页可以正常切换
+```
+
+## 4 如何提交
+
+提交前执行以下最少步骤：
+
+```bash
+xmake build qt_pdf_tab_utils_test qt_pdf_preview_widget_test stem
+xmake run qt_pdf_tab_utils_test
+xmake run qt_pdf_preview_widget_test
+```
+
+## 5 What
+
+实现 Mogan STEM 的基础 PDF 阅读功能，使打开 PDF 文件时直接在应用内以标签页形式展示，而非调用外部软件（浏览器/PDF 阅读器）。复用已有的 `QTPdfPreviewWidget`（基于 MuPDF 矢量渲染）。
+
+1. **C++ 基础设施**：新增 `is_pdf_tab_file()` 工具函数（通过文件后缀检测 PDF）；在 `qt_tm_widget_rep` 中集成 `QTPdfPreviewWidget`，实现编辑器/启动页/PDF 阅读器三种 central widget 模式的切换。
+2. **Scheme 层**：新增 `load-pdf-buffer` 函数，用原始 PDF 路径直接创建 buffer；在所有 PDF 打开入口（`load-document`、`load-buffer-main`、`load-browse-buffer`）进行拦截。
+3. **C++ 单元测试**：编写 `qt_pdf_tab_utils_test` 和 `qt_pdf_preview_widget_test`，覆盖 URL 解析和 Widget 加载。
+4. **空格键滚动**：`PDFReaderWidget` 支持按空格键向下滚动约 90% 视口高度，到达底部后自动跳到下一页顶部，提供连贯的阅读体验。
+
+## 6 Why
+
+目前 Mogan STEM 打开 PDF 文件时走 `buffer-external?` 判定，最终通过 `QDesktopServices::openUrl` 调用外部软件。用户需要在 Mogan STEM 内部直接阅读 PDF，以获得一致的标签页管理体验。已有的 `QTPdfPreviewWidget` 具备 MuPDF 渲染、翻页控制、自适应大小能力，可直接复用。
+
+## 7 How
+
+### 7.1 核心思路
+
+参考启动页机制（`tmfs://startup-tab`）：
+- Scheme 层：PDF 文件不再走外部打开流程，而是直接用原始路径创建 buffer（buffer 名即 PDF 文件路径）。
+- C++ 层：`qt_tm_widget_rep::send(SLOT_FILE)` 检测到文件后缀为 `pdf` 时，设置 `pdfTabMode = true`。`sync_startup_tab_mode()` 根据模式决定显示编辑器、启动页或 `QTPdfPreviewWidget`。
+
+### 7.2 C++ 层修改
+
+**`qt_utilities.cpp/hpp`** 新增：
+```cpp
+bool is_pdf_tab_file (string file);
+```
+
+**`qt_tm_widget.hpp`** 新增成员：
+```cpp
+QTPdfPreviewWidget* pdfViewerWidget;
+bool                pdfTabMode;
+QString             currentPdfPath;
+```
+
+**`qt_tm_widget.cpp`** 关键修改：
+- 构造函数初始化 `pdfViewerWidget(nullptr)`、`pdfTabMode(false)`、`currentPdfPath("")`。
+- 析构函数 `delete pdfViewerWidget`。
+- `sync_startup_tab_mode()` 增加 `pdfTabMode` 分支：隐藏 editor 和 startup widget，延迟创建 `QTPdfPreviewWidget`，`loadFromFile(currentPdfPath)`，并设置焦点。
+- `send(SLOT_FILE)`：`pdfTabMode = is_pdf_tab_file(file)`（通过后缀名检测），`currentPdfPath` 直接使用 buffer 路径。
+- `update_visibility()`：PDF 模式下隐藏所有工具栏，保留 menu、status、tab、title bar。
+
+### 7.3 Scheme 层修改
+
+**`TeXmacs/progs/texmacs/texmacs/tm-files.scm`** 新增 `load-pdf-buffer`：
+```scheme
+(tm-define (load-pdf-buffer u)
+  (when (not (url-rooted? u))
+    (set! u (url-relative (current-buffer) u)))
+  (if (buffer-exists? u)
+      (switch-to-buffer u)
+      (begin
+        (buffer-set u '(document))
+        (buffer-set-title u (url-tail u))
+        (switch-to-buffer u))))
+```
+
+**入口拦截**：确保所有打开 PDF 的路径都进入 `load-pdf-buffer`：
+- `load-buffer-main`：在调用 `load-buffer-check-autosave` 之前，若 `(== (url-suffix name) "pdf")` 则跳转 `load-pdf-buffer`。此修改覆盖 `File -> Open`（`open-buffer` -> `load-buffer` -> `load-buffer-main`）。
+- `load-browse-buffer`：在 `buffer-external?` 判定之前，增加 PDF 分支。
+- `load-document` / `load-document*`：增加 PDF 分支。
+
+### 7.4 测试策略（TDD）
+
+**测试 1：`qt_pdf_tab_utils_test.cpp`**
+- `test_is_pdf_tab_file()`：验证后缀为 `.pdf` 的文件路径返回 true，其他返回 false。
+
+**测试 2：`qt_pdf_preview_widget_test.cpp`**
+- `test_creation()`：验证 Widget 创建后状态正确。
+- `test_loadFromFile_validPdf()`：加载 `$TEXMACS_PATH/tests/PDF/pdf_1_4_sample.pdf`，验证 `pageCount() > 0`。
+- `test_loadFromFile_invalidFile()`：加载不存在的文件，验证 `hasError() == true`。
+- `test_clearPreview()`：验证清除后状态正确。
+
+### 7.5 注意事项
+
+- `QTPdfPreviewWidget` 依赖 `QtNetwork`，需在 `xmake/tests.lua` 的测试框架中添加 `"QtNetwork"`。
+- `gf fix` 会重新格式化整个 `tm-files.scm`，造成巨大 diff，应避免在该文件上运行。
+- 每个 PDF 文件直接以其路径作为 buffer 名，支持多标签页同时打开不同 PDF。
+- 关闭 PDF 标签页走正常的 `kill-buffer` 流程。
+
+### 7.6 `PDFReaderWidget` 空格键滚动
+
+**实现方式**：
+- 重写 `keyPressEvent(QKeyEvent* event)`，检测 `Qt::Key_Space`。
+- 滚动距离为 `viewport()->height() * 0.9`（约 90% 视口高度）。
+- 使用 `QScrollArea::verticalScrollBar()->setValue()` 实现平滑滚动。
+- 若当前已滚动到底部，则继续滚动到下一页顶部（或直接到底部保持连续阅读）。

src/Plugins/Qt/qt_chooser_widget.cpp

@@ -222,7 +222,7 @@ qt_chooser_widget_rep::set_type (const string& _type) {
     nameFilters << to_qstring (translate ("All Format") * " (*)");
   }
   else if (_type == "action_open") {
-    mainNameFilter+= " (*.tmu *.tm *.ts *.tp)";
+    mainNameFilter+= " (*.tmu *.tm *.ts *.tp *.pdf)";
     //" (*.scala *.sc *.sbt *.pants *.ltx *.sty *.cls *.tex *.bib *.rawbib *.jl
     //*.js *.java *.sld *.ss *.tmu *.txt *.py *.json *.html *.hh *.cpp *cc *hpp
     //*.scm *.elv *.md *.sh *.csv)"

src/Plugins/Qt/qt_pdf_preview_widget.hpp

@@ -17,8 +17,6 @@
 #include <QSize>
 #include <QWidget>
 
-#include <mupdf/fitz.h>
-
 // Forward declarations
 class QPushButton;
 class QLabel;