# Ús programàtic: HTML, Folio i EPUB
> El llibre compost en una pàgina web, com a llibre en 3D amb postext-folio i com a EPUB 3 de maquetació fixa o fluida amb postext-epub
- Versió HTML: https://postext.dev/ca/docs/configuration-html-folio-epub
- Última actualització: 2026-10-16
- Temps de lectura: 18 min
- Altres idiomes: [en](https://postext.dev/en/docs/configuration-html-folio-epub.md), [es](https://postext.dev/es/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), [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)
## En poques paraules
Aquesta pàgina és per a qui escriu codi i vol mostrar un llibre en una pantalla. La primera secció posa les pàgines dins d'una pàgina web i explica en què es diferencia aquesta vista del canvas i del PDF. La segona mostra el llibre en 3D, obert sobre una taula, amb fulls que el lector passa. L'última secció crea un llibre electrònic EPUB, amb pàgines fixes o amb un text que s'adapta a la pantalla, i comprova el fitxer.
## Integrar el visor HTML
El visor HTML és el renderitzador de Postext orientat a pantalla. En lloc de rasteritzar pàgines a un mapa de bits emet nodes DOM posicionats absolutament la geometria dels quals genera el mateix pipeline que produeix la sortida impresa. És l'opció adequada quan vols tipografia llegible, seleccionable i conscient del resize al navegador — una app de lectura, una previsualització dins d'un producte o una superfície de documentació incrustada — sense haver d'arrossegar un visor PDF.
Les peces clau de l'API pública:
- **`buildDocument(content, config, cache?)`** — executa el pipeline complet de composició i retorna un `VDTDocument`.
- **`renderToHtmlIndexed(doc, options)`** — converteix el VDT en una única cadena HTML més un desglossament per pàgina i per bloc. El desglossament permet apedaçar el DOM de manera barata quan només han canviat alguns blocs entre renders.
- **`resolveHtmlViewerConfig(partial)`** — completa els valors per defecte del visor HTML (`maxCharsPerLine`, `columnGap`, `optimalLineBreaking`).
- **`buildFontString` + `measureGlyphWidth` + `dimensionToPx`** — primitives de mesura que serveixen per derivar una amplada de columna real en píxels a partir d'un objectiu en caràcters.
- **`createMeasurementCache` / `clearMeasurementCache`** — memòries cau endollables per reutilitzar mesures entre recomposicions.
- **`prepareFonts` / `buildDocumentWithFonts` / `watchFonts` / `onFontsChanged`** — carreguen les cares del document abans de compondre i tornen a compondre quan n'arriben de noves (vegeu [Carregar les fonts abans de compondre](https://postext.dev/ca/docs/configuration-programmatic-usage.md#carregar-les-fonts-abans-de-compondre)).
### Exemple en directe: una cadena HTML
El recorregut complet en JavaScript pla, abans de la integració amb React de més avall: construir el document, passar el `VDTDocument` a `renderToHtml` i bolcar la cadena en un contenidor. `mode: 'single'` apila les pàgines en vertical; `background` els dona color, perquè per defecte les pàgines són transparents. El pen també imprimeix el marcatge generat, perquè vegis les línies posicionades de manera absoluta que emet el renderitzador: el navegador les pinta, però no les recompon mai.
> **Exemple executable: Postext · renderitzar un document a HTML** — Compon un document markdown amb postext i renderitza'l a una cadena HTML. ([codi](https://github.com/drnachio/postext/tree/main/docs/examples/render-html))
### Integració mínima
El fragment següent és la integració útil més curta: construeix el document a la mida actual de la vista, el renderitza en un contenidor i recompon en redimensionar.
```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 adequat per a pantalla: a 144 DPI una mida de cos de 8pt resol a 16 px.
const HTML_DPI = 144;
const PADDING_PX = 24;
// Mostra de prosa que serveix per mesurar l'amplada objectiu de columna. Les fonts
// proporcionals fan poc fiable "N × amplada mitjana", així que mesurem una
// cadena 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);
// Mesura l'amplada *real* de columna per a N caràcters de prosa del cos.
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 {
// Hi encabeix tantes columnes com es pugui a l'amplada objectiu.
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);
// El mode single fa servir una pàgina molt alta; el mode multi fa servir l'alçada
// de la vista, de manera que cada "pàgina" VDT es converteix en una columna.
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);
// Torna a mesurar quan es carreguen les web fonts perquè les amplades de glif no
// quedin preses a partir de les fonts de reserva.
const stopWatching = watchFonts();
const off = onFontsChanged(() => relayout());
return () => {
ro.disconnect();
off();
stopWatching();
};
}, [markdown, config, mode]);
return ;
}
```
Algunes notes sobre el que fa l'exemple:
- **Es mesura la columna, no s'aproxima.** Com que `maxCharsPerLine` és un *objectiu* expressat en caràcters, l'amplada real en píxels depèn de la font del cos. `measureGlyphWidth` dona una mesura real sobre la font triada, i manté la mesura coherent quan es canvia de font.
- **Es reescriu la pàgina.** El visor HTML tracta cada "pàgina" del VDT com una columna en pantalla. L'exemple sobreescriu `page.width` amb l'amplada mesurada de columna, posa els marges a zero (el padding viu fora de la pàgina, al `.pt-doc` que l'embolcalla) i fa servir `HTML_DPI = 144` perquè `8pt` de cos resolgui a `16px`.
- **Atent a la càrrega de fonts.** `watchFonts` escolta `document.fonts` i, una vegada per fotograma, descarta el que s'havia mesurat en les famílies amb cares acabades d'arribar; `onFontsChanged` torna a compondre llavors la columna. Si no es recompon, el primer render fa servir mètriques de la font de reserva i es produeix un salt quan arriba la real.
- **Es reutilitza la memòria cau de mesures.** Crear la memòria cau una sola vegada per component fa que els redimensionaments i els canvis d'escala de font reutilitzin mesures del render anterior en lloc de tornar a mesurar cada paràgraf.
### Pas següent
L'exemple de més amunt és deliberadament pla. Les integracions en producció hi solen afegir:
- **Aïllament amb Shadow DOM** — renderitza a `host.attachShadow({ mode: 'open' })` perquè res del document extern filtri CSS al visor.
- **Apedaçament incremental** — `renderToHtmlIndexed` retorna `pages[i].blocks`, cadascun amb un `id` estable i l'HTML extern del bloc. Quan només uns quants blocs difereixen entre dos renders pots substituir aquests embolcalls al lloc en lloc de reconstruir `innerHTML`.
- **Superposicions** — apila un SVG absolut sobre cada `.pt-page` per a cursors, seleccions o la retícula de base.
- **Enllaços** — les paraules d'un enllaç Markdown s'embolcallen en ``, que pren el color del text i no se subratlla; consulta [Format del document › Enllaços](https://postext.dev/ca/docs/document-format-inline.md#enllaços). En un visor que funcioni com a editor, intercepta els clics als `a[href]` que no comencin per `#` i obre'ls en una pestanya nova (les àncores de `:ref` enllacen dins del document).
- **Imatges a una sola tinta** — amb `diagramStyle.singleInk` actiu, els `![]()
` SVG porten un filtre CSS, tret que passis `singleInk: false` perquè les URL ja estan recolorides; consulta [Tinta única en canvas i en HTML](https://postext.dev/ca/docs/configuration-resources.md#tinta-única-en-canvas-i-en-html).
El component `HtmlPreview` del sandbox (`packages/postext-sandbox/src/viewport/HtmlPreview/index.tsx`) implementa tot això sobre la mateixa API que es mostra aquí i et pot servir de referència. A més, encamina cada build a través d'un worker de layout compartit (consulta [Executar la composició en un Web Worker](https://postext.dev/ca/docs/configuration-programmatic-usage.md#executar-la-composició-en-un-web-worker)) perquè les edicions en directe i els redimensionaments no bloquegin mai el fil principal — substitueix la crida directa `buildDocument(...)` del fragment anterior per `layoutWorker.build(...)` quan vulguis treure la composició del fil principal.
### En què es diferencia la sortida HTML del canvas i del PDF
`renderToHtml` col·loca cada línia, figura i element de disseny exactament on ho fan el canvas i el PDF, però pinta menys coses al voltant:
| Element | Canvas (`renderPage`) | HTML (`renderToHtml`) | PDF (`renderToPdf`) |
| --- | --- | --- | --- |
| Fons de pàgina | Blanc, amb `page.backgroundColor` sobre la caixa de tall i la sang. | **Transparent**, tret que passis `background` o fixis `page.backgroundColor` (que llavors omple tota la caixa de la pàgina, inclosa la zona de les marques de tall). | Blanc, amb `page.backgroundColor` sobre la caixa de tall i la sang. |
| Retícula de base (`page.baselineGrid`) | Es dibuixa | No es dibuixa | Es dibuixa |
| Filet entre columnes (`layout.columnRule`) | Es dibuixa | No es dibuixa | Es dibuixa |
| Marques de tall (`page.cutLines`) | Es dibuixen | No es dibuixen; la caixa de la pàgina continua incloent el marge exterior de les marques. | Es dibuixen |
| Negatiu de pàgina | Opció `pageNegative` | No disponible | Opció `pageNegative` |
| Text | Píxels | Text seleccionable en elements amb posició absoluta, compost en les famílies CSS: la pàgina ha de carregar les mateixes cares. | Fonts incrustades des del teu `fontProvider`; seleccionable, cercable i etiquetat. |
| Text vertical (`layout.writingMode: 'vertical-rl'`) | Caràcters pintats casella a casella i adreçats; formes verticals mitjançant una font bessona (`loadVerticalAlternates`). | El flux en una caixa girada un quart de volta; cada línia adreçada i composta amb `writing-mode: vertical-rl`, de manera que el navegador agafa les formes verticals i posa els caràcters drets; els números curts, en `text-combine-upright: all`; un guió llarg, uns punts suspensius, un punt volat o una titlla d'ona, en una caixa de la llargada de la seva cel·la (el navegador els faria avançar la seva amplada horitzontal), i el guió llarg estirat fins a omplir-la segons `flow.dashAdvances`. | Caràcters drets mitjançant una bessona `Identity-V` de cada font; vegeu [Text vertical en el PDF](https://postext.dev/ca/docs/configuration-pdf-output.md#text-vertical-en-el-pdf). |
| Imatges | `registerResourceImage` | L'opció `resourceImageUrl(fileId)`; sense ella, una caixa grisa provisional. | L'opció `resourceBytes(fileId)`. |
| Fórmules | Traços vectorials | `