像Word一样智能分页:Markdown Resume 自动分页的代码原理剖析

原创2026-11-01 20:41:091,910 阅读

像Word一样智能分页:Markdown Resume 自动分页的代码原理剖析

📄 Markdown Resume 是一款免费、开源、本地优先(Local-first)的 Markdown 简历编写工具:简历、图片、设置全部保存在浏览器本地,内容不上传任何服务器。它最亮眼的体验之一,就是像 Word 一样的自动分页——你只管用 Markdown 写内容,它会自动把内容切分到一张张 A4 纸上,实时预览、所见即所得。本文将带你深入源码,剖析 Markdown 自动分页背后的实现原理。

为什么"网页自动分页"是个难题?

在 Word 或 LaTeX 里,分页是排版引擎的核心能力;而网页天生是无限滚动的,浏览器只管把内容一屏屏往下排,从不会主动"撕纸"。

要在浏览器里模拟纸张效果,需要回答三个问题:

  1. 一张纸有多高?→ 纸张高度减去上下边距 = 可用内容高度
  2. 内容放到哪儿该换页?→ 逐块测量高度,累加到"放不下"就切断
  3. 什么时候重新算一遍?→ 内容、字体、行距、边距一变就要重算

Markdown Resume 用一个名为 vue-smart-pages 的自研组件来解决这三个问题,源码位于 app/libs/vue-smart-pages/ 目录。

分页算法核心:测量 + 累加 + 切断

整个"智能"的大脑,就在 50 多行的 breakPage.ts 里,思路概括为三步:

第 1 步:算出每页可用内容高度 contentH = height - top - bottom;

第 2 步:逐个测量页面顶层子元素,用 clientHeight 加上上下 margin 得到它真实占用的垂直空间;

第 3 步:累加到放不下,就插入"换页条"。核心循环(摘自源码)如下:

for (const child of Array.from(page.children)) {
  const style = window.getComputedStyle(child);
  const childH = child.clientHeight
    + parseInt(style.marginTop) + parseInt(style.marginBottom);

  // 本页放不下,或遇到 \newpage 标记,就插入换页条
  if (pageH + childH > contentH || child.className === NEW_PAGE) {
    newPage.appendChild(getPageBreakElement(height - pageH - top));
    pageH = 0; // 新页从零开始累计
  }

  newPage.appendChild(child.cloneNode(true));
  pageH += childH;
}

所谓"换页条",就是一个带 vue-smart-page-break 类的 <div>,它有两个巧思:

  • margin-top 恰好等于本页剩余空间,把内容顶到当前页底部,视觉上形成纸张分界;
  • 通过负 margin(marginLeft: -left)横向撑开,覆盖页边距区域,让每一页都铺满整张纸。

⚠️ 设计细节:算法只按"块"为单位切页——一个段落或列表项要么整块留在本页,要么整块挪到下一页,不会把一条经历拦腰劈成两半。这正是简历场景的理想行为。

\newpage 手动分页:LaTeX 风格怎么实现的?

自动分页之外,它还支持 LaTeX 风格的手动分页。解析逻辑在 markdown-it-latex-cmds:

  • \newpage 被 markdown-it 插件解析为空标签 <div class="md-it-newpage"></div>;
  • \[10px] 同理被解析成一个 margin-top: 10px 的占位块,用来精确控制空行间距。

上面分页循环里的 child.className === NEW_PAGE 判断就是为它服务的:遍历到这个 div,无条件换页。一个"占位 div"加一行判断,就完成了从 Markdown 语法到真实分页的打通。

何时重算分页?响应式监听 + 防抖节流

改一个字就全量重算 DOM 显然浪费。SmartPages.ts 用监听 + 200ms 防抖来节流重算:

变化来源 处理策略
内容、纸张尺寸、边距 防抖后立即重新分页
行距、段落间距、字号、自定义 CSS 同样防抖重算
中英文字体切换(watchDelay) 额外延迟 100ms 再测量

🔤 为什么字体要特殊对待?因为字体文件是异步加载的,字还没下载完就测量高度,结果不准。所以 ResumeRender.vue 通过 before-break-page 钩子先调用 onFontLoaded,用浏览器原生 document.fonts.load() 等待中英文字体就绪后才开始测量——这是排版精确的关键一步。

页面容器的宽高与边距,则由 injectCSS 动态注入样式表驱动:优先使用浏览器新的 Constructed Style Sheets 接口,不支持时回退到传统 <style> 标签。

纸张换算:从毫米到像素

A4 纸是 210 × 297 mm,浏览器却只认像素。data.ts 里给出了两套纸张规格与换算系数:

export const PAPER = {
  A4:     { h: 297 + 2,     w: 210 },     // A4
  letter: { h: 279.4 + 3,   w: 215.9 }    // US Letter
};
export const MM_TO_PX = 3.78;

getPaperPx() 负责毫米 → 像素换算。高度多出的 2~3 mm 余量是有意为之:抵消不同打印机物理边距的差异,避免最后一行内容被"挤"出纸外。

导出 PDF:屏幕分页是仿真,打印才用真分页

这里有个容易误解的点:屏幕上看到的一页页纸张其实是前端仿真——用换页条把长文档视觉上切成了纸;而导出 PDF 时,走的是浏览器的真实打印分页。resumeExport.ts 生成的打印样式表里有一行关键 CSS:

@media print {
  @page { size: A4; margin: 0; }
  .md-it-newpage { page-break-before: always; break-before: page; }
}

@page 把纸张尺寸交给浏览器,普通内容交给打印引擎自然流动,只有 \newpage 标记处才强制"撕纸"。两套机制各管一段,最终实现屏幕所见即打印所得(WYSIWYG)。

源码导读清单

模块 文件 作用
分页核心算法 breakPage.ts 测量、累加、插入换页条
智能分页组件 SmartPages.ts 监听样式变化、防抖重算
LaTeX 命令解析 markdown-it-latex-cmds 解析 \newpage、\[10px]
渲染入口 ResumeRender.vue 组装纸张参数、等待字体就绪
纸张规格 data.ts A4 / Letter、mm→px 换算
导出打印样式 resumeExport.ts @media print 真实分页

想自己跑起来看看?

git clone https://gitcode.com/gh_mirrors/markdownresu/markdown-resume
cd markdown-resume && pnpm i && ./build.sh

打开本地预览地址,在简历里敲一个 \newpage,就能亲眼看到分页算法"撕纸"的全过程。

✨ 小结:Markdown Resume 的自动分页 = 块级测量累加(模拟分页)+ 字体就绪后再测量(精度保证)+ CSS 打印分页(真实导出)。三者配合,才让 Markdown 在浏览器里拥有了 Word 般的"纸张感"。

登录后查看全文
markdown-resume