# Uso programmatico: HTML, Folio ed EPUB
> Il libro impaginato in una pagina web, come libro 3D con postext-folio, e come EPUB 3 a layout fisso o fluido con postext-epub
- Versione HTML: https://postext.dev/it/docs/configuration-html-folio-epub
- Ultimo aggiornamento: 2026-10-16
- Tempo di lettura: 18 min
- Altre lingue: [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), [pt](https://postext.dev/pt/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)
## In breve
Questa pagina è per chi scrive codice e vuole mostrare un libro su uno schermo. La prima sezione mette le pagine dentro una pagina web e spiega in che cosa questa vista differisce dal canvas e dal PDF. La seconda mostra il libro in 3D, aperto su una scrivania, con pagine che il lettore sfoglia. L’ultima sezione crea un e-book EPUB, a pagine fisse o con un testo che si adatta allo schermo, e verifica il file.
## Integrare il visualizzatore HTML
Il visualizzatore HTML è il renderer di Postext pensato prima di tutto per lo schermo. Invece di rasterizzare le pagine in una bitmap emette nodi DOM posizionati in modo assoluto, la cui geometria è determinata dalla stessa pipeline che produce l’output di stampa. Per questo è la scelta giusta quando vuoi in un browser una tipografia leggibile, selezionabile e sensibile al ridimensionamento (un’app di lettura, un’anteprima dentro un prodotto o una superficie di documentazione incorporata) senza dover includere un visualizzatore PDF.
I pezzi principali dell’API pubblica:
- **`buildDocument(content, config, cache?)`**: esegue l’intera pipeline di impaginazione e restituisce un `VDTDocument`.
- **`renderToHtmlIndexed(doc, options)`**: trasforma il VDT in un’unica stringa HTML più una scomposizione per pagina e per blocco. La scomposizione permette di aggiornare il DOM a basso costo quando tra due rendering cambiano solo pochi blocchi.
- **`resolveHtmlViewerConfig(partial)`**: completa i valori predefiniti del visualizzatore HTML (`maxCharsPerLine`, `columnGap`, `optimalLineBreaking`).
- **`buildFontString` + `measureGlyphWidth` + `dimensionToPx`**: primitive di misurazione usate per ricavare una larghezza di colonna reale in pixel da un numero di caratteri desiderato.
- **`createMeasurementCache` / `clearMeasurementCache`**: cache intercambiabili che ti permettono di riutilizzare le misure tra un’impaginazione e l’altra.
- **`prepareFonts` / `buildDocumentWithFonts` / `watchFonts` / `onFontsChanged`**: caricano i caratteri del documento prima dell’impaginazione e impaginano di nuovo quando i caratteri arrivano (vedi [Caricare i font prima dell’impaginazione](https://postext.dev/it/docs/configuration-programmatic-usage.md#caricare-i-font-prima-dellimpaginazione)).
### Esempio dal vivo: una stringa HTML
L’intero percorso in JavaScript semplice, prima dell’integrazione con React più sotto: costruisci il documento, passa il `VDTDocument` a `renderToHtml` e inserisci la stringa in un contenitore. `mode: 'single'` impila le pagine in verticale; `background` dà loro un colore, perché per impostazione predefinita le pagine sono trasparenti. Il pen stampa anche il markup generato, così puoi vedere le righe posizionate in modo assoluto che il renderer emette: il browser le dipinge ma non le ridistribuisce mai.
> **Esempio eseguibile: Postext · rendere un documento in HTML** — Impagina un documento Markdown con postext e rendilo in una stringa HTML. ([codice](https://github.com/drnachio/postext/tree/main/docs/examples/render-html))
### Integrazione minima
Il frammento qui sotto è l’integrazione utile più breve: costruisce il documento alla dimensione attuale della finestra, lo rende in un contenitore e lo rieseguisce a ogni ridimensionamento.
```tsx
import { useEffect, useRef } from 'react';
import {
buildDocument,
renderToHtmlIndexed,
resolveHtmlViewerConfig,
buildFontString,
measureGlyphWidth,
dimensionToPx,
createMeasurementCache,
watchFonts,
onFontsChanged,
} from 'postext';
import type { PostextConfig, MeasurementCache } from 'postext';
// Screen-friendly DPI: at 144 DPI, an 8pt body size resolves to 16 px.
const HTML_DPI = 144;
const PADDING_PX = 24;
// Prose sample used to measure the target column width. Proportional fonts
// make "N × average width" unreliable, so we measure a representative string.
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);
// Measure the *actual* column width for N characters of body prose.
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 {
// Fit as many columns as we can at the target width.
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 mode uses one very tall page; multi mode uses the viewport
// height so each VDT "page" becomes one column.
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);
// Re-measure when web fonts land so glyph widths aren't taken from fallbacks.
const stopWatching = watchFonts();
const off = onFontsChanged(() => relayout());
return () => {
ro.disconnect();
off();
stopWatching();
};
}, [markdown, config, mode]);
return ;
}
```
Qualche nota su che cosa fa questo esempio:
- **Misurare la colonna, non stimarla.** Poiché `maxCharsPerLine` è un *obiettivo* espresso in caratteri, la larghezza reale in pixel dipende dal font del testo corrente. `measureGlyphWidth` fornisce una misura reale con il font scelto, il che mantiene coerente la giustezza quando cambi font.
- **Riscrivere la pagina.** Il visualizzatore HTML tratta ogni «pagina» del VDT come una colonna sullo schermo. L’esempio sostituisce `page.width` con la larghezza di colonna misurata, azzera i margini (il padding vive fuori dalla pagina, nel div `.pt-doc` che la avvolge) e usa `HTML_DPI = 144` perché un testo corrente di `8pt` diventi `16px`.
- **Attenzione al caricamento dei font.** `watchFonts` ascolta `document.fonts` e, una volta per frame, scarta ciò che era stato misurato nelle famiglie i cui caratteri sono arrivati; `onFontsChanged` impagina poi di nuovo la colonna. Senza la nuova impaginazione, il primo rendering usa le metriche di un font di ripiego e salta quando arriva il font vero.
- **Riutilizzare la cache delle misure.** Creare la cache una volta per componente significa che i ridimensionamenti e i cambi di scala del font riutilizzano le misure del rendering precedente invece di rimisurare ogni paragrafo.
### Andare oltre
L’esempio qui sopra è volutamente essenziale. Le integrazioni in produzione di solito aggiungono:
- **Isolamento con Shadow DOM**: rendi dentro `host.attachShadow({ mode: 'open' })` così che niente della pagina esterna possa far trapelare CSS nel visualizzatore.
- **Aggiornamento incrementale**: `renderToHtmlIndexed` restituisce `pages[i].blocks`, ognuno con un `id` stabile e l’HTML esterno del blocco. Quando tra due rendering differiscono solo pochi blocchi puoi sostituire sul posto quei contenitori di blocco invece di ricostruire `innerHTML`.
- **Sovrapposizioni**: un SVG posizionato in modo assoluto sopra ogni `.pt-page` per cursori, selezioni o griglie della linea di base.
- **Link**: le parole di un link Markdown sono avvolte in ``, che prende il colore del testo e non ha sottolineatura; vedi [Formato del documento › Link](https://postext.dev/it/docs/document-format-inline.md#link). In un visualizzatore simile a un editor, intercetta i clic sugli `a[href]` che non cominciano con `#` e aprili in una nuova scheda (le ancore di `:ref` puntano dentro il documento).
- **Immagini a un solo inchiostro**: con `diagramStyle.singleInk` attivo, gli `![]()
` SVG ricevono un filtro CSS, a meno che tu non passi `singleInk: false` per URL già ricolorati; vedi [Un solo inchiostro su canvas e in HTML](https://postext.dev/it/docs/configuration-resources.md#inchiostro-unico-sul-canvas-e-in-html).
Il componente `HtmlPreview` della Sandbox (`packages/postext-sandbox/src/viewport/HtmlPreview/index.tsx`) implementa tutto questo sopra la stessa API mostrata qui e può servire da riferimento. Inoltre fa passare ogni build da un worker di impaginazione condiviso (vedi [Eseguire l’impaginazione in un Web Worker](https://postext.dev/it/docs/configuration-programmatic-usage.md#eseguire-limpaginazione-in-un-web-worker)), così le modifiche dal vivo e i ridimensionamenti non bloccano mai il thread principale: sostituisci la chiamata diretta `buildDocument(...)` del frammento qui sopra con `layoutWorker.build(...)` quando sei pronto a spostare l’impaginazione fuori dal thread principale.
### In che cosa l’output HTML differisce da canvas e PDF
`renderToHtml` colloca ogni riga, figura ed elemento di design esattamente dove li collocano il canvas e il PDF, ma attorno a essi dipinge meno:
| Funzione | Canvas (`renderPage`) | HTML (`renderToHtml`) | PDF (`renderToPdf`) |
| --- | --- | --- | --- |
| Sfondo della pagina | Bianco, con `page.backgroundColor` sul formato rifilato e sull’abbondanza. | **Trasparente**, a meno che tu non passi `background` o imposti `page.backgroundColor` (che allora riempie l’intero riquadro della pagina, area esterna compresa). | Bianco, con `page.backgroundColor` sul formato rifilato e sull’abbondanza. |
| Griglia della linea di base (`page.baselineGrid`) | Disegnata | Non disegnata | Disegnata |
| Filetto tra le colonne (`layout.columnRule`) | Disegnato | Non disegnato | Disegnato |
| Segni di taglio (`page.cutLines`) | Disegnati | Non disegnati; il riquadro della pagina include comunque l’area esterna attorno al formato rifilato. | Disegnati |
| Negativo della pagina | Opzione `pageNegative` | Non disponibile | Opzione `pageNegative` |
| Testo | Pixel | Testo selezionabile in elementi posizionati in modo assoluto, composto nelle famiglie di caratteri CSS: la pagina deve caricare gli stessi font. | Font incorporati dal tuo `fontProvider`; selezionabile, ricercabile e taggato. |
| Testo verticale (`layout.writingMode: 'vertical-rl'`) | Caratteri dipinti una cella alla volta, raddrizzati; forme verticali tramite un font gemello (`loadVerticalAlternates`). | Il flusso in un unico riquadro ruotato di un quarto di giro; ogni riga raddrizzata e composta con `writing-mode: vertical-rl`, così il browser prende le forme verticali e mette in piedi i caratteri; i numeri brevi in `text-combine-upright: all`; una lineetta, un’ellissi, un punto mediano o una tilde ondulata in un riquadro della sua cella (il browser la farebbe avanzare della sua larghezza orizzontale), una lineetta allungata per riempirla da `flow.dashAdvances`. | Caratteri in piedi tramite un gemello `Identity-V` di ogni font; vedi [Testo verticale nel PDF](https://postext.dev/it/docs/configuration-pdf-output.md#testo-verticale-nel-pdf). |
| Immagini | `registerResourceImage` | L’opzione `resourceImageUrl(fileId)`; senza di essa, un riquadro grigio segnaposto. | L’opzione `resourceBytes(fileId)`. |
| Formule | Tracciati vettoriali | `