跳到主要内容

章 2 · 篇 I · 基础

Postext架构

Postext排版引擎的技术架构:核心概念、文档树、垂直韵律、后端与性能

更新于 2026-11-1620分钟enescadefritptzhjaar

简单来说

本页讲解Postext的内部工作原理,面向程序员。首先,Postext在不往屏幕上画任何东西的情况下测量每个词,所以速度很快。然后它算出每一行、每张图和每一栏的位置,并把这份排版方案保存在内存里。最后,它把排好的页面输出为网页、Canvas图像或PDF文件。你改动一个词时,它会把各页重新排一遍,并沿用未改动段落的测量结果。下一页一步步说明各行和各张图是怎样放上去的。

如果你用过React,就已经懂得这里的核心技巧。React先在内存里构建虚拟DOM,做差异比较,然后才去改动浏览器里真实的DOM。Postext做的是同一件事,只不过它构建的不是UI组件,而是一棵由页面、栏、文本块和边界框组成的树。一份多页、多栏文档的全部几何信息,在渲染出第一个像素之前就已算好。每个段落、标题、图片、脚注和引文框都放在精确的坐标上,并且遵守延续了几百年、CSS根本无法表达的排版规则。

这一切得益于@chenglou/pretext。它是一个不依赖DOM的文本测量库,比浏览器的布局重排快300–600倍。项目背后的故事(十年间的屡次失败、卡住所有尝试的那个瓶颈,以及最终消除它的那个库)见简介。

#核心思路

设想一份74页的双栏文档,比如一份公司年报,或者一本插图密集的教材。你把它交给Postext,引擎就在内存里构建出完整的版面:每一页、每一栏、每个段落的确切位置和像素尺寸。想知道第72页第2栏里有什么?答案已经在那里,不需要渲染。引擎已经决定好每个段落在哪里断行、每张图片放在哪里、怎样避免段末孤行和段首孤行,以及相邻各栏的基线如何对齐。

下面说说这一点为什么如此重要。

排版规则彼此牵连,而且牵连得让人头疼。第5页有一个段末孤行,也就是被孤零零留在栏底的最后一行,你把它拉回前一栏,问题解决了。可这一改动让第5页那一栏变短,内容随之后移,第6页就可能冒出一个段首孤行:段落的第一行被单独推到新的一栏,和段落其余部分分离。仅仅为了发现自己制造了新问题,你就需要整份文档的版面都可供检查。而要修正它又不在别处引出新问题,你就得能够调整、重新测量、重新检查整份文档。

这就是“先全部算好,再渲染”的理念。它不是性能技巧。专业排字工几百年来一直遵循几十条相互关联的排版规则,要运用这些规则,这是唯一的途径。

#核心概念

一份简短的术语表。本文后面默认你熟悉这些术语,哪个记不清了就回到这里查看。

术语定义
VDT虚拟文档树(Virtual Document Tree)。一种可原地修改的数据结构,表示整份文档:页面、栏、块、行内片段和边界框。类似虚拟DOM,但描述的是文档版面的几何信息。
页面一个固定尺寸的矩形区域。引擎从一开始就以页面为单位工作。文档是页面的有序序列。
栏页面在水平方向上划分出的竖直区域。栏有固定的宽度和最大高度。文本从一栏流入下一栏,再流入下一页。
块在栏中占据竖直空间的内容单元:段落、标题、图片、表格、块引用、引文框或脚注区。
行块内一行经过测量的文本,由Pretext生成。每行都有边界框和基线位置。
边界框{ x, y, width, height },单位为像素,相对于页面原点。VDT中的每个节点都带有一个边界框。
资源通过id与正文关联的非文本元素:位图、SVG、表格或视频(Resource,kind: 'bitmap' | 'svg' | 'table' | 'video')。资源在首次引用时按类型编号(图1、表2.1……),并浮动到该引用附近某页顶部或底部的一个区带中。
注释脚注或章末注,在Markdown中写成[^id]标记加[^id]:定义(见脚注)。旁注,以及内容模型所接受的PostextNote列表,都没有实现:引擎不读取notes。
基线网格由正文行距导出的竖直格子(例如16px/1.5对应24px)。每条正文基线都应落在它的整数倍上,使各栏之间、左右相对的两页之间的行保持对齐。
劣度(Badness)两端对齐的行中词间距偏离自然宽度的程度,即调整比的平方,上限为10000。它是Knuth-Plass断行中的基础代价。
缺陷值(Demerits)Knuth-Plass中一个候选断点的总代价:劣度加上各项惩罚值(断词、末行孤字、适配等级不匹配)。算法选出总缺陷值最低的一组断点。段落在两栏之间的拆分也以同样的方式选出,取段首孤行、段末孤行和余量三项代价之和最低的那一种。
适配等级(Fitness Class)对一行松紧程度的粗略分档。相邻两行分属差别很大的等级时(一行很紧,下一行很松),会额外计入一份缺陷值,使段落的灰度更均匀。
余量(Slack)段落在栏底拆分或整段后移时,栏底空出的行。引擎选择拆分位置时,把余量的平方代价(以slackWeight加权)与段首孤行和段末孤行的惩罚值一起权衡。
后端消费完成的VDT的渲染目标。目前已有四种:canvas(位图预览)、HTML(基于DOM的屏幕阅读)、PDF(通过postext-pdf输出可付印的文件)和EPUB(postext-epub,把整本书做成电子书)。四者共用同一套测量(基于Pretext的measure模块)。3D查看器postext-folio用Canvas后端绘制书页。
放置遍(Placement Pass)对内容的一次遍历,从第一个块到最后一个块,构建出一整棵VDT:解析,经由缓存测量,放置文本、浮动体和框,并执行分页规则和保持同页规则。
轮(Round)带着上一遍给出的提示把放置遍重新运行一次:栏带上限、齐底手段、已确定的页码标签或注释编号。每一类轮各有自己的上限(见放置遍的驱动器)。

#系统架构

Postext系统架构增强Markdown和PostextConfig进入解析器。放置遍用Pretext测量文本,并填充虚拟文档树;buildDocument带着提示重新运行这一遍,直到版面稳定。后端把完成的VDT渲染为HTML或PDF。排版引擎增强MarkdownPostextConfig(栏、规则、间距)解析器Markdown → 块Pretext文本测量虚拟文档树(VDT)由放置遍原地填充页面 > 栏 > 块每个节点都有bbox每一遍都是一棵新树放置遍(对内容的一次遍历)测量各行,经由缓存放置块,排入栏和页浮动资源,浮到页面区带断开栏末的段落保持标题和列表紧跟正文对齐文本流回到网格上带着提示重新运行后端(统一接口)Canvas / 浏览器PDFEPUBHTML / PDF渲染输出
解析器 → 放置遍 ↔ Pretext → VDT → 后端 → 输出。

内容在引擎中经历的过程如下:

  1. 解析器读取你的增强Markdown,把它变成一个由带类型的内容块组成的扁平列表:只有内容和结构,还没有位置
  2. 放置遍把这个列表遍历一次,构建出VDT。它按每个块即将进入的那一栏的宽度,通过Pretext测量这个块,把文本、浮动体和框放入页面和栏,并在行进中执行分页规则和保持同页规则
  3. 驱动器(buildDocument)在某个决定要依据整个版面的结果时重新运行这一遍,例如:要印出页码的目录;通栏框,它上方的各栏必须在同一高度结束;提前结束的一栏。每次重新运行都从前一遍取得提示,每一类重新运行各有自己的上限
  4. 最终的VDT就是完整的版面几何:每个元素都知道自己的页码、所在栏、位置和边界框。在任何渲染发生之前,文档就已完全“排好”
  5. 后端遍历完成的VDT,把它渲染成目标格式:栅格化的canvas位图、由定位HTML元素组成的DOM树、嵌入字体的PDF文档,或EPUB。同一份VDT供四者使用,选哪个后端纯粹是输出方面的决定

#输入层

#内容模型

内容模型既是一种数据结构,也是一种理念。你描述要说什么,而不是如何排版。版面上的决定由引擎来做。

内容模型:Markdown、资源、注释Postext的输入把Markdown(阅读顺序和语义结构)与资源(位图、SVG、表格)以及注释分开。引擎按ID解析行内的:ref引用和::resource嵌入,生成VDT。PostextContentmarkdown阅读顺序 + 按id的:ref / ::resource:ref{id=fig-1}::resource{id=tbl-1}resources[]位图、SVG、表格fig-1bitmapsvg-1svgtbl-1tablemetadata标题、作者、日期按id解析::ref{id=…}、::resource{id=…}引擎VDT
Markdown决定阅读顺序,资源提供视觉数据。
// packages/postext/src/types.ts
 
interface PostextContent {
  markdown: string;            // 带:ref / ::resource标记的增强markdown
  metadata?: DocumentMetadata; // 标题、副标题、作者、发布日期……
  resources?: Resource[];      // 位图、SVG、表格、视频,按id引用
  notes?: PostextNote[];       // 不读取:脚注在markdown中写成[^id]
  continuation?: LayoutContinuation; // 从前面各章延续下来的计数器和页码
  outline?: OutlineEntry[];    // 全书标题及其页码标签,供:::toc / :::index使用
  citations?: CitationContext; // 全书引文中属于本章的部分
  laterPageIds?: Record<string, number>; // 后续各章中可续排文字的页面块
  chapters?: { start: number; end: number }[]; // 整本书作为一个文档:各章所在的位置,每章按自己的章节样式排版
}
 
interface Resource {
  id: string;                  // 稳定的id,供行内:ref引用
  typeId: string;              // 该资源所属的ResourceType('figure'、'table'……)
  kind: 'bitmap' | 'svg' | 'table' | 'video';
  caption?: string;            // 类型前缀和编号由计算得出,不写在这里
  altText?: string;
  createdAt: number;
  updatedAt: number;
  // 恰好一种与kind对应的数据:
  bitmap?: { fileId: string; format: string; width: number; height: number };
  svg?: { fileId: string; width?: number; height?: number };
  table?: { model: TableModel };
  video?: ResourceVideo;       // 从哪里播放;页面上画的是它的封面
  placement?: ResourcePlacement; // 可选:单个资源覆盖浮动设置
  safeArea?: ResourceSafeArea;  // 位图 / svg:{ x, y, width, height },以比例表示,始终显示的部分
}

资源承载视觉数据:题注、替代文字,以及与其类型对应的数据。二进制数据(位图、SVG)存放在带外:资源只保存一个fileId,渲染器在绘制时再去解析它(沙盒把这些字节保存在IndexedDB里)。表格资源是例外:它的TableModel(一个带合并和对齐信息的单元格网格)随资源一起内联传递,因为它是结构化数据,而不是字节。 注释写在markdown里:引用脚注的地方写[^id]标记,定义[^id]:自成一段,可以放在本章的任何位置。引擎按首次引用的顺序给脚注编号,把每条脚注排在引用它的那一行所在栏的底部,上方有一条短线;设置footnotes.placement: 'chapterEnd'时,则排在该章最后一个块之后(见脚注和配置 › 脚注)。内容模型仍然接受notes数组,但流水线的任何阶段都不读取它。

这种分离是一个有明确取向的设计选择,其意义比看上去要大。markdown掌管阅读顺序和语义结构:什么在前,什么是标题,脚注在哪里被引用、写了什么。资源数组掌管视觉数据:图片尺寸、题注文字、表格单元格。两者分开后,同一份markdown只需改变配置,就能排成完全不同的样子。双栏的学术版式和单栏的博客文章可以共用同一份源内容。引擎也可以做出安放上的决定,比如因为这一栏放不下而把图片推迟到下一栏,却完全不必改动你的源内容。

// 示例:一篇引用了一幅图的简单文章
const content: PostextContent = {
  markdown: `
# The Art of Typography
 
The history of typography begins with Gutenberg's
movable type, shown in :ref{id="printing-press"}.
His invention transformed the production of books.
 
The technique spread rapidly across Europe, reaching
Italy by 1465 and France by 1470.
  `,
  resources: [
    {
      id: 'printing-press',
      typeId: 'figure',
      kind: 'bitmap',
      caption: 'A reconstruction of the original press.',
      altText: "Reconstruction of Gutenberg's printing press",
      createdAt: 1765379100000,
      updatedAt: 1765379100000,
      bitmap: { fileId: 'press-photo', format: 'jpeg', width: 600, height: 400 },
    },
  ],
};

资源通过id与正文关联,只要引用它,就能把它纳入文档。行内的:ref{id="printing-press"}同时做两件事:它在正文中渲染出资源经计算得到的编号(“Fig. 1”);并且在阅读顺序中的第一次引用处,把资源浮动到页面上,在该引用附近页面的顶部或底部预留一个区带,和印刷排字工的做法完全一样。你不需要再安放一次这幅图。少数资源必须位于文本流中的某个确切位置,这时可以把::resource{id="…"}单独写成一行,作为可选的块级嵌入:只有当资源解析后的placement.position为'here'(即不参与浮动)时,它才在原处渲染;对于浮动的资源,它只被当作又一次引用。作者从不需要考虑安放问题,由引擎来考虑。

引用解析Markdown源文件用:ref{id=printing-press}在行内引用一幅图,resources数组按ID提供实际内容。引擎解析这个引用,在正文中印出算好的编号,并把图浮动到页面顶部的区带中。markdown# The Art of Typographymovable type, shown in:ref{id=printing-press} …resources[]{ id: 'printing-press', kind: 'bitmap', … }::resource{id=…}placement为'here'时的可选嵌入解析排好的页面[图1:浮动到区带中]…shown in Fig. 1…
Markdown中的引用只是名称。引擎根据资源解析引用并编号,再把图浮动到引用附近。

#配置

排版流水线的每个方面都由PostextConfig控制。各部分的完整概览(页面、布局、正文、标题、列表、数学公式、页眉页脚……)见配置页;与本文关系最密切的是:

配置控制内容用于
bodyText / headings按字段设置的段末孤行/段首孤行/孤字惩罚值、保持不分离的规则、两端对齐的限度、断词,见配置 › 正文测量、分页与保持同页规则、各栏齐底
tableStylekind: 'table'资源的单元格排版、边框、圆角、表头和表体的填充,以及表格用table.styleId选用的tableStyles命名变体,见配置 › 表格样式资源放置
captionStyle资源题注的排版:带编号的标签和说明文字,见配置 › 题注样式资源放置
diagramStylesingleInk + inkColor:按亮度把SVG图表重新着色为同一种油墨的不同深浅,使图在单一专色印刷时也能忠实再现,见配置 › 图示样式后端
resourceTypes按类型的资源编号:模板、计数格式、重置范围、默认浮动位置,见配置 › 资源类型内容结构化、资源放置

#解析策略

解析有意设计成流水线中最简单的一步。Markdown输入后,输出一个由带类型的内容块组成的扁平列表(ContentBlock,位于packages/postext/src/parse/):标题、带行内片段的段落、列表项、指令。解析结果有记忆化(parseMarkdownMemo),所以同一次构建的各遍只解析一次,之后对同一文本的构建也是如此。资源引用在每个放置遍开始时按ID在resources[]数组中解析。脚注定义(以[^id]:开头的段落)也在这时离开文本流,按id保存,留给引用它们的标记;notes[]数组不读取。

可以把它看成一份清单:“先是一个标题,然后是一个200词的段落,然后是一处图的引用,然后又是一个段落。”没有测量,没有定位,也完全没有版面上的决定。只有在放置遍测量了一个块并给了它位置之后,VDTBlock才存在。

#虚拟文档树(VDT)

设想你请一位专业排字工排一整本书,他交给你的不是印好的页面,而是一张电子表格。每一行是一个元素,每个单元格是一个精确的测量值:“标题位于(40, 30),第一段从(40, 78)开始,高144px,图片放在第3页第2栏的顶部……”这张电子表格就是VDT。

虚拟文档树是Postext的核心数据结构:一棵可原地修改的树,表示每个页面、栏、块和行,每个节点都带有精确的边界框。buildDocument返回之后,VDT就是答案。你可以查询“第72页第2栏里有什么?”,而不必渲染一个像素。

#为什么是可变的

游戏引擎的渲染流水线也采用同样的做法:共享的可变世界状态在一个紧凑的循环里被各个系统依次更新。原因也相同。

放置遍原地填充这棵树。它打开一个页面,向页面追加栏,从块落入的那一栏的availableHeight中减去块的高度,并在通栏框切割栏带的地方封闭该栏带的各栏。一本书有几千个块,而不可变的树(比如React的虚拟DOM)会为其中每一步分配一个新对象。所以节点是普通对象,这一遍直接写入它们。

已经完成的一遍不会被修补。buildDocument需要再试一次时(一个栏带上限,一个齐底手段),它从内容出发重新运行这一遍,得到一棵新树。前一遍的树保持原样,驱动器因此可以比较两者,留下较好的那一棵,或者从两棵树中各取若干页。测量缓存让重新运行的开销可以承受:文本、字体和宽度都没有变化的段落从缓存中读出,不再重新测量。

#结构

虚拟文档树的结构层级化的VDT:文档包含页,每页包含栏,每栏包含块(标题、段落、资源),每个文本块包含测量过的行。每个块都带有边界框、类型以及所在页和栏的索引。VDTDocumentVDTPage [0]VDTPage [1]VDTPage [n]VDTColumn [0]VDTColumn [1]标题段落资源第0行第1行每个块都带有:bbox: { x, y, w, h }type: VDTBlockTypepageIndex: numbercolumnIndex: number行还带有:baseline: numberhyphenated: boolean
每个块都带有bbox、类型以及所在页和栏的索引。

#类型定义

下面的结构是为便于说明而简化的:packages/postext/src/vdt.ts中的实际定义还有许多面向渲染的字段(字体字符串、颜色、列表符号、公式渲染结果、设计槽位)。这里重要的是结构本身:

// 已简化,完整定义见packages/postext/src/vdt.ts
 
// 虚拟文档树的根
interface VDTDocument {
  pages: VDTPage[];
  blocks: VDTBlock[];         // 同一批块对象的扁平视图
  config: ResolvedConfig;     // 每个子配置都已解析为非可选值
  baselineGrid: number;       // 基线增量,单位px(例如16px/1.5对应24)
  converged: boolean;         // 每个齐底分段都已齐平结束,或已无手段可用
  iterationCount: number;     // 这份版面背后的放置遍数(见“放置遍的驱动器”)
  metadata: DocumentMetadata;
}
 
// 一个物理页面
interface VDTPage {
  index: number;
  width: number;
  height: number;
  columns: VDTColumn[];
  header?: VDTDesignSlot;     // 页眉(设计槽位)
  footer?: VDTDesignSlot;     // 页脚 / 页码
  floats?: VDTBlock[];        // 浮动到本页顶部/底部的资源区带
  pageNumberValue: number;
  pageLabel: string;          // 渲染出的标签('iv'、'7'、'A'……)
}
 
// 页面中的一栏
interface VDTColumn {
  index: number;
  bbox: BoundingBox;          // 在页面中的位置
  blocks: VDTBlock[];
  availableHeight: number;    // 剩余的竖直空间
  baselineOffset: number;     // 当前基线的y位置
  band?: number;              // 栏所在区带(除非有通栏块把页面分割开,否则为0)
  kind?: 'text' | 'span' | 'side'; // 'span' = 容纳通栏块的全宽栏,
                              // 'side' = 一栏半版式中只放浮动体的侧栏
}
 
// 一个内容块(段落、标题、资源等)
type VDTBlockType =
  | 'paragraph' | 'heading' | 'resource' | 'blockquote'
  | 'listItem' | 'footnoteRef' | 'mathDisplay' | 'callout' | 'code';
 
interface VDTBlock {
  id: string;
  type: VDTBlockType;
  bbox: BoundingBox;
  lines: VDTLine[];           // 用于文本块:经过测量的行
  resourceBlock?: ResolvedResourceBlock; // 用于资源块
  pageIndex: number;
  columnIndex: number;
  dirty: boolean;             // 未使用:块放置时清除,没有任何地方读取
  snappedToGrid: boolean;     // 文本流在这个块之下回到了基线网格
  balancing?: VDTBalancing;   // 作用于这个块的各栏齐底手段
}
 
// 一行经过测量的文本
interface VDTLine {
  text: string;
  bbox: BoundingBox;            // 自然宽度:两端对齐的行会一直画到所在块的右边缘
  baseline: number;             // 文本基线的y位置
  hyphenated: boolean;          // 行在词中结束,或在不带空格的破折号之后结束("say—" | "that’s")
  hardHyphen?: boolean;         // ……在文本自带的连字符之后结束("well-" | "known"):不添加任何字符
  repeatedHyphen?: boolean;     // 以重复的那个连字符开头("vencer-" | "-se"),源文本中没有它
  segments?: VDTLineSegment[];  // 供两端对齐渲染使用的词/空格/公式片段
  isLastLine?: boolean;         // 所在段落的最后一行
  justifiedSpaceRatio?: number; // 每个空格绘制的宽度 ÷ 正体的空格宽度
  justifiedSpaceLimitRatio?: number; // 上下限所约束的间距,行内空格不全是正体时才有(lineWordSpacing两个都读)
  sourceStart?: number;         // 到markdown源文件的映射(字符偏移;以`\$`开头的行从反斜杠算起)
  sourceEnd?: number;
  plainStart?: number;          // 到纯文本的映射
  plainEnd?: number;
  qr?: VDTLineQr;               // 链接注释的二维码(links.show),挂在注释的第一行
}
 
// 经过测量、可以安放的资源嵌入(位图 / svg / 表格 / 视频)
interface ResolvedResourceBlock {
  resource: Resource;
  kind: 'bitmap' | 'svg' | 'table' | 'video';
  number: string;             // 计算出的编号,例如"1.7"
  captionPrefix: string;      // 例如"Figure"
  bodyRect: BoundingBox;      // 图片 / 表格区域
  bodySource?: ResourceSafeArea; // 按安全区裁切时,图片在bodyRect中显示的部分
  bodyFlex?: { shrink: number; grow: number; delta: number }; // 主体还能缩短 / 增高的px,已改变的px
  fileId?: string;            // 带外的二进制数据(位图 / svg)
  captionLines: VDTLine[];    // 经过测量的题注,含前缀和编号
  table?: VDTResourceTableLayout; // 表格资源的单元格几何信息
}
 
// 边界框:所有值的单位为px,相对于页面原点
interface BoundingBox {
  x: number;
  y: number;
  width: number;
  height: number;
}

其中几个字段值得说明:

  • isLastLine控制两端对齐的渲染:即使段落两端对齐,最后一行也按齐左渲染。过满的最后一行除外,它的词间距会压缩以适应行长(TeX的粘连设置语义)。
  • sourceStart/sourceEnd和plainStart/plainEnd是源映射,把每一行分别映射回原始markdown和块的纯文本,编辑器集成靠它们实现光标和选区的同步。
  • VDTResourceTableLayout(及其VDTResourceTableCell条目)承载表格资源排好后的全部几何信息:各列的x边界、各行的y边界,以及每个单元格的矩形和其中经过测量的内容行,这样每个后端画出的表格都相同。
  • dirty和snappedToGrid在块被放置时写入,没有任何阶段和后端读取它们。新建的块上dirty初始为true,块放置时设为false;引擎不在树上跟踪变化,而是重新运行放置遍(见放置遍的驱动器)。如果文本流在某个文本块之后回到网格,该块的第一部分上snappedToGrid为true(见垂直韵律系统)。
  • balancing说明是哪些各栏齐底手段移动或拉伸了这个块;齐底没有处理的块不带这个字段(见各栏齐底)。
  • computePageTextExtent(page)是一个小的公共辅助函数,返回页面上文本实际覆盖的竖直范围(包括浮动体的题注)。调试叠加层用它让基线网格线只覆盖真正有文本的部分,而不延伸到空白的页面底部。

#垂直韵律系统

把一本排得好的书对着光举起来。左页的行与右页的行对齐。第1栏第5行的基线与第2栏第5行的基线处在完全相同的垂直位置。这就是垂直韵律,也是训练有素的眼睛评判排版质量时最先检查的事项之一。它也是Postext的关键特色之一。

当两栏都只有同一字号的正文时,对齐轻而易举:每行高度相同,基线自然对齐。难题出现在某一栏包含更大字号的标题、任意像素高度的图像,或块引用周围的额外间距时。这些元素“破坏”了网格:它们下方的内容偏移了一个不是基线增量整数倍的距离,这一栏的基线突然就与相邻栏错开了。视觉上的和谐消失了。

目标是把它找回来:即使标题、图像或其他非标准高度的元素只出现在一栏中,相邻栏的正文基线也必须水平对齐。

#基线网格

一切都以一个数值为基准。文档定义一个baselineGrid值,由正文的行距推导而来:例如,正文字号为16px、line-height为1.5时,基线网格为24px。每条正文基线都应落在这个值的整数倍上。这就是约定。

#破坏网格的元素

有些元素的高度不是baselineGrid的整数倍,因而不可避免地会破坏网格:

  • 标题(字号更大,行距不同)
  • 图像(任意像素高度)
  • 表格(高度可变)
  • 块引用(可能使用不同的字号或内边距)
  • 脚注区(栏底的脚注及其分隔线:该栏的文本区在它们上方结束)

#文本流如何回到网格

垂直韵律对齐第1栏的标题打破了基线网格,偏离12像素。放置这个标题时,引擎把该栏已用的高度向上取整到下一条网格线,于是标题下方多出12像素,下一行正文重新落在网格上。第2栏始终保持对齐。024487296120144168第1栏第2栏正文行(基线:24px)正文行标题(高36px)+12px间距调整正文(回到网格上)正文行已对齐放置时对齐网格1. 排入块:先是它的各行,再是它下方的间距(marginBottom)2. 把该栏已用的高度向上取整到下一条网格线3. 下一个块从那里开始,所以下方的间距是最小值4. snapToGrid: false保留精确的间距,直到下一个对齐网格的块
打破网格的元素一放下,它下方的空白就向上取整到网格,所以各栏的基线保持同步。

网格是在放置时逐块保持的。之后没有哪一遍会遍历各栏去找偏移。正文行的高度是一个网格行,所以从网格上开始的一串正文会一直留在网格上。放置遍排入一个可能离开网格的块之后,会在下一个块开始之前,把该栏已用的高度向上取整到下一条网格线。以这种方式对齐网格的块有:

  • 一串标题中的最后一个(连续的标题一个接一个,中间不对齐,由最后一个让其后的文本重新对齐);
  • 列表的最后一项,不论各项之间的间距如何;
  • 独立公式;
  • 标注框、代码清单,以及以行内方式嵌入的图或表;
  • :::paragraphs容器的最后一段,以及:::verse诗歌,两者用的都是自己的行距。

块下方的间距(marginBottom)在取整之前计入,所以这个边距是最小值,其余由网格决定。图中,第1栏在24px的网格上有一个高36px的标题,下方没有边距。它的底边越过网格线12px,对齐时补上12px,下一行正文就从网格上开始,与第2栏中旁边的那一行平齐。如果marginBottom为16px,底边会在52px处,对齐时会把它向上取整到72px。

浮动带以自己的方式保持网格,见第4阶段:顶部浮动带向上取整到整数个网格行,底部浮动体的锚定方式是让题注的最后一条基线落在网格上。各栏齐底按整数个网格行加空,所以也保持网格。

没有任何东西拿一栏去和另一栏比较。每一栏都从网格上开始,每次对齐都回到网格上,所以相邻各栏的行、左右相对两页的行,不需要第二遍就能对上。

不参与对齐。snapToGrid: false改为保留块下方的精确间距。它可以设在headings上(针对所有级别、某一级别或某个标题样式),也可以设在段落样式、标注框样式和codeStyle上。这样的块之后的文本可能不在网格上,直到下一个对齐网格的块为止。标注框内的文本遵循框自己的行距,没有网格。

#后端接口

文本测量只有一个事实来源:基于Pretext Canvas字体度量的测量模块。每个后端都从它生成的同一个完成的VDT进行渲染。

这是一个有意的选择,原因很关键:测量文本的方式必须与渲染文本的方式完全一致。设想测量使用Canvas字体度量,而某个渲染后端使用的PDF库字距调整表略有不同,那么版面就会与输出对不上。引擎测得能放进320px的行,渲染时可能放不下,也可能留出空隙。差一个像素,版面就不再可信。只测量一次,所有输出都按由此得到的几何数据渲染,各后端就不可能出现分歧:断行、栏高和资源位置在任何后端运行之前就已固定在VDT中。

例如,PDF后端正是因此不重新测量文本:它接收完成的VDT,把其中的像素坐标换算成PDF点。Canvas度量是事实来源,PDF只是传输载体。使用renderToPdf(来自postext-pdf包)时,传入的VDT与交给renderToCanvas或renderToHtml的完全相同,三种输出保证一致。

#API接口

后端是作用于VDTDocument的普通函数,而不是类层次结构。没有PostextBackend接口,只有每种输出的渲染入口及其所需的辅助函数:

// Canvas(来自'postext')
renderToCanvas(doc, options?): HTMLCanvasElement[];     // 每页一个canvas
renderPage(page, doc, options?): HTMLCanvasElement;     // 单页
renderPageToCanvas(page, doc, canvas, options?): void;  // 绘制到已有的canvas中
 
// Canvas资源图像注册表:以Resource的fileId为键的已解码图像
registerResourceImage(fileId, image, options?): void;   // options: { vector?, singleInk? }
unregisterResourceImage(fileId): void;
clearResourceImages(): void;
 
// HTML(来自'postext')
renderToHtml(doc, options?): string;
renderToHtmlIndexed(doc, options?): HtmlRenderIndex;    // 按页、按块的分解结果
 
// PDF(来自'postext-pdf')
renderToPdf(doc, options): Promise<Uint8Array>;
 
// EPUB(来自'postext-epub'),按顺序传入一本书的各章
renderToEpub(docs, options): Promise<Uint8Array>;
 
// SCORM(来自'postext-scorm'),把EPUB写入器的内容打包给LMS使用
renderToScorm(docs, options): Promise<Uint8Array>;

由于资源的二进制数据在带外传递,每个后端以自己的方式解析fileId。Canvas后端维护一个已解码CanvasImageSource的注册表:宿主应用用registerResourceImage(fileId, image)把每个位图或SVG注册一次,渲染器在绘制时查找。HTML后端在选项中接收一个resourceImageUrl(fileId)解析函数,生成指向宿主返回的URL(object URL、data URI、CDN路径)的<img>标签。PDF后端接收一个resourceBytes提供函数,嵌入实际的字节;EPUB写入器也接收这样一个函数,每张图片只作为书中的一个文件存一次。视频资源绘制为它的封面,和其他位图一样;HTML后端还接收一个resourceVideoUrl(fileId)解析函数,用于它要播放的视频文件,EPUB写入器则把这些文件存放在media/下。PDF后端把播放标记和二维码以矢量路径画在封面上;video.linkPoster开启时,还在封面上方加一个打开video.link的URI链接注释。在带标签的PDF中,这个链接归入封面的Figure,其替代文字以类型名称开头(视频:…)。表格资源不需要这些:它们的模型是内联的,每个后端都按VDT中的表格几何数据绘制单元格。

renderToHtmlIndexed值得单独说明:除了完整的HTML字符串,它还返回按页、按块的分解结果(HtmlRenderIndex),调用方可以与上一次渲染做差异比较,只修补HTML确实发生变化的DOM子树。沙盒的实时预览走的就是这条路径。

#后端

后端测量渲染状态
CanvasPretext(Canvas字体度量)在HTMLCanvasElement上绘制位图(renderToCanvas、renderPage、renderPageToCanvas)已发布
HTMLPretext(与Canvas相同的度量)使用绝对定位的DOM节点和书刊排版CSS(renderToHtml、renderToHtmlIndexed)已发布
PDF接收已由Pretext测量过的VDT通过pdf-lib构建PDF页面,按字重嵌入字体(postext-pdf中的renderToPdf)已发布
EPUB接收已由Pretext测量过的VDTEPUB 3文件:每个印刷页(固定版式)或每章(流式版式)一个XHTML文档,嵌入字体(postext-epub中的renderToEpub)已发布
SCORM接收已由Pretext测量过的VDT供学习管理系统使用的SCORM 1.2或2004 zip文件:EPUB写入器的页面或文字做成HTML5,每个SCO配一个播放器,练习报告得分、完成情况和是否通过(postext-scorm中的renderToScorm)已发布
Folio(3D查看器)接收已用Pretext测量好的VDT每一页由Canvas后端绘制(renderPageToCanvas),作为three.js书页的纹理显示,只绘制打开的跨页附近(postext-folio中的createFolioFromDocument)已发布
命令行基于Skia(@napi-rs/canvas)的Pretext,由Skia代替浏览器的CanvasPDF、HTML和EPUB写入器,以及页面图像和Word,在终端中运行,不需要浏览器(postext-cli);Python和Rust可通过pip install postext和cargo add postext使用它已发布

四个后端和Folio查看器都接收同一个VDTDocument。postext(导出Canvas和HTML后端)与postext-pdf(导出PDF后端)的拆分纯粹是出于依赖考虑:PDF路径会引入pdf-lib和@pdf-lib/fontkit,而大多数Web集成并不需要它们。只有在确实要输出PDF字节时才安装postext-pdf。postext-epub出于同样的原因单独成包,只在制作电子书时需要;postext-scorm建立在它之上,把EPUB写入器的内容打包给学习平台,因此本身不算一个后端。命令行不是第五个后端:postext-cli在没有浏览器的地方运行同样这些写入器。Word文件也不是,它们在这些后端旁边(postext/word):semanticDocx把Markdown各章及其样式写成.docx,不经过排版;formattedDocx写出生成PDF的同一条VDTDocument链的页面;applyDocxEdits把在两者中做的校改带回Markdown。readDocx配合wordToPostext把其他任何Word文件读成Markdown。

排版在哪里运行:引擎在Canvas上测量文本,所以只要有Canvas就能运行。在浏览器中,流水线既可以在主线程上运行(buildDocument),也可以在专用的Web Worker中运行(postext/worker中的createLayoutWorker)。对于由UI驱动的应用,推荐使用工作线程方式:它让测量和放置遍远离主线程,可以用AbortSignal取消旧的构建、只保留最后一次,并拥有自己的测量缓存和数学公式光栅缓存,使连续的重新构建保持低开销。完整的集成模式参见配置 › 在Web Worker中运行排版。在浏览器之外,命令行用Skia代替浏览器的Canvas运行同一条流水线,所以同一本书在终端、脚本或构建服务器上分出的页面完全相同。

#性能策略

迟钝的工具和神奇的工具之间大约差10倍。500ms的排版意味着用户每改动一个词都会看到明显的卡顿。50ms的排版则感觉是即时的,仿佛文档一直就在那里。这个差距没法事后补上,必须从第一天起就设计进去。

想想引擎要面对的是什么:几百页中的几千个文本块,每次编辑都要重新排一遍,版面需要各轮处理时还要排上好几遍。游戏引擎面对的是同一类问题:每秒60次处理几千个对象(几何、物理、光照、AI)。它们的解决办法是不重复已经做过的工作。Postext把这个办法用在自己开销最大的地方,也就是文本测量上。

#原则

  1. 内存中计算。整个VDT都能放进内存。排版期间不读取DOM。DOM只在最后渲染时才会被触及。

  2. 在缓存的测量结果上跑完整的一遍。重新运行放置遍时不去找哪里变了:它从第一个块开始把文档重新放置一遍。这之所以负担得起,是因为开销大的测量部分按段落缓存(原则5)。如果某一遍没有改变一个段落的文本、字体或宽度,它就从缓存中读出该段落的各行。

  3. 有界的轮。每一类重新运行都有固定的上限(见放置遍的驱动器),各栏齐底除了每个分段的上限之外还有每份文档的上限,所以章数很多的书不会无止境地消耗放置遍。一次构建的开销可以逐遍测量:BuildDocumentOptions.onPass报告每一遍及其实际耗时。

  4. Pretext的速度。文本测量速度是DOM的300至600倍,因此引擎可以投机性地重新测量文本(尝试不同的栏宽、断词点、字距调整),而不会阻塞主线程。

  5. 分层的测量缓存。测量模块(packages/postext/src/measure/)在Pretext自己的prepare()缓存和底层文本宽度缓存之上,维护一个显式的测量缓存,以文本、字体、宽度和所有影响版面的选项为键。重新测量一个未改动的段落只需一次映射查找。某个字体族的字体变化时,引擎丢弃该字体族的宽度和Pretext的缓存,测量缓存则在下一次查找时丢弃用该字体族排出的块(它记着自己是在哪个代次下填充的),因此字体加载完成后字形宽度是正确的,宿主不必调用任何函数;clearMeasurementCache()丢弃所有字体族。

  6. 热路径上的断行。Knuth-Plass的活动节点处理为速度而重写:节点退出时就地压缩活动集合,候选节点按(行,适配等级)去重,每个键只保留缺陷值最低的节点。算法结果完全相同:断点组合不变,只是计算得更快。同一个断行算法也用Rust写了一份(rust/crates/linebreak),编译成WebAssembly并内嵌在包中:它以相同的顺序做相同的运算,速度快两到三倍,只要模块已编译完成就由它作答。在页面主线程上,模块在后台编译;在此之前,或在缺少WebAssembly、WebAssembly被拒绝的环境中,由TypeScript版本作答。initLineBreaker()可以提前开始编译;useWasmLineBreaker(false)让所有段落都用TypeScript版本断行。

  7. 在主线程之外构建。postext/worker入口在专用的Web Worker中运行整个流水线。主线程发送{ content, config }和一个AbortSignal;工作线程注册字体(以ArrayBuffer转移),运行放置遍,再发回完成的VDTDocument。新的build()调用会以协作方式取消上一次调用:工作线程运行buildDocumentAsync,它在每个块处和各遍之间查询取消钩子,并抛出BuildCancelledError,因此在编辑器中打字的用户从不需要等待一个已被取代的排版。工作线程还维护自己的持久测量缓存和一个以内容为键的数学公式光栅缓存,使经过结构化克隆的MathRender对象在多次重新构建之间保留下来,无需重新光栅化。

  8. 双重访问的VDT。树结构(pages > columns > blocks)为按页或按栏进行的工作提供层级访问(各栏齐底测量每一栏底部的空隙)。一个并行的扁平blocks[]数组可以直接访问每一个块,不论它位于何处(注释编号轮从中读出每条注释印出的标记)。两种视图引用相同的块对象(没有重复,只是遍历同一份数据的两种方式)。

#重新排版

内容或配置发生变化时(一次按键,换一种页面尺寸),宿主再次调用buildDocument,得到一份新文档。从一次构建延续到下一次构建的有两样东西:测量结果,以及对正在编辑的文档而言,上一次的排版。

记录带。createLayoutTapes(options?)返回LayoutTapes,即一个文档排版过程的检查点。在该文档的每次构建中把它作为BuildDocumentOptions.tapes传入。编辑之后,每个放置遍从被编辑块之前的最后一个检查点开始,在其排版与上一次重新吻合的地方停下;此后的页面直接沿用,只移动它们在Markdown中的位置。得到的文档与不带记录带的构建完全相同。设置options.restBelowPages后,页数少于该值的文档不使用记录带排版,直到页数重新达到该值,因为在短章上,记录的开销超过节省的时间。tapes.stats说明上一次构建的每一遍从哪里开始,以及为什么不能更早开始。一套记录带只服务一个文档;两次构建之间,不得原地修改该文档的内容、配置和资源。排版工作线程保留一套记录带,供tapesKey指明正在编辑的章的那次构建使用,并且只发送有变化的页面。

测量。用createMeasurementCache()创建一次MeasurementCache,把它作为第三个参数传给每一次buildDocument调用。文本、字体、宽度和断行选项都没有变化的段落从缓存中读出,所以每次按键都重新排版的编辑器只需测量正在输入的那个段落。从缓存读出的行与缓存共用词片段,所以要修改已排版文档中某个片段(例如颜色)的代码,应在该行的segments里放入一份副本,而不是直接写入原片段。页面尺寸或栏数的变化会改变宽度,这些段落就要重新测量;Pretext的prepare()结果仍然有效,因为它们取决于字体和文本,与宽度无关,所以只需运行低开销的layout()算术。解析结果也有记忆化。模板页也会延续下来:模板、Markdown、样式和字体都没有变化的模板页直接沿用上一次构建的结果(composed/pageMemo.ts),所以在由模板页组成的章里编辑某一页,只会重排这一页。含有脚注、交叉引用、引文、目录或索引列表、漫画条的页面则总是重新排版。

对于实时编辑器,createLayoutWorker(来自postext/worker)在主线程之外完成这一切:工作线程拥有一个与它同寿命的测量缓存,新的build()会取消正在进行的那一次。见配置 › 测量缓存和在Web Worker中运行排版。

#基准测试

packages/postext/src/__bench__/中有三个基准测试。pnpm test跳过它们;在packages/postext中运行pnpm bench才会执行。chapter.bench.test.ts把一个教材篇幅的章(四十节,含标题、段落和列表)对着空的测量缓存排五次,再对着热缓存排五次,报告两个中位数和放置遍数。cjkChapter.bench.test.ts排《红楼梦》第1回,并统计送入measureText的字符数,以确保CJK排版器的开销与段落长度成线性关系。composedPage.bench.test.ts对一章二十个模板页计时:冷构建、无改动的重新构建、修改某一页的一个属性、在某一页的一个框内编辑,每种情况都分别在启用和不启用模板页记忆时测量。

// 摘自packages/postext/src/__bench__/chapter.bench.test.ts
const cold: number[] = [];
for (let i = 0; i < ROUNDS; i++) cold.push(time(() => buildDocument({ markdown }, config, createMeasurementCache())));
 
const warmCache = createMeasurementCache();
buildDocument({ markdown }, config, warmCache);
const warm: number[] = [];
for (let i = 0; i < ROUNDS; i++) warm.push(time(() => buildDocument({ markdown }, config, warmCache)));
 
const passes: BuildPassInfo[] = [];
const doc = buildDocument({ markdown }, config, createMeasurementCache(), { onPass: (p) => passes.push(p) });
// [bench] chapter: … pages, … passes (… ms), iterationCount=…; cold median … ms, warm median … ms (5 rounds)

需要如实说明一点:Node中没有Canvas,所以这些基准测试都用桩代替文本测量,它们的绝对时间不是浏览器中的时间。冷缓存与热缓存的比值以及放置遍数则与浏览器中一致,其中任何一项退化,都会先在这里显现,然后才在沙盒中显现。章和模板页的基准测试只报告数字,不会让构建失败;中文的那个则断言测量的字符数低于最长段落长度的三倍。它们都不在CI中运行:性能退化是在热路径改动时通过对比多次运行的数字发现的(Knuth-Plass活动节点重写时就是这样做的)。目前没有哪次构建会因为耗时变长而失败:性能退化要靠测量和代码审查来发现。

第四个基准测试用真实的文字测量(Skia,与 CLI 相同)为整本书计时。在 packages/postext-cli 中运行 bun scripts/bench-layout.ts --runs 3 --stages <book>,会逐章冷启动排版一本书,并输出每次运行的时间、内存、页面的哈希值以及各阶段所占的份额:测量、断行、放置和各遍之后的工作。Layout timing 工作流在每次发布后于 GitHub 运行器上对五本示例书运行它,并把表格写入该次运行的摘要;它只报告,不会让任何检查失败。每次运行还会在同一台运行器上排版推送之前的提交,与新提交轮流进行:两台运行器之间的差距比大多数改动节省的时间还大,所以要看的是同一次运行之内的差值。以下是 1.88.1 的数字(2026 年 11 月 16 日,三次运行的中位数,单线程);最后三列是占该次运行的份额。

| 书 | 页数 | 时间 | 每页 | 测量 | 断行 | 放置 | | --- | ---: | ---: | ---: | ---: | ---: | ---: | | Don Quijote | 142 | 0.58 s | 4.1 ms | 22 % | 20 % | 18 % | | Paradise Lost | 402 | 2.12 s | 5.3 ms | 29 % | 8 % | 25 % | | Física universitaria (OpenStax) | 122 | 0.91 s | 7.5 ms | 25 % | 12 % | 35 % | | ألف ليلة وليلة | 2,700 | 26.6 s | 9.8 ms | 49 % | 5 % | 23 % | | 紅樓夢 | 2,030 | 3.55 s | 1.8 ms | 48 % | 0 % | 12 % |

#数据流

引擎中的数据流内容和配置进入放置遍,它对每个块做结构化、测量和放置,让资源浮动,并执行分页规则和保持同页规则。buildDocument带着提示重新运行这一遍,直到每一轮都稳定下来。完成的VDT交给后端,由后端渲染出HTML或PDF。内容 +配置放置遍1结构化2测量3放置4浮动体5保持同页带着提示重新运行,每一轮不超过各自的上限VDT(已完成)后端:渲染HTML / PDF
端到端的数据流:一个放置遍,带着提示重新运行,然后渲染。

#不做的事

下面每一条限制都是有意的取舍。引擎本身已经足够复杂,再去承担本该由别处负责的工作,最容易让它永远做不完。

  • 所见即所得编辑。Postext是排版引擎,不是编辑器:输入内容,输出几何信息。构建交互式编辑界面(光标管理、选区、撤销/重做、输入处理)是另一个完全不同的问题。Postext可以作为编辑器的渲染后端,但它本身不提供编辑功能。
  • CSS column-count的封装。Postext取代CSS多栏布局,而不是在它外面包一层。它从零开始计算精确定位的几何信息,因为浏览器的分栏算法无法控制资源的摆放、段首孤行和段末孤行的避免,以及跨栏的排版规则。而这些恰恰是Postext存在的意义。
  • 响应式断点管理。Postext按给定的页面尺寸计算版面。何时重新排版(视口尺寸变化、屏幕方向变化时)由调用方决定。Postext不管理断点、媒体查询,也不替你做响应式设计的决定。那是你的工作。
  • 实时协同编辑。Postext是无状态的排版计算(输入内容,输出几何信息),不是带冲突解决、操作变换或多用户感知的协同文档系统。
  • 字体文件。postext包负责加载字体,但不自带字体。prepareFonts在第一次构建之前加载配置及其文本要求的所有字体,字体集无法提供的字体会作为fontFallback列在文档的警告中。文件本身由宿主提供:页面上的一条@font-face规则,或者一个说明每个字体在哪里的resolve函数。见配置 › 排版前加载字体。

#附录:与现有类型的对应关系

packages/postext/src/types.ts中定义的主要类型与上文所述架构的对应关系如下:

类型在架构中的作用
PostextContent入口:引擎的输入(内容结构化)
PostextConfig控制放置遍的每个阶段以及围绕它的各轮
Resource带类型的位图/SVG/表格/视频资源。在测量阶段变成ResolvedResourceBlock,随后要么成为类型为'resource'的行内VDTBlock(摆放位置为'here'),要么成为页面浮动带中的浮动体(资源放置)
ResourceType决定按类型编号、题注前缀、引用标签和默认浮动位置(内容结构化、资源放置)
ResourcePlacement单个资源的浮动覆盖设置:position('auto' / 'top' / 'bottom' / 'here')和span('column' / 'page' / 'side'),外加rotate、width、align、columns、captionSide、shrink、minScale、captionMeasure、wrap、wrapGap和citingPage;每个字段没有设定时取类型的defaultPlacement,在资源放置时解析
PostextNote引擎不读取它。脚注写在Markdown中([^id]),排在引用它的那一栏的栏脚或章末;旁注尚未实现
PostextResource已弃用。旧版内容模型中的资源,只保留到最后一处渲染器引用(VDTBlock.resource)迁移到Resource模型为止

#VDT类型在哪里

VDT类型(VDTDocument、VDTPage、VDTColumn、VDTBlock、VDTLine、VDTLineSegment、ResolvedResourceBlock、VDTResourceTableLayout、BoundingBox等)位于packages/postext/src/vdt.ts,与工厂辅助函数(createVDTDocument、createVDTPage、createVDTBlock……)和computePageTextExtent放在一起。没有单独的后端接口模块:后端接口一节所述的渲染入口直接从postext(Canvas、HTML)、postext-pdf(PDF)和postext-epub(EPUB)导出。

#排版食谱中的示例

用到本页内容的食谱,每道列在最贴切的小节下。每道食谱都把页面和完整脚本并排展示。