# Uso programático: HTML, Folio e EPUB
> O livro diagramado numa página web, como livro em 3D com o postext-folio e como EPUB 3 de layout fixo ou refluível com o postext-epub
- Versão HTML: https://postext.dev/pt/docs/configuration-html-folio-epub
- Última atualização: 2026-10-16
- Tempo de leitura: 18 min
- Outros idiomas: [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), [zh](https://postext.dev/zh/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)
## Em poucas palavras
Esta página é para quem escreve código e quer mostrar um livro numa tela. A primeira seção coloca as páginas dentro de uma página web e explica em que essa visualização difere do canvas e do PDF. A segunda mostra o livro em 3D, aberto sobre uma mesa, com folhas que o leitor vira. A última seção gera um livro digital EPUB, com páginas fixas ou com texto que se ajusta à tela, e verifica o arquivo.
## Integração do visualizador HTML
O visualizador HTML é o renderizador do Postext voltado para a tela. Em vez de rasterizar as páginas em um bitmap, ele emite nós DOM com posicionamento absoluto, cuja geometria vem do mesmo pipeline que produz a saída impressa. Por isso é a escolha certa quando você quer, no navegador, tipografia legível, selecionável e que acompanha o redimensionamento (um app de leitura, uma visualização dentro de um produto ou uma página de documentação incorporada) sem depender de um visualizador de PDF.
As peças principais da API pública:
- **`buildDocument(content, config, cache?)`**: executa o pipeline de layout completo e devolve um `VDTDocument`.
- **`renderToHtmlIndexed(doc, options)`**: transforma o VDT em uma única string HTML, mais um detalhamento por página e por bloco. Esse detalhamento permite remendar o DOM a baixo custo quando só alguns blocos mudaram entre duas renderizações.
- **`resolveHtmlViewerConfig(partial)`**: preenche os valores padrão do visualizador HTML (`maxCharsPerLine`, `columnGap`, `optimalLineBreaking`).
- **`buildFontString` + `measureGlyphWidth` + `dimensionToPx`**: primitivas de medição usadas para obter a largura real da coluna em pixels a partir de um número de caracteres desejado.
- **`createMeasurementCache` / `clearMeasurementCache`**: caches plugáveis, para reaproveitar medições entre um layout e outro.
- **`prepareFonts` / `buildDocumentWithFonts` / `watchFonts` / `onFontsChanged`**: carregam as faces do documento antes do layout e diagramam de novo quando chegam faces (veja [Carregar as fontes antes do layout](https://postext.dev/pt/docs/configuration-programmatic-usage.md#carregar-as-fontes-antes-do-layout)).
### Exemplo ao vivo: uma string HTML
O percurso completo em JavaScript puro, antes da integração com React mais abaixo: construir o documento, entregar o `VDTDocument` a `renderToHtml` e inserir a string em um contêiner. `mode: 'single'` empilha as páginas na vertical; `background` dá uma cor a elas, já que as páginas são transparentes por padrão. O pen também imprime a marcação gerada, para você ver as linhas com posicionamento absoluto que o renderizador emite: o navegador as pinta, mas nunca refaz o fluxo delas.
> **Exemplo executável: Postext · renderizar um documento em HTML** — Diagrame um documento Markdown com o postext e renderize-o em uma string HTML. ([código](https://github.com/drnachio/postext/tree/main/docs/examples/render-html))
### Integração mínima
O trecho abaixo é a menor integração útil: constrói o documento no tamanho atual da área de visualização, renderiza-o em um contêiner e repete o processo a cada redimensionamento.
```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 adequado para tela: a 144 DPI, um corpo de 8pt equivale a 16 px.
const HTML_DPI = 144;
const PADDING_PX = 24;
// Amostra de prosa usada para medir a largura de coluna desejada. Com fontes
// proporcionais, "N × largura média" não é confiável, então medimos uma string representativa.
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);
// Mede a largura *real* da coluna para N caracteres de texto corrido.
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 {
// Encaixa quantas colunas couberem na largura desejada.
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);
// O modo single usa uma única página muito alta; o modo multi usa a altura
// da área de visualização, de modo que cada "página" do VDT vira uma coluna.
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);
// Mede de novo quando as fontes web chegam, para que as larguras dos glifos não venham das fontes substitutas.
const stopWatching = watchFonts();
const off = onFontsChanged(() => relayout());
return () => {
ro.disconnect();
off();
stopWatching();
};
}, [markdown, config, mode]);
return ;
}
```
Algumas observações sobre o que esse exemplo faz:
- **Mede a coluna em vez de estimá-la.** Como `maxCharsPerLine` é um *alvo* expresso em caracteres, a largura real em pixels depende da fonte do texto corrido. `measureGlyphWidth` faz uma medição de verdade com a fonte escolhida, o que mantém a medida constante quando a fonte muda.
- **Reescreve a página.** O visualizador HTML trata cada “página” do VDT como uma coluna na tela. O exemplo substitui `page.width` pela largura de coluna medida, zera as margens (o espaçamento interno fica fora da página, na div `.pt-doc` que a envolve) e usa `HTML_DPI = 144` para que um texto de `8pt` resulte em `16px`.
- **Leva em conta o carregamento das fontes.** `watchFonts` escuta `document.fonts` e, uma vez por quadro, descarta o que foi medido nas famílias cujas faces chegaram; `onFontsChanged` então diagrama a coluna de novo. Sem refazer o layout, a primeira renderização usa as métricas de uma fonte substituta e salta quando a fonte verdadeira chega.
- **Reaproveita o cache de medição.** Criar o cache uma vez por componente faz com que redimensionamentos e mudanças de escala da fonte reaproveitem as medições da renderização anterior, em vez de medir de novo cada parágrafo.
### Indo além
O exemplo acima é propositalmente simples. Integrações em produção costumam acrescentar:
- **Isolamento com Shadow DOM**: renderize em `host.attachShadow({ mode: 'open' })` para que nenhum CSS da página externa vaze para o visualizador.
- **Remendos incrementais**: `renderToHtmlIndexed` devolve `pages[i].blocks`, cada um com um `id` estável e o HTML externo do bloco. Quando só alguns blocos diferem entre duas renderizações, você pode substituir esses invólucros no lugar, em vez de reconstruir o `innerHTML`.
- **Sobreposições**: uma camada SVG com posicionamento absoluto sobre cada `.pt-page`, para cursores, seleções ou a grade de linhas de base.
- **Links**: as palavras de um link Markdown são envolvidas em ``, que assume a cor do texto e não tem sublinhado; veja [Formato do documento › Links](https://postext.dev/pt/docs/document-format-inline.md#links). Em um visualizador que funcione como editor, intercepte os cliques em `a[href]` que não comecem por `#` e abra-os em uma nova aba (as âncoras de `:ref` apontam para dentro do documento).
- **Imagens em tinta única**: com `diagramStyle.singleInk` ativado, os `![]()
` SVG recebem um filtro CSS, a menos que você passe `singleInk: false` para URLs que já foram recoloridas; veja [Tinta única no canvas e no HTML](https://postext.dev/pt/docs/configuration-resources.md#tinta-única-no-canvas-e-no-html).
O componente `HtmlPreview` do Sandbox (`packages/postext-sandbox/src/viewport/HtmlPreview/index.tsx`) implementa tudo isso sobre a mesma API mostrada aqui e pode servir de referência. Ele também encaminha cada build por um worker de layout compartilhado (veja [Executar o layout em um Web Worker](https://postext.dev/pt/docs/configuration-programmatic-usage.md#executar-o-layout-em-um-web-worker)), para que edições ao vivo e redimensionamentos nunca bloqueiem a thread principal. Troque a chamada direta `buildDocument(...)` do trecho acima por `layoutWorker.build(...)` quando quiser tirar o layout da thread principal.
### Como a saída HTML difere do canvas e do PDF
`renderToHtml` posiciona cada linha, figura e elemento de design exatamente onde o canvas e o PDF os posicionam, mas pinta menos coisas ao redor deles:
| Recurso | Canvas (`renderPage`) | HTML (`renderToHtml`) | PDF (`renderToPdf`) |
| --- | --- | --- | --- |
| Fundo da página | Branco, com `page.backgroundColor` sobre o refile e a sangria. | **Transparente**, a menos que você passe `background` ou defina `page.backgroundColor` (que então preenche a caixa da página inteira, área de slug incluída). | Branco, com `page.backgroundColor` sobre o refile e a sangria. |
| Grade de linhas de base (`page.baselineGrid`) | Desenhada | Não desenhada | Desenhada |
| Fio entre colunas (`layout.columnRule`) | Desenhado | Não desenhado | Desenhado |
| Marcas de corte (`page.cutLines`) | Desenhadas | Não desenhadas; a caixa da página continua incluindo a área de slug ao redor do refile. | Desenhadas |
| Negativo da página | Opção `pageNegative` | Não disponível | Opção `pageNegative` |
| Texto | Pixels | Texto selecionável em elementos com posicionamento absoluto, composto nas famílias de fonte do CSS: a página precisa carregar as mesmas fontes. | Fontes incorporadas a partir do seu `fontProvider`; selecionável, pesquisável e com tags. |
| Texto vertical (`layout.writingMode: 'vertical-rl'`) | Caracteres pintados uma célula por vez, girados de volta à posição em pé; formas verticais por meio de uma fonte gêmea (`loadVerticalAlternates`). | O fluxo em uma caixa girada um quarto de volta; cada linha girada de volta à posição em pé e composta com `writing-mode: vertical-rl`, de modo que o navegador usa as formas verticais e põe os caracteres em pé; números curtos em `text-combine-upright: all`; um travessão, reticências, um ponto médio ou um til ondulado em uma caixa da sua célula (o navegador o avançaria pela largura horizontal), e um travessão esticado para preenchê-la por `flow.dashAdvances`. | Caracteres em pé por meio de uma gêmea `Identity-V` de cada fonte; veja [Texto vertical no PDF](https://postext.dev/pt/docs/configuration-pdf-output.md#texto-vertical-no-pdf). |
| Imagens | `registerResourceImage` | A opção `resourceImageUrl(fileId)`; sem ela, uma caixa cinza no lugar. | A opção `resourceBytes(fileId)`. |
| Fórmulas | Caminhos vetoriais | `