# 以编程方式使用：HTML、3D书本与EPUB
> 把排好的书放进网页，用postext-folio做成3D书本，用postext-epub做成固定版式或流式版式的EPUB 3
- HTML版本: https://postext.dev/zh/docs/configuration-html-folio-epub
- 最后更新: 2026-10-16
- 阅读时间: 12分钟
- 其他语言: [en](https://postext.dev/en/docs/configuration-html-folio-epub.md), [es](https://postext.dev/es/docs/configuration-html-folio-epub.md), [ca](https://postext.dev/ca/docs/configuration-html-folio-epub.md), [de](https://postext.dev/de/docs/configuration-html-folio-epub.md), [fr](https://postext.dev/fr/docs/configuration-html-folio-epub.md), [it](https://postext.dev/it/docs/configuration-html-folio-epub.md), [pt](https://postext.dev/pt/docs/configuration-html-folio-epub.md), [ja](https://postext.dev/ja/docs/configuration-html-folio-epub.md), [ar](https://postext.dev/ar/docs/configuration-html-folio-epub.md)
## 简单来说
本页写给写代码、想在屏幕上展示一本书的人。第一节把页面放进网页，并说明这种视图和Canvas、PDF有什么不同。第二节把书以3D形式摊开在桌面上，读者可以翻页。最后一节制作EPUB电子书，页面可以固定，也可以让文字随屏幕重新排列，并检查这个文件。
## 集成HTML查看器
HTML查看器是Postext面向屏幕的渲染器。它不把页面栅格化成位图，而是输出绝对定位的DOM节点，节点的几何位置来自生成印刷输出的同一条流水线。如果你想在浏览器里呈现可读、可选中、能随窗口尺寸变化的排版，又不想引入PDF阅读器，比如做一个阅读应用、产品内预览或嵌入式文档界面，它就是合适的选择。
公共API中的关键部分：
- **`buildDocument(content, config, cache?)`**：运行完整的排版流水线，返回一个`VDTDocument`。
- **`renderToHtmlIndexed(doc, options)`**：把VDT转成一个HTML字符串，外加按页、按块的拆分结果。两次渲染之间只有少数块变化时，可以借助这份拆分廉价地修补DOM。
- **`resolveHtmlViewerConfig(partial)`**：补齐HTML查看器的默认值（`maxCharsPerLine`、`columnGap`、`optimalLineBreaking`）。
- **`buildFontString` + `measureGlyphWidth` + `dimensionToPx`**：测量原语，用来根据目标字符数算出实际的栏宽像素值。
- **`createMeasurementCache` / `clearMeasurementCache`**：可插拔的缓存，让多次重新排版复用测量结果。
- **`prepareFonts` / `buildDocumentWithFonts` / `watchFonts` / `onFontsChanged`**：在排版前加载文档的字体，并在字体到达时重新排版（见[排版前加载字体](https://postext.dev/zh/docs/configuration-programmatic-usage.md#排版前加载字体)）。
### 在线示例：HTML字符串
在进入下面的React集成之前，先用纯JavaScript走一遍完整流程：构建文档，把`VDTDocument`交给`renderToHtml`，再把字符串放进一个容器。`mode: 'single'`把页面竖向堆叠；页面默认透明，所以用`background`给它们一个颜色。这个pen还会打印生成的标记，你可以看到渲染器输出的绝对定位的行：浏览器绘制它们，但从不重排它们。
> **可运行的示例: Postext · 把文档渲染为HTML** — 用postext排版一篇Markdown文档，并渲染为HTML字符串。 ([源代码](https://github.com/drnachio/postext/tree/main/docs/examples/render-html))
### 最简集成
下面的代码是最短的实用集成：按当前视口尺寸构建文档，渲染进一个容器，尺寸变化时重新运行。
```tsx
import { useEffect, useRef } from 'react';
import {
buildDocument,
renderToHtmlIndexed,
resolveHtmlViewerConfig,
buildFontString,
measureGlyphWidth,
dimensionToPx,
createMeasurementCache,
watchFonts,
onFontsChanged,
} from 'postext';
import type { PostextConfig, MeasurementCache } from 'postext';
// 适合屏幕的DPI：在144 DPI下，8pt的正文字号换算为16 px。
const HTML_DPI = 144;
const PADDING_PX = 24;
// 用来测量目标栏宽的正文样本。比例字体下“N × 平均宽度”并不可靠，
// 所以测量一段有代表性的字符串。
const SAMPLE =
'The quick brown fox jumps over the lazy dog. Sphinx of black quartz, judge my vow.';
function sampleForChars(n: number): string {
let s = SAMPLE;
while (s.length < n) s += ' ' + SAMPLE;
return s.slice(0, n);
}
export function PostextHtmlViewer({
markdown,
config,
mode = 'multi',
}: {
markdown: string;
config: PostextConfig;
mode?: 'single' | 'multi';
}) {
const hostRef = useRef(null);
const cacheRef = useRef(createMeasurementCache());
useEffect(() => {
const host = hostRef.current;
if (!host) return;
const relayout = () => {
const rect = host.getBoundingClientRect();
if (rect.width === 0 || rect.height === 0) return;
const viewer = resolveHtmlViewerConfig(config.htmlViewer);
const fontFamily = config.bodyText?.fontFamily ?? 'EB Garamond';
const fontWeight = config.bodyText?.fontWeight ?? 400;
const fontSize = config.bodyText?.fontSize ?? { value: 8, unit: 'pt' as const };
const fontSizePx = dimensionToPx(fontSize, HTML_DPI);
// 测量N个正文字符的*实际*栏宽。
const targetColumnPx = measureGlyphWidth(
sampleForChars(viewer.maxCharsPerLine),
buildFontString(fontFamily, fontSizePx, String(fontWeight), 'normal'),
);
const inner = Math.max(rect.width - PADDING_PX * 2, 100);
let columnWidthPx: number;
if (mode === 'single') {
columnWidthPx = Math.min(targetColumnPx, inner);
} else {
// 按目标栏宽尽量多放几栏。
const count = Math.max(
1,
Math.floor((inner + viewer.columnGap) / (targetColumnPx + viewer.columnGap)),
);
columnWidthPx = (inner - viewer.columnGap * (count - 1)) / count;
}
columnWidthPx = Math.max(Math.floor(columnWidthPx), 80);
// single模式用一个很高的页面；multi模式用视口高度，
// 这样每个VDT“页面”就成为一栏。
const pageHeightPx =
mode === 'single' ? Math.max(rect.height * 20, 200_000) : Math.max(rect.height - PADDING_PX * 2, 400);
const override: PostextConfig = {
...config,
page: {
...config.page,
dpi: HTML_DPI,
width: { value: columnWidthPx, unit: 'px' },
height: { value: pageHeightPx, unit: 'px' },
margins: {
top: { value: 0, unit: 'px' },
bottom: { value: 0, unit: 'px' },
left: { value: 0, unit: 'px' },
right: { value: 0, unit: 'px' },
},
},
layout: { ...config.layout, layoutType: 'single' },
bodyText: {
...config.bodyText,
optimalLineBreaking: viewer.optimalLineBreaking,
},
};
const doc = buildDocument({ markdown }, override, cacheRef.current);
const { html } = renderToHtmlIndexed(doc, {
mode,
columnGap: viewer.columnGap,
padding: PADDING_PX,
background: 'transparent',
});
host.innerHTML = html;
};
relayout();
const ro = new ResizeObserver(() => relayout());
ro.observe(host);
// Web字体加载完成后重新测量，避免字形宽度取自后备字体。
const stopWatching = watchFonts();
const off = onFontsChanged(() => relayout());
return () => {
ro.disconnect();
off();
stopWatching();
};
}, [markdown, config, mode]);
return ;
}
```
关于这个示例做了什么，有几点说明：
- **测量栏宽，而不是估算。**`maxCharsPerLine`是以字符数表示的*目标*，实际的像素宽度取决于正文字体。`measureGlyphWidth`针对所选字体给出真实的测量值，换字体后行长也保持一致。
- **改写页面**。HTML查看器把每个VDT“页面”当作屏幕上的一栏。示例用测得的栏宽覆盖`page.width`，把页边距设为0（内边距放在页面外，由外层的`.pt-doc` div提供），并使用`HTML_DPI = 144`，使`8pt`的正文换算为`16px`。
- **感知字体加载**。`watchFonts`监听`document.fonts`，每帧最多一次，丢弃在有字体到达的字体族中测得的结果；随后`onFontsChanged`重新排出这一栏。如果不重新排版，首次渲染用的是后备字体的度量，真正的字体到达后版面会跳动。
- **复用测量缓存**。每个组件只创建一次缓存，调整尺寸或改变字体缩放时就能复用上一次渲染的测量结果，不必重新测量每个段落。
### 进一步
上面的示例刻意保持简单。用于生产的集成通常还会加上：
- **Shadow DOM隔离**：渲染到`host.attachShadow({ mode: 'open' })`里，外层页面的CSS就不会渗入查看器。
- **增量修补**：`renderToHtmlIndexed`返回`pages[i].blocks`，每个块都有稳定的`id`和该块的外层HTML。两次渲染之间只有少数块不同时，可以原地替换这些块的包装元素，而不必重建`innerHTML`。
- **叠加层**：在每个`.pt-page`上叠一个绝对定位的SVG，用来显示光标、选区或基线网格。
- **链接**：Markdown链接中的词被包在``里，沿用文字颜色，没有下划线；见[文档格式 › 链接](https://postext.dev/zh/docs/document-format-inline.md#链接)。在类似编辑器的查看器中，拦截对不以`#`开头的`a[href]`的点击，在新标签页中打开（`:ref`锚点链接到文档内部）。
- **单色图片**：打开`diagramStyle.singleInk`后，SVG的`![]()
`会加上CSS滤镜；对于已经重新着色的URL，传入`singleInk: false`即可跳过；见[Canvas与HTML中的单色模式](https://postext.dev/zh/docs/configuration-resources.md#canvas与html中的单色模式)。
沙盒的`HtmlPreview`组件（`packages/postext-sandbox/src/viewport/HtmlPreview/index.tsx`）在这里展示的同一套API之上实现了以上全部功能，可以作为参考。它还把每次构建都交给一个共享的排版工作线程（见[在Web Worker中运行排版](https://postext.dev/zh/docs/configuration-programmatic-usage.md#在web-worker中运行排版)），所以实时编辑和调整尺寸都不会阻塞主线程。准备把排版移出主线程时，把上面代码中直接调用的`buildDocument(...)`换成`layoutWorker.build(...)`即可。
### HTML输出与Canvas和PDF的区别
`renderToHtml`把每一行、每个图和每个设计元素放在与Canvas和PDF完全相同的位置，但在它们周围画的东西更少：
| 功能 | Canvas（`renderPage`） | HTML（`renderToHtml`） | PDF（`renderToPdf`） |
| --- | --- | --- | --- |
| 页面背景 | 白色，`page.backgroundColor`铺满成品区域和出血。 | **透明**，除非传入`background`或设置`page.backgroundColor`（此时填满整个页面框，包括裁切线外的区域）。 | 白色，`page.backgroundColor`铺满成品区域和出血。 |
| 基线网格（`page.baselineGrid`） | 绘制 | 不绘制 | 绘制 |
| 栏间线（`layout.columnRule`） | 绘制 | 不绘制 | 绘制 |
| 裁切标记（`page.cutLines`） | 绘制 | 不绘制；页面框仍包含成品尺寸外围的区域。 | 绘制 |
| 页面反色 | `pageNegative`选项 | 不支持 | `pageNegative`选项 |
| 文字 | 像素 | 绝对定位元素中的可选中文字，使用CSS字体族排版：页面必须加载相同的字体。 | 来自`fontProvider`的嵌入字体；可选中、可搜索、带标签。 |
| 竖排文字（`layout.writingMode: 'vertical-rl'`） | 逐个字格绘制字符并转回直立；竖排字形取自一个孪生字体（`loadVerticalAlternates`）。 | 一个框中的文字流整体旋转四分之一圈；每一行再转回直立，并以`writing-mode: vertical-rl`排版，由浏览器选用竖排字形并让字符直立；短数字用`text-combine-upright: all`；破折号、省略号、间隔号或波浪线放在所在字格的一个框里（否则浏览器会按它的横排宽度推进），破折号按`flow.dashAdvances`拉长以填满字格。 | 通过每种字体的`Identity-V`孪生字体排出直立字符；见[PDF中的竖排文字](https://postext.dev/zh/docs/configuration-pdf-output.md#pdf中的竖排文字)。 |
| 图像 | `registerResourceImage` | `resourceImageUrl(fileId)`选项；未提供时显示灰色占位框。 | `resourceBytes(fileId)`选项。 |
| 公式 | 矢量路径 | 内联`