feat: 实现真实分页预览
This commit is contained in:
SkyJourney
+56
-50
@@ -1,6 +1,6 @@
|
||||
# Markdown PDF 导出器进度
|
||||
|
||||
最后更新：2026-07-25
|
||||
最后更新：2026-07-26
|
||||
|
||||
## 1. 当前概况
|
||||
|
||||
@@ -19,13 +19,14 @@ main
|
||||
已有提交：
|
||||
|
||||
```text
|
||||
52cf816 feat: 完善导出设置与打印预览
|
||||
ec14f79 feat: 扩展本地主题兼容能力
|
||||
fa07472 feat: 实现网页实时预览
|
||||
7224dfd feat: 实现 Markdown 渲染核心
|
||||
ec48bce chore: 初始化项目骨架
|
||||
```
|
||||
|
||||
当前工作区存在未提交修改，主要是导出配置版本 2、导出设置抽屉、浏览器缓存和实时纸张尺寸及页边距预览。接手时必须保留并审查这些修改，不要重置工作区。
|
||||
当前工作区存在未提交修改，主要是基于 Paged.js 的真实分页预览、页眉页码、跨页表格和超高 Mermaid 图表适配。接手时必须保留并审查这些修改，不要重置工作区。
|
||||
|
||||
## 2. 已完成
|
||||
|
||||
@@ -119,53 +120,58 @@ ec48bce chore: 初始化项目骨架
|
||||
- 主题开发指南；
|
||||
- 后端测试增至 6 项。
|
||||
|
||||
### 2.7 导出设置与打印预览
|
||||
|
||||
提交 `52cf816` 已完成：
|
||||
|
||||
- 导出配置升级到版本 2；
|
||||
- 纸张收敛为 A3、A4、A5、US-Letter 和 US-Legal；
|
||||
- 默认 A4 纵向和 16mm 四边页边距；
|
||||
- 统一 96 CSS px/in、72 PDF pt/in 和 25.4mm/in 的物理单位换算；
|
||||
- 响应式导出设置抽屉；
|
||||
- 纸张、方向、页边距、页眉、页码和主题的版本化浏览器缓存；
|
||||
- 页眉左中右内容和变量；
|
||||
- 五种页码样式、对齐和起始页码；
|
||||
- Mermaid 官方配置 frontmatter、默认主题与错误隔离；
|
||||
- Markdown 表格对齐属性保留和自适应列宽；
|
||||
- 纸张尺寸和页边距实时预览。
|
||||
|
||||
## 3. 当前未提交工作
|
||||
|
||||
以下内容已写入工作区，但尚未提交：
|
||||
|
||||
### 3.1 导出配置版本 2
|
||||
### 3.1 Paged.js 真实分页预览
|
||||
|
||||
- 纸张只保留 A3、A4、A5、US-Letter 和 US-Legal。
|
||||
- 固定纸张尺寸分别为 297×420、210×297、148×210、216×279 和 216×356mm。
|
||||
- 默认 A4 纵向，四边页边距均为 16mm。
|
||||
- 统一采用 96 CSS px/in、72 PDF pt/in 和 25.4mm/in 的物理单位换算。
|
||||
- 保留横向和纵向。
|
||||
- 页脚模型收敛为页码设置，支持五种页码样式、对齐和起始页码。
|
||||
- 校验页边距之和必须为正文保留正尺寸区域。
|
||||
- 增加 6 项共享配置测试。
|
||||
- 引入 MIT 许可证的 Paged.js 0.4.3。
|
||||
- 使用独立同源沙箱 iframe 执行分页，父页面通过严格消息协议传递渲染载荷。
|
||||
- 每张纸以真实物理尺寸独立显示，页面间保留 24px 间隔和预览阴影。
|
||||
- 主题 CSS 原样交给 Paged.js，使主题 `@media print` 规则与未来 PDF 一致。
|
||||
- GitHub 主题打印字号已与 Typora PDF 对齐：正文 13px、一级标题 29.25px、二级标题 22.75px。
|
||||
- W30 对照文档在 Typora 和网页预览中均为 4 页。
|
||||
- 主题切换会重置 iframe 就绪握手，GitHub、Pixyll 和 Whitey 可连续切换且无需刷新。
|
||||
|
||||
### 3.2 导出设置和浏览器缓存
|
||||
### 3.2 页眉、页码与跨页内容
|
||||
|
||||
- 增加响应式右侧导出设置抽屉。
|
||||
- 支持五种纸张、方向和四边页边距。
|
||||
- 已提供页眉左中右内容、页脚页码样式、位置、起始页码和分隔线控件。
|
||||
- 配置和主题选择写入版本化 `localStorage`，不缓存 Markdown 正文。
|
||||
- 缓存缺失、损坏或版本过期时恢复默认配置。
|
||||
- 切换到更小纸张时自动等比例收敛过大的旧页边距。
|
||||
- 增加 3 项浏览器缓存测试和 3 项打印媒体预览测试。
|
||||
- 页眉支持左中右三栏、标题、作者和文件名变量及分隔线。
|
||||
- 页脚支持五种页码格式、左中右位置、起始页码和分隔线。
|
||||
- 当前页码逐页递增，总页数使用真实分页结果。
|
||||
- 标题避免孤立在页尾，段落使用孤行和寡行约束。
|
||||
- 长表格允许跨页，并通过 Paged.js 处理器重复表头。
|
||||
- 表格行、代码块、引用、公式、图片和 Mermaid 默认避免从中间断开。
|
||||
|
||||
### 3.3 实时纸张预览
|
||||
### 3.3 Mermaid 单页适配
|
||||
|
||||
- 纸张尺寸、方向和四边页边距实时作用于预览。
|
||||
- 删除本地主题专用的 8mm 外边距特例。
|
||||
- 在主题 CSS 后追加共享几何 CSS，统一清除 `body` 和 `#write` 的页面宽度、内外边距限制。
|
||||
- 网页预览将主题的 `@media print` 规则按原始位置转换为屏幕预览规则，使 Typora GitHub 等主题使用与 PDF 相同的打印字号和行高。
|
||||
- 固定逻辑页面后续按 96 CSS px/in 分页，预览显示倍率只缩放外层，不参与正文换行和分页计算。
|
||||
- 页眉和页码配置将在下一阶段分页预览中显示。
|
||||
|
||||
### 3.4 Mermaid 配置与错误隔离
|
||||
|
||||
- 使用 Mermaid 官方 npm 包，当前锁定安装版本为 11.16.0。
|
||||
- 无区块配置时显式使用 `default` 主题和 `classic` 外观。
|
||||
- Mermaid 区块内容原样交给官方解析器，支持区块内部的 YAML `config` frontmatter。
|
||||
- 允许区块覆盖主题、外观、主题变量、布局及图表专属配置。
|
||||
- 固定 `strict` 安全级别、自动启动开关、文本和边数量限制、错误输出策略，并禁止区块注入原始 `themeCSS`。
|
||||
- 单个 Mermaid 图表解析或渲染失败时显示局部错误，其余图表继续渲染。
|
||||
- 增加 Mermaid 站点配置、单图错误隔离及区块 frontmatter 保留测试。
|
||||
- Mermaid、字体和图片完成后再启动分页。
|
||||
- 普通 Mermaid 保持主题原有尺寸和布局。
|
||||
- 根据纸张和页边距计算正文区域的 CSS 像素宽高。
|
||||
- 当 SVG 按正文宽度适配后仍高于一页时，读取 `viewBox` 并改为按正文高度等比例缩小。
|
||||
- 超高 Mermaid 整体换页、水平居中，不跨页裁切。
|
||||
- 浏览器实测 A4 超高图高度约 1000.56px，正文可用高度约 1001.57px，未侵入上下页边距。
|
||||
- 增加 SVG `viewBox` 解析、正文尺寸和缩放算法测试。
|
||||
|
||||
## 4. 已执行验证
|
||||
|
||||
2026-07-25 在当前完整工作区成功执行：
|
||||
2026-07-26 在当前完整工作区成功执行：
|
||||
|
||||
```text
|
||||
npm test
|
||||
@@ -177,14 +183,17 @@ git diff --check
|
||||
结果：
|
||||
|
||||
- 共享配置测试：6 项通过；
|
||||
- 渲染器测试：6 项通过；
|
||||
- 前端测试：10 项通过；
|
||||
- 渲染器测试：7 项通过；
|
||||
- 前端测试：21 项通过；
|
||||
- 后端测试：6 项通过；
|
||||
- 全项目类型检查通过；
|
||||
- 生产构建通过；
|
||||
- `git diff --check` 通过，仅出现工作区 LF 将来可能转为 CRLF 的提示；
|
||||
- 导入器默认的已存在目标保护通过；
|
||||
- GitHub、Pixyll 和 Whitey 三套本地主题的 CSS API 均返回成功，组合结果无残留 `@import`。
|
||||
- 同一份 W30 Markdown 在 GitHub 分页预览和 Typora PDF 中均为 4 页。
|
||||
- 三个本地主题无需刷新即可连续切换并重新分页。
|
||||
- 超高 Mermaid 整体缩放到单页正文区域，普通 Mermaid 尺寸不受影响。
|
||||
|
||||
已使用浏览器插件完成视觉验证：
|
||||
|
||||
@@ -213,7 +222,11 @@ git diff --check
|
||||
## 5. 当前注意事项
|
||||
|
||||
- 工作区不是干净状态，禁止重置。
|
||||
- `apps/web/src/App.tsx` 是当前预览实现的主要文件。
|
||||
- `apps/web/src/App.tsx` 负责分页 iframe 生命周期和父页面消息处理。
|
||||
- `apps/web/src/paged-preview-frame.ts` 负责 iframe 内 Mermaid、资源等待和 Paged.js 分页。
|
||||
- `apps/web/src/paged-preview.ts` 负责分页协议、共享文档 CSS、页眉和页码 CSS。
|
||||
- `apps/web/src/mermaid-page-fit.ts` 负责超高 Mermaid 的单页等比例适配。
|
||||
- `apps/web/src/paged-table-handler.ts` 负责跨页表格表头处理。
|
||||
- `apps/web/src/ExportSettingsDrawer.tsx` 是导出设置界面。
|
||||
- `apps/web/src/export-settings.ts` 负责版本化浏览器缓存。
|
||||
- `packages/core/src/export-config.ts` 是纸张、页边距、页眉页脚和页码的共享模型。
|
||||
@@ -229,20 +242,13 @@ git diff --check
|
||||
|
||||
## 6. 推荐接手顺序
|
||||
|
||||
### 阶段一：完成分页预览
|
||||
### 阶段一：提交分页预览
|
||||
|
||||
导出设置、缓存和实时纸张几何已经完成。下一步按已确认设计引入 Paged.js，并实现：
|
||||
|
||||
- 逐页预览；
|
||||
- 页眉左中右内容及变量替换；
|
||||
- 页脚页码、总页数、对齐和起始页码；
|
||||
- Mermaid 整体换页和超高图按页面正文高度等比例缩放；
|
||||
- 字体、图片和 Mermaid 完成后再分页；
|
||||
- 预览与未来 PDF 共用分页 HTML 和 CSS。
|
||||
当前分页预览已经实现并通过验证。检查完整差异并创建一个清晰的阶段提交后，再进入真实 PDF。
|
||||
|
||||
### 阶段二：实现真实 PDF
|
||||
|
||||
分页预览完成并提交后再实现：
|
||||
分页预览提交后再实现：
|
||||
|
||||
1. 增加 Playwright 和固定版本 Chromium。
|
||||
2. 抽取可复用的完整 HTML 文档组装器。
|
||||
|
||||
Reference in New Issue
Block a user