yixiong/MorphDoc
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity

fix: 修复长文档分页与滚动同步

Browse Source
This commit is contained in:
SkyJourney
2026-07-26 08:43:56 +08:00
parent 1d93f31f85
commit d62552384f
15 changed files with 449 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+41 -2
View File
@@ -12,11 +12,12 @@
- 动态主题清单、CSS 和静态资源接口；
- Markdown、Front Matter、安全过滤和扩展语法渲染核心；
- 表格、任务列表、脚注、代码高亮、KaTeX 和 Mermaid；
- iframe 隔离的 A4 页面预览与主题切换；
- iframe 隔离的真实分页预览、双向滚动同步与主题切换；
- 五种纸张、页边距、页眉、页码和浏览器配置缓存；
- 内置 Typora 风格主题，以及仅供本机使用的三套白色 Typora 默认主题导入工具；
- Docker 与 PDF 渲染目录预留。
Chromium PDF 下载、完整导出配置面板和本地资源文件处理将在后续阶段实现。
Chromium PDF 下载和本地资源文件处理将在后续阶段实现。
## 本地开发
@@ -35,6 +36,44 @@ npm run dev
页面支持直接编辑 Markdown，或选择本地 `.md` 文件。文件内容将读取到当前浏览器页面并发送给内网转换服务，不写入数据库。
编辑区和分页预览使用双向比例滚动同步。在任意一侧滚动时，另一侧会跟随到相同的全文阅读进度，方便定位并修改较长文档。
## Mermaid 长标签
流程图节点标签的默认最大宽度为 320px。单个 Mermaid 区块可以通过 config frontmatter 覆盖：
````markdown
```mermaid
---
config:
flowchart:
wrappingWidth: 360
---
flowchart TB
A["较长的节点名称<br/>第二行说明"] --> B["下一个节点"]
```
````
需要自动换行时可以使用 Mermaid Markdown String：
````markdown
```mermaid
flowchart LR
A["`这是一段可以由 Mermaid 自动换行的较长节点文字`"]
```
````
个别节点仍需缩小字体时，优先使用 Mermaid 自带的 `classDef`：
````markdown
```mermaid
flowchart LR
A["较长节点"] --> B["普通节点"]
classDef compact font-size:12px;
class A compact;
```
````
## 本地导入 Typora 默认主题
项目不会打包或提交 Typora 官方默认主题。如本机已安装 Typora，可以将 GitHub、Pixyll 和 Whitey 三套适合打印的白色默认主题及 Typora 基础 CSS 复制到 Git 忽略的本地主题目录：
apps/web/src/App.tsx
+130 -22
View File
@@ -8,7 +8,6 @@ import {
} from "react";
import {
getPaperDimensionsMm,
millimetersToCssPixels,
type ExportConfig
} from "@md-to-pdf/core";
import { ExportSettingsDrawer } from "./ExportSettingsDrawer";
@@ -22,6 +21,11 @@ import {
isPagedPreviewFrameMessage,
type PagedPreviewPayload
} from "./paged-preview";
import {
getNearestPageNumber,
PREVIEW_SCROLLBAR_WIDTH_PX
} from "./preview-page";
import { getSyncedScrollTop } from "./scroll-sync";
interface RenderedMarkdown {
articleHtml: string;
@@ -97,9 +101,18 @@ export function App() {
const [mermaidError, setMermaidError] = useState("");
const [paginationError, setPaginationError] = useState("");
const [previewFrameReady, setPreviewFrameReady] = useState(false);
const [previewHeight, setPreviewHeight] = useState(500);
const [previewPagination, setPreviewPagination] = useState({
current: 0,
total: 0
});
const editorRef = useRef<HTMLTextAreaElement>(null);
const previewScrollRef = useRef<HTMLDivElement>(null);
const previewFrameRef = useRef<HTMLIFrameElement>(null);
const previewRequestIdRef = useRef(0);
const scrollSyncFrameRef = useRef<number | undefined>(undefined);
const scrollSyncOriginRef = useRef<
"editor" | "preview" | undefined
>(undefined);
const error =
renderError || themeError || mermaidError || paginationError;
@@ -110,9 +123,8 @@ export function App() {
exportConfig.paper.orientation
);
const paperStyle = {
width: `${paperDimensions.width}mm`,
minWidth: `${paperDimensions.width}mm`,
minHeight: `${paperDimensions.height}mm`
width: `calc(${paperDimensions.width}mm + ${PREVIEW_SCROLLBAR_WIDTH_PX}px)`,
minWidth: `calc(${paperDimensions.width}mm + ${PREVIEW_SCROLLBAR_WIDTH_PX}px)`
} satisfies CSSProperties;
const previewPayload = useMemo<PagedPreviewPayload | undefined>(
() =>
@@ -274,6 +286,7 @@ export function App() {
if (event.data.type === "rendering") {
setPaginationError("");
setMermaidError("");
setPreviewPagination({ current: 0, total: 0 });
setStatus("正在分页…");
return;
}
@@ -284,24 +297,52 @@ export function App() {
return;
}
setPreviewHeight(
Math.max(
event.data.contentHeight,
millimetersToCssPixels(paperDimensions.height)
)
);
setMermaidError(
event.data.mermaidErrors.length > 0
? `Mermaid：${event.data.mermaidErrors.join("；")}`
: ""
);
setStatus(`预览已分页（${event.data.pageCount} 页）`);
setPreviewPagination({
current: event.data.pageCount > 0 ? 1 : 0,
total: event.data.pageCount
});
window.requestAnimationFrame(() => {
synchronizeScroll("editor");
window.requestAnimationFrame(updatePreviewCurrentPage);
});
}
window.addEventListener("message", handlePreviewFrameMessage);
return () =>
window.removeEventListener("message", handlePreviewFrameMessage);
}, [paperDimensions.height]);
}, []);
useEffect(() => {
const frameWindow = previewFrameRef.current?.contentWindow;
if (!frameWindow || !previewFrameReady) {
return;
}
function handlePreviewScroll() {
synchronizeScroll("preview");
updatePreviewCurrentPage();
}
frameWindow.addEventListener("scroll", handlePreviewScroll, {
passive: true
});
return () =>
frameWindow.removeEventListener("scroll", handlePreviewScroll);
}, [previewFrameReady]);
useEffect(() => {
return () => {
if (scrollSyncFrameRef.current !== undefined) {
window.cancelAnimationFrame(scrollSyncFrameRef.current);
}
};
}, []);
useEffect(() => {
const frameWindow = previewFrameRef.current?.contentWindow;
@@ -310,9 +351,6 @@ export function App() {
}
previewRequestIdRef.current += 1;
setPreviewHeight(
Math.ceil(millimetersToCssPixels(paperDimensions.height))
);
frameWindow.postMessage(
createPagedPreviewRenderRequest(
previewRequestIdRef.current,
@@ -320,11 +358,70 @@ export function App() {
),
window.location.origin
);
}, [
paperDimensions.height,
previewFrameReady,
previewPayload
]);
}, [previewFrameReady, previewPayload]);
function getPreviewScroller() {
return previewFrameRef.current?.contentDocument
?.scrollingElement as HTMLElement | null;
}
function synchronizeScroll(origin: "editor" | "preview") {
const source =
origin === "editor" ? editorRef.current : getPreviewScroller();
const target =
origin === "editor" ? getPreviewScroller() : editorRef.current;
if (!source || !target) {
return;
}
const activeOrigin = scrollSyncOriginRef.current;
if (activeOrigin && activeOrigin !== origin) {
return;
}
scrollSyncOriginRef.current = origin;
target.scrollTop = getSyncedScrollTop(source, target);
if (scrollSyncFrameRef.current !== undefined) {
window.cancelAnimationFrame(scrollSyncFrameRef.current);
}
scrollSyncFrameRef.current = window.requestAnimationFrame(() => {
scrollSyncOriginRef.current = undefined;
scrollSyncFrameRef.current = undefined;
});
}
function updatePreviewCurrentPage() {
const frame = previewFrameRef.current;
const frameDocument = frame?.contentDocument;
const scrollElement = getPreviewScroller();
if (!frame || !frameDocument || !scrollElement) {
return;
}
const viewportCenter =
scrollElement.scrollTop + frame.clientHeight / 2;
const pages = Array.from(
frameDocument.querySelectorAll<HTMLElement>(".pagedjs_page")
).map((page) => {
const rect = page.getBoundingClientRect();
return {
top: rect.top + scrollElement.scrollTop,
bottom: rect.bottom + scrollElement.scrollTop
};
});
const current = getNearestPageNumber(viewportCenter, pages);
setPreviewPagination((pagination) =>
pagination.current === current &&
pagination.total === pages.length
? pagination
: {
current,
total: pages.length
}
);
}
async function handleFileChange(event: ChangeEvent<HTMLInputElement>) {
const file = event.target.files?.[0];
@@ -379,10 +476,12 @@ export function App() {
</span>
</div>
<textarea
ref={editorRef}
aria-label="Markdown 内容"
value={markdown}
spellCheck={false}
onChange={(event) => setMarkdown(event.target.value)}
onScroll={() => synchronizeScroll("editor")}
/>
</aside>
@@ -392,6 +491,12 @@ export function App() {
<span className="panel-kicker">实时预览</span>
<strong>{result?.metadata.title || "未命名文档"}</strong>
</div>
<span className="preview-heading-actions">
{previewPagination.total > 0 ? (
<span className="preview-page-indicator" aria-live="polite">
第 {previewPagination.current} / {previewPagination.total} 页
</span>
) : null}
<label className="theme-control">
<span className="sr-only">预览主题</span>
<select
@@ -418,8 +523,12 @@ export function App() {
<span className="local-theme-mark">本地</span>
) : null}
</label>
</span>
</div>
<div className="preview-scroll">
<div
ref={previewScrollRef}
className="preview-scroll"
>
<div className="paper" style={paperStyle}>
{previewPayload ? (
<iframe
@@ -428,7 +537,6 @@ export function App() {
title="文档内容预览"
sandbox="allow-same-origin allow-scripts"
src="/preview-frame.html"
style={{ height: `${previewHeight}px` }}
/>
) : (
<div className="preview-loading">正在生成文档预览…</div>
apps/web/src/mermaid-config.ts
+3
View File
@@ -17,6 +17,9 @@ export function createMermaidSiteConfig(): MermaidConfig {
theme: "default",
look: "classic",
fontFamily: "Segoe UI, Microsoft YaHei, sans-serif",
flowchart: {
wrappingWidth: 320
},
maxTextSize: 50_000,
maxEdges: 500,
suppressErrorRendering: true,
apps/web/src/paged-break-token.ts
+15
View File
@@ -0,0 +1,15 @@
const ELEMENT_NODE_TYPE = 1;
export function resolveBreakTokenElement(
node: Node | undefined
): Element | undefined {
if (!node) {
return undefined;
}
if (node.nodeType === ELEMENT_NODE_TYPE) {
return node as Element;
}
return node.parentElement ?? undefined;
}
apps/web/src/paged-preview-frame.ts
+1
View File
@@ -25,6 +25,7 @@ function getPreviewRoot() {
}
const previewRoot = getPreviewRoot();
document.documentElement.dataset.renderTarget = "preview";
let latestRequestId = 0;
let renderQueue = Promise.resolve();
apps/web/src/paged-preview.ts
+23 -1
View File
@@ -2,6 +2,7 @@ import {
getPaperDimensionsMm,
type ExportConfig
} from "@md-to-pdf/core";
import { PREVIEW_SCROLLBAR_WIDTH_PX } from "./preview-page";
export const PAGED_PREVIEW_MESSAGE_SCOPE = "md-to-pdf:paged-preview";
@@ -335,7 +336,27 @@ ${
width: max-content;
min-width: 100%;
margin: 0 auto;
padding: 0;
padding: 34px 0;
}
html[data-render-target="preview"] {
height: 100%;
overflow-x: hidden;
overflow-y: scroll;
scrollbar-gutter: stable;
}
html[data-render-target="preview"]::-webkit-scrollbar {
width: ${PREVIEW_SCROLLBAR_WIDTH_PX}px;
}
html[data-render-target="preview"]::-webkit-scrollbar:horizontal {
height: 0;
}
html[data-render-target="preview"] body {
min-height: 100%;
overflow: visible;
}
.pagedjs_page {
@@ -354,6 +375,7 @@ html[data-render-target="pdf"] .pagedjs_pages {
display: block;
width: auto;
min-width: 0;
padding: 0;
}
html[data-render-target="pdf"] .pagedjs_page {
apps/web/src/paged-table-handler.ts
+7 -6
View File
@@ -1,7 +1,8 @@
import { Handler, registerHandlers } from "pagedjs";
import { resolveBreakTokenElement } from "./paged-break-token";
interface PagedBreakToken {
node?: Element;
node?: Node;
}
interface PagedChunker {
@@ -47,14 +48,14 @@ class RepeatTableHeadersHandler extends Handler {
breakToken?: PagedBreakToken
) {
this.splitTableRefs = [];
const node = breakToken?.node;
if (!node) {
const element = resolveBreakTokenElement(breakToken?.node);
if (!element) {
return;
}
const tables = elementAncestors(node, "table");
if (node.matches("table")) {
tables.push(node);
const tables = elementAncestors(element, "table");
if (element.matches("table")) {
tables.push(element);
}
this.splitTableRefs = Array.from(
apps/web/src/preview-page.ts
+34
View File
@@ -0,0 +1,34 @@
export interface PageVerticalRange {
top: number;
bottom: number;
}
export const PREVIEW_SCROLLBAR_WIDTH_PX = 14;
export function getNearestPageNumber(
viewportCenter: number,
pages: readonly PageVerticalRange[]
) {
if (pages.length === 0 || !Number.isFinite(viewportCenter)) {
return 0;
}
let nearestPage = 1;
let nearestDistance = Number.POSITIVE_INFINITY;
for (const [index, page] of pages.entries()) {
const distance =
viewportCenter < page.top
? page.top - viewportCenter
: viewportCenter > page.bottom
? viewportCenter - page.bottom
: 0;
if (distance < nearestDistance) {
nearestPage = index + 1;
nearestDistance = distance;
}
}
return nearestPage;
}
apps/web/src/scroll-sync.ts
+29
View File
@@ -0,0 +1,29 @@
export interface ScrollMetrics {
scrollTop: number;
scrollHeight: number;
clientHeight: number;
}
function clamp(value: number, minimum: number, maximum: number) {
return Math.min(maximum, Math.max(minimum, value));
}
export function getScrollProgress(metrics: ScrollMetrics) {
const range = metrics.scrollHeight - metrics.clientHeight;
if (range <= 0) {
return 0;
}
return clamp(metrics.scrollTop / range, 0, 1);
}
export function getSyncedScrollTop(
source: ScrollMetrics,
target: ScrollMetrics
) {
const targetRange = Math.max(
0,
target.scrollHeight - target.clientHeight
);
return getScrollProgress(source) * targetRange;
}
apps/web/src/styles.css
+25 -5
View File
@@ -166,12 +166,29 @@ h1 {
color: #a23d3d;
}
.theme-control {
.preview-heading-actions {
display: flex;
flex: none;
align-items: center;
justify-content: flex-end;
gap: 10px;
min-width: 0;
max-width: 68%;
}
.preview-page-indicator {
flex: none;
color: #5d7168;
font-size: 0.7rem;
font-variant-numeric: tabular-nums;
white-space: nowrap;
}
.theme-control {
display: flex;
min-width: 0;
align-items: center;
gap: 6px;
max-width: 56%;
}
.theme-control select {
@@ -245,11 +262,13 @@ textarea:focus {
.preview-scroll {
flex: 1;
min-height: 0;
overflow: auto;
padding: 34px;
padding: 0 30px;
}
.paper {
height: 100%;
margin: 0 auto;
background: transparent;
}
@@ -257,7 +276,8 @@ textarea:focus {
.preview-frame {
display: block;
width: 100%;
min-height: 500px;
height: 100%;
min-height: 0;
border: 0;
background: transparent;
}
@@ -576,7 +596,7 @@ textarea:focus {
}
.preview-scroll {
padding: 18px 10px;
padding: 0 10px;
}
.paper {
apps/web/tests/mermaid-config.test.ts
+1
View File
@@ -11,6 +11,7 @@ describe("Mermaid 站点配置", () => {
expect(config.look).toBe("classic");
expect(config.securityLevel).toBe("strict");
expect(config.startOnLoad).toBe(false);
expect(config.flowchart?.wrappingWidth).toBe(320);
});
it("锁定安全限制和原始主题 CSS", () => {
apps/web/tests/paged-break-token.test.ts
+35
View File
@@ -0,0 +1,35 @@
import { describe, expect, it } from "vitest";
import { resolveBreakTokenElement } from "../src/paged-break-token";
describe("Paged.js 分页断点", () => {
it("直接返回元素断点", () => {
const element = {
nodeType: 1,
parentElement: null
} as unknown as Element;
expect(resolveBreakTokenElement(element)).toBe(element);
});
it("文本断点使用父元素继续查找", () => {
const parentElement = {} as Element;
const textNode = {
nodeType: 3,
parentElement
} as unknown as Node;
expect(resolveBreakTokenElement(textNode)).toBe(parentElement);
});
it("安全跳过空断点和无父元素节点", () => {
const detachedTextNode = {
nodeType: 3,
parentElement: null
} as unknown as Node;
expect(resolveBreakTokenElement(undefined)).toBeUndefined();
expect(
resolveBreakTokenElement(detachedTextNode)
).toBeUndefined();
});
});
apps/web/tests/paged-preview.test.ts
+5
View File
@@ -38,7 +38,12 @@ describe("分页预览协议", () => {
expect(css).toContain("display: table-header-group");
expect(css).toContain("break-inside: avoid");
expect(css).toContain(".pagedjs_pages");
expect(css).toContain("padding: 34px 0");
expect(css).toContain('html[data-render-target="preview"]');
expect(css).toContain("overflow-x: hidden");
expect(css).toContain("overflow-y: scroll");
expect(css).toContain('html[data-render-target="pdf"]');
expect(css).toContain("padding: 0");
expect(css).toContain("break-after: page");
expect(css).not.toContain("@media print");
});
apps/web/tests/preview-page.test.ts
+24
View File
@@ -0,0 +1,24 @@
import { describe, expect, it } from "vitest";
import { getNearestPageNumber } from "../src/preview-page";
const pages = [
{ top: 0, bottom: 100 },
{ top: 124, bottom: 224 },
{ top: 248, bottom: 348 }
];
describe("getNearestPageNumber", () => {
it("返回视口中心所在的页面", () => {
expect(getNearestPageNumber(180, pages)).toBe(2);
});
it("在页间空隙中返回距离最近的页面", () => {
expect(getNearestPageNumber(110, pages)).toBe(1);
expect(getNearestPageNumber(116, pages)).toBe(2);
});
it("没有页面或中心坐标无效时返回 0", () => {
expect(getNearestPageNumber(20, [])).toBe(0);
expect(getNearestPageNumber(Number.NaN, pages)).toBe(0);
});
});
apps/web/tests/scroll-sync.test.ts
+51
View File
@@ -0,0 +1,51 @@
import { describe, expect, it } from "vitest";
import {
getScrollProgress,
getSyncedScrollTop
} from "../src/scroll-sync";
describe("编辑与预览滚动同步", () => {
it("按可滚动范围计算阅读进度", () => {
expect(
getScrollProgress({
scrollTop: 600,
scrollHeight: 1600,
clientHeight: 400
})
).toBe(0.5);
});
it("把源区域进度映射到目标区域", () => {
expect(
getSyncedScrollTop(
{
scrollTop: 600,
scrollHeight: 1600,
clientHeight: 400
},
{
scrollTop: 0,
scrollHeight: 5000,
clientHeight: 1000
}
)
).toBe(2000);
});
it("处理无滚动范围和越界位置", () => {
expect(
getScrollProgress({
scrollTop: 100,
scrollHeight: 500,
clientHeight: 500
})
).toBe(0);
expect(
getScrollProgress({
scrollTop: 1800,
scrollHeight: 1600,
clientHeight: 400
})
).toBe(1);
});
});