Capítulo 3.18 · Parte II · El oficio
Uso programático: archivos PDF
Cómo se usa postext-pdf desde el código: la instalación y la API; los proveedores de fuentes en el navegador y en Node; las fuentes CJK, los bytes de los recursos y el texto vertical, y los workers y los archivos listos para imprenta
En pocas palabras
Esta página es para quienes escriben código y quieren un archivo PDF. Enseña a instalar el paquete de PDF y a convertir un libro compuesto en un archivo con unas pocas líneas. El paquete necesita los archivos de las fuentes, así que la página explica cómo dárselos, en un navegador o en un servidor. Trata las fuentes para chino, japonés y coreano, las imágenes, el texto que va de arriba abajo y los enlaces. Termina con un ejemplo completo y con archivos listos para la imprenta.
#Generación de PDF
La salida PDF está en un paquete aparte, postext-pdf, para que las integraciones exclusivamente web no carguen con el peso de pdf-lib ni de @pdf-lib/fontkit. El backend de PDF no vuelve a medir el texto: consume exactamente el mismo VDTDocument que le pasarías a renderToCanvas o a renderToHtml y traduce sus coordenadas en píxeles a puntos PDF. Por eso, las tres salidas coinciden siempre en saltos de línea, alturas de columna y colocación de recursos.
En el navegador, construye el VDT a través del Web Worker. Una vez que existe el VDT,
renderToPdfes rápido; lo costoso es la composición que lo produjo. Ejecutar esa composición en el worker mantiene fluida la interfaz y permite que una exportación a PDF reutilice la misma caché de medidas que ya preparó la vista previa en vivo. El flujo recomendado se describe en Exportar PDF desde el worker. Los ejemplos en el hilo principal que siguen sirven de referencia sobre qué significan los argumentos; en el código de una interfaz, construye primero el VDT en el worker y luego llama directamente arenderToPdf.
#Instalación
npm install postext postext-pdfpostext es una peer dependency de postext-pdf. Cada versión de postext-pdf necesita el postext con el que se publicó, o uno posterior de la misma versión mayor (su rango es ^ sobre esa versión: ^1.5.0 para la 1.5.0), porque importa funciones auxiliares que postext añadió en esa versión. Actualiza los dos a la vez y, en una CDN, fíjalos a la misma versión.
#API pública
El paquete expone un único punto de entrada y un puñado de tipos:
renderToPdf(doc, options): Promise<Uint8Array>: toma unVDTDocument(o los capítulos de un libro, como una lista de ellos) y devuelve los bytes del PDF.PdfFontProvider: la firma del callback(family, weight, style, request?) => Promise<Uint8Array | Uint8Array[]>que usarenderToPdfpara pedir los bytes de una fuente cuando necesita incrustar una combinación nueva de familia, peso y estilo.request.codePointscontiene los caracteres que las páginas componen en esa variante; la respuesta es un archivo, o varios que juntos forman la variante (consulta Fuentes chinas, japonesas y coreanas).declaredFontFile(bytes, { unicodeRange?, order? }): PdfFontFile: un archivo de una variante que registra cómo lo declaró la página: elunicode-rangede su regla@font-facey su lugar en el orden de declaración. UnPdfFontFilees unUint8Arraycon esas dos propiedades opcionales (véase Fuentes chinas, japonesas y coreanas). Desde postext-pdf 1.30.RenderToPdfOptions:{ fontProvider, forms?, resourceBytes?, previewBytes?, outlines?, accessible?, colorSpace?, pageNegative?, characterGrid?, baselineGrid?, onProgress?, onWarning?, rasterizeSvg?, harfbuzzWasm?, print?, outputProfile?, profileBaseUrl?, date? }.formsfija cómo escriben los números los campos de formulario (moneda, su lado, separadores) y la fuente en que muestran sus valores (font; véase Campos de formulario).outlines,accessibleycolorSpacetoman el valor delpdfGenerationdel documento cuando no se pasan (véase Generación de PDF (configuración)).resourceBytesse describe en Bytes de recursos y másteres de impresión;onWarning, en Qué variantes se piden al proveedor y en Avisos del documento. ConcharacterGrid: true, el PDF imprime la retícula quecjk.grid.showdibuja en pantalla y que, si no, deja fuera (véase Retícula de caracteres).harfbuzzWasmindica de dónde cargar elharfbuzz.wasmde HarfBuzz (una URL, relativa a la página, o los bytes del archivo) para un documento con texto de derecha a izquierda o de letras enlazadas; si no se pasa, postext-pdf prueba la copia que hay junto a su propio módulo y, después, la misma versión de harfbuzzjs en jsDelivr y en esm.sh.printrecibe los ajustes de salida a imprenta (norma PDF/X, perfil de salida, negro, preflight) y, si no se pasa, toma elprintdel documento; con una norma PDF/X, o concolorSpace: 'cmyk', cada color se separa con el perfil ICC de salida, cuyos bytes daoutputProfile(si no, se descarga deprofileBaseUrl, por defecto la copia de la carpetaicc/de postext en la CDN de npm).date(unDate, un tiempo en milisegundos o una fecha escrita, como elmtimedecreateBundle) es la fecha de creación y de modificación del archivo y, en un PDF/X, las fechas de su paquete XMP y el origen de su identificador de documento: el mismo documento, generado dos veces con un mismodate, da los mismos bytes. Si no se pasa, el archivo lleva la hora de la llamada. Una fecha no válida lanza un error.PdfWarning: un problema no fatal que se notifica poronWarning; se distingue porkind:'fontFallback'(PdfFontFallbackWarning), una variante compuesta con otro corte de su familia;'missingGlyph'(PdfMissingGlyphWarning), caracteres para los que ningún archivo de una variante tiene glifo;'variableFontDefaultInstance'(PdfVariableFontWarning), una fuente variable pedida con un peso distinto del de su instancia por defecto;'cffEmbeddedWhole'(PdfCffEmbeddedWholeWarning), una fuente CFF de más de 2 MB incrustada entera;'complexShapingUnavailable'(PdfComplexShapingWarning), texto de derecha a izquierda o de letras enlazadas dibujado sin HarfBuzz, que no se pudo cargar (reasondice dónde se buscó), así que las marcas del árabe quedan mal colocadas;'outputProfileUnavailable'(PdfPrintWarning), una salida CMYK cuyo perfil de salida no se pudo cargar y que se convirtió con la fórmula simple;'pageNegativeIgnored'(PdfPrintWarning), el negativo de página que se omite en un PDF/X-1a;'spotTintsExhausted'(PdfPrintWarning), un render que se quedó sin códigos para tonos distintos de tinta plana (unos 25 millones) e imprimió el resto en cuatricromía;'spotInkRenamed'(PdfPrintWarning), una tinta cuya plancha se escribe con otro nombre (véase Tintas planas);'imageProfileUnavailable'(PdfPrintWarning), el perfil asignado a las imágenes RGB no se pudo cargar y se usaron sus propios perfiles;'pictureOriginalUnreadable'(PdfPrintWarning), un original TIFF o Photoshop que no se pudo decodificar, impreso desde su vista previa (previewBytes) o como marcador;'plateMixesApproximated'y'artworkOffPlates'(PdfPrintWarning), un trabajo en pocas planchas (print.plates) que se quedó sin códigos y compuso los colores restantes como la mezcla ya codificada más cercana, o que colocó una página PDF o una imagen que no pudo decodificar con sus propias tintas; o'missingImage', una imagen sin bytes dibujada como marcador de posición (esta solo se notifica a unonWarningpropio; sin él, los avisos de fuentes van aconsole.warn).inspectPrintMaster(bytes): Promise<PrintMasterReport>: lee la primera página de un máster de impresión en PDF e indica las fuentes que usa sin incrustarlas (nonEmbeddedFonts), si pinta en RGB (rgb) y si usa transparencias (transparency), para la verificación previa.inspectPrintPdf(bytes): Promise<PrintPdfReport>: lee un PDF terminado como lo haría la comprobación previa de una imprenta, todas sus páginas: la versión y el número de páginas, la identificación PDF/X y la intención de salida (y si su perfil va incrustado), el formato final y el sangrado más pequeño, las páginas con otro formato final, sin TrimBox o con una caja de página que no consta de cuatro números (malformedBoxPages, que se leen como si les faltara), las fuentes (fonts: nombre, incrustada o no, tipo; una fuente usada incrustada y sin incrustar aparece una vez de cada forma), en qué pinta (CMYK, gris, tintas planas por su nombre, registro, y RGB separado endeviceRgb, sin perfil, eiccRgb, con perfil, cada uno en pinturavectoro enimages), transparencias, sobreimpresión, anotaciones, un formulario interactivo y si está etiquetado. Además de las páginas, lee las apariencias de las anotaciones, los campos y los recursos por defecto del formulario, los motivos (patterns), los glifos Type 3 y las imágenes en línea. Lee lo que dice el archivo, no lo que pidió la configuración, y no lee la resolución de las imágenes, la tinta total, los filetes demasiado finos ni el reventado (trapping). Recorre las páginas igual queinspectPrintMaster, que además informa del RGB en sombreados, motivos y glifos Type 3.decompressWoff2(bytes): Uint8Array: función auxiliar que convierte un archivo WOFF2 en bytes TTF, que es el formato quepdf-libpuede incrustar directamente.createPdfWorker(options?), depostext-pdf/worker: la misma generación en un Web Worker; consulta Renderizar el PDF en un worker.
#Ejemplo mínimo
import { buildDocument } from 'postext';
import { renderToPdf } from 'postext-pdf';
const vdt = buildDocument(
{ markdown: '# Capítulo uno\n\nLa historia empieza aquí…' },
{
page: { sizePreset: '17x24' },
layout: { layoutType: 'double' },
bodyText: { fontFamily: 'EB Garamond', fontSize: { value: 9, unit: 'pt' } }, // 9 pt sobrescribe el valor por defecto de 8 pt
},
);
const pdfBytes = await renderToPdf(vdt, {
fontProvider: async (family, weight, style) => {
// Devuelve los bytes TTF para esta family/weight/style.
// Consulta la sección "Proveedor de fuentes" más abajo para una implementación real.
const res = await fetch(`/fonts/${family}-${weight}${style === 'italic' ? 'i' : ''}.ttf`);
return new Uint8Array(await res.arrayBuffer());
},
});
// `pdfBytes` es un Uint8Array — guárdalo, descárgalo o envíalo por streaming.
const blob = new Blob([pdfBytes], { type: 'application/pdf' });
const url = URL.createObjectURL(blob);
window.open(url);#¿Por qué un proveedor de fuentes?
pdf-lib incrusta archivos de fuente reales dentro del PDF: las fuentes instaladas en el navegador no están disponibles al generar el PDF, y una fuente que solo cargaste para medir en pantalla no basta, por sí sola, para producir un PDF autónomo. renderToPdf recorre las páginas buscando cada variante que pintan (una por cada combinación family|weight|style; consulta Qué variantes se piden al proveedor) e invoca tu proveedor una sola vez por combinación única. El proveedor devuelve un Uint8Array con bytes TTF u OTF, o una lista de ellos para una variante servida en varios archivos (consulta Fuentes chinas, japonesas y coreanas); pdf-lib reduce los contornos TrueType a un subconjunto con los glifos usados e incrusta enteros los archivos CFF (.otf). Una variante CFF se declara como tal, como una fuente CIDFontType0 con su programa CFF en FontFile3 (CIDFontType0C), que pdffonts muestra como CID Type 0C y que es lo que esperan las verificaciones previas de imprenta. Una variante CFF con claves CID (Source Han, los archivos .otf de Noto CJK) conserva la declaración TrueType, porque su numeración de glifos no coincide con la que usa el texto; para imprenta, usa las versiones TrueType de esas familias. Las variantes a las que el proveedor responde con el mismo archivo, como una redonda que sustituye a la negrita que falta en una familia, comparten una sola fuente incrustada. Una variante con la que ninguna página llega a dibujar, como la del texto de una figura SVG que acaba dibujada como imagen, no se escribe en el archivo.
Usa fuentes estáticas por peso, no una única fuente variable. Google Fonts a menudo sirve un único WOFF2 variable por familia que cubre todo el eje de pesos. pdf-lib solo puede incrustar la instancia por defecto de un archivo variable, por lo que un párrafo en negrita saldría con peso normal. Fontsource publica archivos WOFF2 estáticos por peso que resuelven el problema sin complicaciones; es lo que hace el Sandbox. Un archivo variable pedido con un peso distinto del de su instancia por defecto se notifica con un aviso variableFontDefaultInstance.
Cada palabra del texto cae donde la puso la maquetación. En los párrafos, los elementos de lista, las citas, los recuadros y el resto del texto corrido, cada palabra empieza en la posición que midió el VDT, así que una diferencia entre los anchos del navegador y los de la fuente incrustada nunca se acumula a lo largo de una línea. Una línea sin formato en línea se pinta como un solo objeto de texto que mueve el punto de escritura entre palabra y palabra; las líneas justificadas, las centradas y las que llevan formato se pintan palabra a palabra. Un carácter para el que la fuente no tiene glifo, que el navegador midió con otra fuente y que el PDF pinta como la caja de glifo ausente de la fuente, no mueve ninguna de las palabras que le siguen, y se notifica una vez por variante con un aviso missingGlyph. Un espacio que la fuente no tiene, como el espacio fino de no separación o el espacio de cifra, toma el ancho que le dio el navegador, y los caracteres invisibles, como la unión de palabras y el espacio de anchura cero, no se dibujan. Un guion de no separación (U+2011) que la fuente no tiene se dibuja con el guion de la fuente (U+2010), o con su guion-menos si tampoco tiene guion, como lo muestra el navegador; Open Sans y Outfit, entre otras, carecen de los dos. Ninguno de estos casos cuenta como glifo ausente. Hay dos excepciones. Una línea con letras de derecha a izquierda se sigue pintando como un solo tramo (consulta Idiomas y escrituras). El texto que coloca un diseño (titulillos, pies de página, aperturas, títulos de recuadro y otros elementos de diseño) se compone con los anchos propios de la fuente incrustada, así que allí un glifo que falta en la fuente sigue moviendo el resto de su línea.
#Qué variantes se piden al proveedor
renderToPdf recorre las páginas en el mismo orden en que las pinta y solo pide al proveedor las variantes que dibujan:
- la variante regular de un bloque que compone alguna línea, y la negrita, cursiva o negrita cursiva de cada tramo que de verdad tiene ese estilo;
- los tramos de los chips, las marcas de lista y el texto de los elementos de diseño (titulillos, folios, bandas de apertura y de parte);
- el texto del pie, de la nota y de las celdas de tabla de cada recurso;
- las variantes que indica el
<text>de una figura SVG, al incrustarla. Si el proveedor no puede servir ninguna variante de una familia, se pasa a la siguiente familia de la listafont-familydel SVG.
Así, nunca se pide la cursiva de una familia de encabezados que nadie inclina, y una figura sin nota no necesita las variantes de la nota.
Cuando el proveedor rechaza una variante, la generación sigue adelante. Se incrusta en su lugar otra variante de la misma familia y se emite un PdfWarning. La sustituta es la primera variante que carga, probando los nueve pesos estándar (de 100 a 900) en el orden que usa la selección de fuentes de CSS, que es también la variante que el navegador muestra en la vista previa:
- primero el mismo estilo. Para un peso entre 400 y 500, van primero los pesos hasta 500, después los más ligeros, del más cercano hacia abajo, y después los más gruesos, de 600 hacia arriba. Para un peso por debajo de 400, van primero los más ligeros, del más cercano hacia abajo, y después los más gruesos. Para un peso por encima de 500, van primero los más gruesos y después los más ligeros;
- después el otro estilo, cursiva para la redonda y redonda para la cursiva, en el peso pedido y en los demás pesos con el mismo orden.
Por eso, una familia sin cursivas compone en redonda sus tramos en cursiva, una familia que solo publica 400 y 700 toma un 600 como 700, y una familia que publica un único corte lo compone todo con él. Al proveedor se le pide una variante cada vez, en ese orden, y nunca dos veces la misma, así que nunca se incrusta una variante que nada usa. A una familia que el proveedor no puede servir en absoluto se le piden esas 18 variantes antes de que falle la generación.
const bytes = await renderToPdf(doc, {
fontProvider,
onWarning: (w) => {
// { kind: 'fontFallback', family: 'Oswald', weight: 700, style: 'italic',
// fallback: { weight: 700, style: 'normal' }, reason: '…', message: '…' }
console.info(w.message);
},
});Sin onWarning, el mensaje va a console.warn. El texto conserva sus posiciones, que vienen del VDT y se midieron con las variantes que tenía el navegador, así que una sustituta con otros anchos puede verse apretada o floja. Para corregirlo, proporciona la variante real. La generación solo falla (postext-pdf: failed to load font(s): …) cuando el proveedor no puede servir ninguna variante de una familia en un peso estándar, ni redonda ni cursiva.
#Proveedor de fuentes en el navegador (Fontsource + WOFF2)
El Sandbox incluye createPdfFontProvider() (packages/postext-sandbox/src/viewport/pdf/pdfFontProvider.ts), que puedes copiar en cualquier aplicación de navegador. Lo esencial:
import type { PdfFontProvider } from 'postext-pdf';
import { decompressWoff2 } from 'postext-pdf';
const bytesCache = new Map<string, Promise<Uint8Array>>();
function fontsourceId(family: string): string {
return family.toLowerCase().replace(/\s+/g, '-');
}
function fontsourceWoff2Url(
family: string,
weight: number,
style: 'normal' | 'italic',
): string {
const id = fontsourceId(family);
return `https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/files/${id}-latin-${weight}-${style}.woff2`;
}
export function createPdfFontProvider(): PdfFontProvider {
return async (family, weight, style) => {
const key = `${family}|${weight}|${style}`;
const cached = bytesCache.get(key);
if (cached) return cached;
const promise = (async (): Promise<Uint8Array> => {
const url = fontsourceWoff2Url(family, weight, style);
const res = await fetch(url, { mode: 'cors' });
if (!res.ok) throw new Error(`font fetch failed: ${res.status} ${url}`);
// pdf-lib necesita bytes TTF, así que descomprimimos el envoltorio WOFF2 en el cliente.
return decompressWoff2(new Uint8Array(await res.arrayBuffer()));
})();
bytesCache.set(key, promise);
return promise;
};
}Una versión de producción debería además:
- Consultar los pesos disponibles (vía
https://api.fontsource.org/v1/fonts/{id}) y ajustar el peso pedido al más cercano que la familia distribuye de verdad, para que una petición deweight: 600sobre una familia que solo tiene{400, 700}siga funcionando. - Recurrir a la redonda cuando una familia no tenga cursiva en el peso solicitado, en lugar de hacer fallar toda la generación.
- Reutilizar la caché de una generación a otra (mantén
bytesCachea nivel de módulo, no en cada llamada) para que regenerar el PDF tras un cambio de configuración sea prácticamente gratis.
#Fuentes chinas, japonesas y coreanas
Una fuente CJK no viene en un solo archivo pequeño. Fontsource distribuye Noto Serif SC en un centenar de archivos por peso, cada uno con una parte de los caracteres y declarado en la hoja de estilos de la familia con su unicode-range (@fontsource/noto-serif-sc/400.css); el navegador descarga los archivos que necesita el texto de la página. El archivo latin que pide el proveedor de arriba no tiene ni un solo carácter han, y los subconjuntos con nombre están incompletos: al chinese-simplified de Noto Serif SC le falta 釵, y el chinese-traditional de Noto Serif TC no tiene ninguno de los signos de ancho completo (),!?:;.
Por eso un proveedor puede responder a una variante con varios archivos. renderToPdf le pasa los caracteres que las páginas componen en esa variante (request.codePoints), reunidos de todos los capítulos antes de dibujar nada, y el proveedor devuelve los archivos que los contienen, en el orden en que el navegador los consulta. Cada archivo se incrusta como un subconjunto propio y cada carácter se dibuja con el primer archivo que tiene glifo para él: un capítulo que usa 60 fragmentos incrusta 60 subconjuntos pequeños. Si se vuelve a pedir la variante, por ejemplo para el texto de una figura SVG, solo se piden los caracteres que faltan en sus archivos. Un proveedor que devuelve un solo Uint8Array funciona como antes. El proveedor del Sandbox lee la hoja de estilos de Fontsource del peso y el estilo y descarga los archivos cuyos intervalos contienen el texto; su núcleo:
import type { PdfFontProvider } from 'postext-pdf';
import { decompressWoff2 } from 'postext-pdf';
type Slice = { url: string; ranges: Array<[number, number]> };
async function fontsourceSlices(family: string, weight: number, style: 'normal' | 'italic'): Promise<Slice[]> {
const id = family.toLowerCase().replace(/\s+/g, '-');
const cssUrl = `https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/${weight}${style === 'italic' ? '-italic' : ''}.css`;
const css = await (await fetch(cssUrl)).text();
return [...css.matchAll(/@font-face\s*{([^}]*)}/g)].map(([, rule]) => ({
url: new URL(/url\(\.?\/?([^)]+\.woff2)\)/.exec(rule)![1], cssUrl).href,
ranges: /unicode-range:\s*([^;]+);/.exec(rule)![1].split(',').map((part) => {
const [lo, hi = lo] = part.trim().slice(2).split('-');
return [parseInt(lo, 16), parseInt(hi, 16)] as [number, number];
}),
}));
}
export const sliceFontProvider: PdfFontProvider = async (family, weight, style, request) => {
// Where ranges overlap, the browser tries the last rule first.
const slices = (await fontsourceSlices(family, weight, style)).reverse();
const picked = new Set<Slice>();
for (const cp of request?.codePoints ?? []) {
const slice = slices.find((s) => s.ranges.some(([lo, hi]) => cp >= lo && cp <= hi));
if (slice) picked.add(slice);
}
if (picked.size === 0) picked.add(slices[0]!);
return Promise.all(slices.filter((s) => picked.has(s)).map(async (s) =>
decompressWoff2(new Uint8Array(await (await fetch(s.url)).arrayBuffer()))));
};Una familia latina pasa por el mismo código: un texto en inglés recibe solo su archivo latin, uno en checo recibe latin y latin-ext.
Un navegador no se queda con el primer archivo que tiene glifo. Compone cada carácter con el archivo declarado en último lugar entre aquellos cuyo unicode-range lo contiene, y los archivos de una familia se solapan: Fontsource repite las letras ASCII de Noto Serif JP en su archivo latin y en sus fragmentos numerados. Entre dos caracteres compuestos con dos archivos no hay kerning, así que el archivo decide el ancho: Chrome 154 compone Shift_JIS con 4,25 cuadratines de ancho cuando los fragmentos se declaran después de latin, y el archivo latin por sí solo, que aplica kerning a t_ y a _J, lo compone con 4,32. Desde postext-pdf 1.30 un proveedor puede decir cómo declaró la página cada archivo: declaredFontFile(bytes, { unicodeRange, order }) devuelve los mismos bytes con el unicode-range de la regla del archivo, tal como lo escribe CSS, y el lugar de esa regla entre las de la variante, un número cualquiera que crece con el orden de declaración (el mayor es el declarado en último lugar).
import { declaredFontFile } from 'postext-pdf';
declaredFontFile(bytes, { unicodeRange: 'U+0000-00FF,U+0131,U+0152-0153', order: 0 });Cuando los archivos de una variante incluyen sus intervalos, en un documento compuesto en su propio idioma (bodyText.shapingLanguage: 'document', el valor por defecto) cada carácter se dibuja con el archivo declarado en último lugar cuyo intervalo lo contiene y que tiene glifo para él, como elige un navegador entre las reglas @font-face, y una letra y sus signos combinantes quedan en un mismo archivo. Un carácter que ningún intervalo contiene se dibuja con el primer archivo que tiene glifo. Los archivos sin estos datos, y todos los de un documento con 'host', se leen en el orden dado, como antes, así que un proveedor que describe sus archivos sigue poniendo primero el declarado en último lugar. A una variante descrita así se le vuelven a pedir todos los caracteres que no se le habían pedido antes, porque puede tenerlos un archivo declarado más tarde. El proveedor del Sandbox describe sus archivos.
Los caracteres para los que ningún archivo de la variante tiene glifo se dibujan con el glifo .notdef de la fuente (una caja vacía en la mayoría), y renderToPdf los notifica una vez por variante cuando termina de dibujar las páginas:
// { kind: 'missingGlyph', family: 'Noto Serif TC', weight: 400, style: 'normal',
// characters: [',', '!', '?'], message: '…' }El Sandbox muestra estos avisos, y los dos siguientes, en su panel Revisión tras cada PDF que genera. Si cambian el libro, sus ajustes o sus recursos, se marcan como de un PDF anterior hasta que el siguiente los sustituye; abrir otro libro los retira.
- La negrita necesita un archivo estático por peso. Fontsource sirve cada peso de Noto Serif SC y TC en archivos estáticos propios, así que la negrita funciona en el Sandbox. Los archivos de Google Fonts (
NotoSerifSC[wght].ttf, 25 MB) son fuentes variables: pdf-lib incrusta su instancia por defecto, así que una variante 700 se imprime con peso 400, yrenderToPdflo notifica comovariableFontDefaultInstance. Para un paquete, genera una instancia estática por peso con fontTools (fonttools varLib.instancer NotoSerifSC[wght].ttf wght=700) y redúcela a los caracteres del libro conpyftsubset. - Usa las versiones TrueType. Source Han Serif y los archivos
.otfde Noto Serif CJK tienen contornos CFF, que postext-pdf incrusta enteros, de 8 a 25 MB por peso; una fuente CFF de más de 2 MB se notifica comocffEmbeddedWhole. Las versiones TrueType (Google Fonts, Fontsource) se reducen a los glifos usados. Para el japonés, Noto Serif JP y Noto Sans JP (Google Fonts, o los fragmentos numerados de Fontsource), Shippori Mincho, Zen Old Mincho y BIZ UDMincho vienen en TrueType; Source Han Serif JP y los archivos.otfJPde Noto Serif CJK son CFF. - Formas japonesas de una fuente panCJK. Un mismo punto de código, ya sea un carácter han, un signo de puntuación o unas comillas, puede dibujarse de una manera en Japón y de otra en China, y una fuente panCJK (Source Han, Noto CJK) tiene las dos. El PDF compone un documento japonés (
locale: 'ja'), y un fragmento aislado en japonés (:ltr[…]{lang=ja}) en cualquier documento, con el sistema de idioma OpenTypeJAN, de modo que la funciónloclde la fuente imprime las formas japonesas que el canvas y el HTML imprimen gracias alang. Un fragmento aislado en otro idioma dentro de un libro japonés se compone con las formas de ese idioma (las de la fuente por defecto, para el chino, con'host') y se etiqueta como unSpancon su/Lang. ConbodyText.shapingLanguage: 'document', el valor por defecto desde postext 1.30, todo documento y todo fragmento aislado se componen en su propio idioma (ZHSpara el chino simplificado), como lo midió la maquetación; con'host', los documentos chinos y los demás se componen con las formas por defecto de la fuente, como hasta ahora. Una fuente hecha para el japonés, como Noto Serif JP, ya tiene formas japonesas por defecto; aun así pone las “ ” del texto japonés en su formaJAN.
Un carácter que falta en una familia no se toma de otra: Noto Serif TC no toma prestado de Noto Serif SC. Resuelve la cobertura al preparar los archivos de fuente; el ejemplo de 红楼梦 copia desde la fuente SC los glifos que les faltan a sus subconjuntos TC.
#Proveedor de fuentes en el servidor (Node, archivos locales)
En Node puedes saltarte por completo el paso de WOFF2 y leer archivos TTF/OTF desde el disco:
import { readFile } from 'node:fs/promises';
import { join } from 'node:path';
import type { PdfFontProvider } from 'postext-pdf';
const FONT_DIR = '/ruta/a/fuentes';
function filename(family: string, weight: number, style: 'normal' | 'italic'): string {
const slug = family.replace(/\s+/g, '');
const styleSuffix = style === 'italic' ? 'Italic' : '';
const weightName =
weight >= 700 ? 'Bold'
: weight >= 600 ? 'SemiBold'
: weight >= 500 ? 'Medium'
: weight >= 300 ? 'Light'
: 'Regular';
return `${slug}-${weightName}${styleSuffix}.ttf`;
}
export const localFontProvider: PdfFontProvider = async (family, weight, style) => {
const buf = await readFile(join(FONT_DIR, filename(family, weight, style)));
return new Uint8Array(buf);
};#Bytes de recursos y másteres de impresión
resourceBytes(fileId) devuelve los bytes de una imagen, y el backend reconoce su formato por el contenido:
- PNG, JPEG, GIF y WebP se incrustan como imágenes;
- el marcado SVG se dibuja como trazados vectoriales, con su
textcompuesto como texto real con las fuentes incrustadas del documento, o se convierte en mapa de bits a 600 ppp en el navegador cuando usa funciones que quedan fuera del subconjunto vectorial. Un<style>que solo contiene reglas@font-face(variantes que incrustó el autor) se omite, y la figura sigue siendo vectorial (desde postext-pdf 1.25); cualquier otra hoja de estilo la convierte en mapa de bits, dibujado con las variantes que indica su texto, incrustadas desdefontProvider(salvo quediagramStyle.inlineFontso elsvg.inlineFontsdel recurso seafalse); - los TIFF y los documentos de Photoshop (PSD, PSB) se imprimen desde sus propios píxeles: gris, RGB o CMYK, de 8 o 16 bits, con el perfil ICC y la resolución que llevan. Uno CMYK conserva sus tintas tal cual; el gris y el RGB siguen
print.imageColor. De un documento de Photoshop se lee la imagen compuesta que guarda con «Maximizar compatibilidad»; los TIFF con compresión JPEG no se leen; - de un PDF se incrusta tal cual su primera página, como un XObject de formulario.
Cada imagen se guarda una sola vez en el archivo, aunque se dibuje muchas veces. Un SVG dibujado con trazados vectoriales se convierte en un XObject de formulario que pinta cada página, así que un marco o un logotipo en el diseño de página de un documento de treinta páginas se escribe una vez y no treinta; cada página más añade unos cientos de bytes. Hasta postext-pdf 1.4 cada página llevaba su propia copia de los trazados.
Una figura SVG puede indicar un máster de impresión en svg.pdfFileId: un PDF de una sola página con la misma figura, normalmente el original del que se exportó el SVG. renderToPdf pide primero a resourceBytes el identificador del máster. Incrusta esa página en lugar del SVG, con sus fuentes, degradados y espacios de color intactos, allí donde se dibuje el SVG: como figura, como imagen de una celda de tabla (TableCell.image), como imagen de diseño o como icono de un recuadro (también su marker). El VDT incluye el identificador del máster en cada uno de esos usos (svg.pdfFileId en el recurso de la figura, pdfFileId en la imagen de una celda y en un bloque de imagen de diseño), así que en un libro todos los capítulos reciben el máster. Los backends canvas y HTML siguen dibujando el SVG. En cambio, se usan los bytes del propio SVG en tres casos: si falta el máster, si no es un PDF o si la tinta única está activa (diagramStyle.singleInk solo recolorea marcado SVG).
const resources: Resource[] = [{
id: 'mapa', typeId: 'figure', kind: 'svg', createdAt: 0, updatedAt: 0,
svg: { fileId: 'mapa.svg', width: 800, height: 600, pdfFileId: 'mapa.pdf' },
}];
const archivos = new Map([['mapa.svg', bytesSvg], ['mapa.pdf', bytesMasterPdf]]);
const pdf = await renderToPdf(buildDocument({ markdown, resources }, config), {
fontProvider,
resourceBytes: (fileId) => archivos.get(fileId),
});Un anfitrión también puede devolver los bytes del máster para el identificador del propio SVG, como hace bundleResourceBytes; las dos formas funcionan.
Un navegador no puede mostrar un TIFF ni un documento de Photoshop, así que un recurso de mapa de bits hecho a partir de uno guarda dos archivos: bitmap.fileId es una vista previa en PNG, que muestran el canvas, el HTML y el EPUB, y bitmap.printFileId (con printFormat: 'tiff' | 'psd') es el original. Un anfitrión devuelve los bytes del original para bitmap.fileId, como hacen bundleResourceBytes y el Sandbox, y el PDF se imprime desde él. También pasa la vista previa, como previewBytes (bundlePreviewBytes en un paquete): un original que no se puede decodificar se imprime desde su vista previa, con un aviso pictureOriginalUnreadable, y sin ella queda un marcador. decodePrintRaster(bytes) y rasterToRgba(raster) de postext leen el original y hacen la vista previa; el Sandbox la hace al importar el archivo, y un paquete guarda el original como resources/<nombre>.tif o .psd junto a la vista previa.
Un archivo de Adobe Illustrator guardado con «Crear archivo compatible con PDF» es un PDF, y puede ser un máster de impresión como cualquier otro (.ai). Sus muestras son sus propias planchas: la comprobación previa enumera las que la tabla de tintas renombra, las que ningún color del libro define y, en un trabajo con planchas propias (print.plates), las que el trabajo no imprime, porque un archivo colocado se imprime tal cual.
#Texto vertical en el PDF
Una página vertical (layout.writingMode: 'vertical-rl') se dibuja a través de un marco girado un cuarto de vuelta, igual que la pinta el canvas, y su texto se compone de arriba abajo en la columna:
- Los caracteres de pie se muestran con una segunda fuente Type0 del mismo archivo incrustado: la misma CIDFont, los mismos anchos y el mismo mapa ToUnicode, con
Encoding /Identity-V(modo vertical). Un tramo de caracteres es un solo objeto de texto cuyos glifos avanzan por sí mismos un cuadratín columna abajo (DW2 [880 −1000]), así que los lectores seleccionan y extraen una columna como una línea. La forma de los glifos se ajusta convertyfwidde OpenType, que dan su forma vertical a los paréntesis, las comillas, los signos de pausa de China continental, los puntos suspensivos y las rayas; un carácter que queda de pie tal cual conserva su glifo horizontal. Nada de la fuente se incrusta dos veces. - Las palabras latinas y los números largos van tumbados con la fuente horizontal; un número en una casilla queda de pie, estrechado hasta el cuadratín si es más ancho; un signo sin forma vertical en la fuente se gira o se desplaza, como en el canvas.
- El espaciado entre caracteres se escribe como números de
TJ, que en modo vertical bajan el punto de escritura por la columna. - Cada línea vertical lleva un
/ActualTextcon su texto, de modo que, al copiarla o extraer el texto, se lee tal como se escribió.pdftotexty pdf.js leen las columnas de arriba abajo y de derecha a izquierda; pdf.js empieza una línea nueva en un número compuesto en una casilla. - Los enlaces, los marcadores y los destinos se trasladan a la hoja: un enlace sobre una línea vertical es un rectángulo alto y estrecho, y un marcador abre la página en lo alto de la columna de su encabezado.
- Un PDF etiquetado declara el sentido de escritura en su elemento
Document(el atributo de maquetaciónWritingMode /TbRl, que heredan todos los elementos); la validación PDF/UA-1 (veraPDF) pasa en un capítulo vertical. - Visores: Acrobat, Vista Previa, Chrome (PDFium), pdf.js y Poppler pintan las fuentes verticales. Un libro encuadernado por la derecha (
page.binding) pide además a los visores que muestren las dobles páginas de derecha a izquierda (/Direction /R2L,/PageLayout /TwoPageRight); Acrobat y Foxit lo siguen, Chrome no.
Un capítulo de 43 páginas compuesto en Noto Serif TC (los caracteres del libro, TrueType) ocupa unos 820 KB, casi todo de los dos subconjuntos de la fuente.
#Campos de formulario
Un chip con el atributo field es un campo de formulario rellenable (AcroForm). El chip se compone y pinta su caja como cualquier chip: su estilo da el aspecto y el ancho mínimo (minWidth), sus palabras son el valor inicial del campo. El PDF pone un campo interactivo sobre la caja; un nombre usado dos veces es un campo con dos widgets.
Cantidad :chip[ ]{style="field" field="pos.a.qty" kind="number"}
Precio :chip[120]{style="field" field="pos.a.price" format="currency"}
Total :chip[ ]{style="field" field="pos.a.total" format="currency" calc="product(pos.a.qty, pos.a.price)"}
Servicio :chip[ ]{style="box" field="pkg.a" kind="checkbox" on="1"}
Total del pedido :chip[ ]{style="field" field="order.total" format="currency" calc="sum(pos.a.total, product(pkg.a, 161.75))"}
Talla :chip[M]{style="field" field="size" kind="choice" options="S|M|L"}kind:text(por defecto),number,checkbox,choice(conoptions, separadas por|). Un chip conformatocalcy sinkindes un campo numérico.on(una casilla): el nombre del estado activado de la casilla, que es el valor que leen sus scripts cuando está marcada. Conon="1", una casilla marcada cuenta 1 en un cálculo, de modo queproduct(pkg.a, 161.75)suma un precio fijo cuando se marca. Por defecto esYes, que un cálculo cuenta como 0.format:currency,decimal(dos decimales),integer. Se escribe conAFNumber_FormatyAFNumber_Keystrokede Acrobat, con los separadores del idioma del documento (1.234,56en alemán y en español) salvo queRenderToPdfOptions.forms.separatorStylediga otra cosa; la moneda esforms.currency(por defecto€), delante del número salvo queforms.currencyBeforeseafalse. El valor inicial se dibuja ya formateado.calc:sum(…),product(…),min(…),max(…)oavg(…). Los argumentos son otros campos por su nombre, números (con punto decimal,161.75) y cálculos anidados:sum(pos.a.total, pos.b.total, product(pkg.a, 161.75)). Un cálculo solo sobre campos se escribe comoAFSimple_Calculate. Uno con números o cálculos anidados es un script de cálculo propio y breve, que lee cada campo de la misma manera (AFMakeNumberde su valor; lo que no es un número cuenta 0) y redondea el resultado a seis decimales. Un campo calculado es de solo lectura y el orden de cálculo sigue todos los campos que lee, también los anidados. Dan un avisoformField: un cálculo que lee un campo desconocido (cuenta 0), un ciclo, un nombre usado para dos tipos y una casilla en un cálculo cuyo valoronno es un número (siempre cuenta 0).readonly,required,multilineytooltip, como dicen sus nombres.
Un campo muestra su valor, y lo que se escribe en él, en la fuente de su chip (forms.font: 'chip', por defecto) o en una fuente del documento que nombre forms.font ({ family, weight?, style? }, que se pide al fontProvider como cualquier otra). Esa fuente se incrusta entera, no como subconjunto, porque a un subconjunto le faltarían los glifos de lo que se escriba después; se incrusta una sola vez aunque la usen muchos campos, se nombra en los recursos por defecto del formulario (/DR) y en la apariencia por defecto de cada campo (/DA), y los valores iniciales se dibujan con ella. Una fuente entera añade su archivo completo al PDF (una fuente de texto latina suele ocupar entre 50 y 300 KB, una CJK varios MB), además del subconjunto que usa el texto de las páginas. El proveedor puede responder con TrueType, OpenType o WOFF2 (que se descomprime antes de incrustarlo). Los campos vuelven a Helvetica, con un aviso formField, cuando la fuente no se puede incrustar entera: su licencia lo prohíbe (fsType de OS/2 restringido o solo mapas de bits), el proveedor la da en varios archivos (una fuente troceada) o su formato es WOFF o una colección. Con forms.font: 'helvetica' se usa Helvetica sin incrustar nada. Algunos visores (la Vista Previa de macOS, por ejemplo) dibujan el texto que se está escribiendo con una fuente propia; el valor es el mismo.
Acrobat, Foxit, pdf.js (Firefox) y la mayoría de los visores ejecutan estos scripts. Un estándar de impresión (PDF/X) no admite campos interactivos: allí los valores se pintan como texto, y el de un campo numérico tal como lo muestra el formulario (formateado, alineado al final de la caja dentro del paddingX propio del estilo, en el color del chip).
El canvas pinta un campo numérico de la misma manera, así que la vista previa coincide con el PDF: pasa a renderPageToCanvas (o a renderPage, renderToCanvas) la misma opción forms que a renderToPdf; en ambos, los separadores salen por defecto del locale del documento (si no, de su idioma de separación silábica). Una sola regla escribe los números en todas partes, y postext la exporta para otros escritores: formNumberStyle(forms, lang) resuelve las opciones, formatFieldNumber(value, format, style) formatea un valor (undefined para un texto que no es un número) y numberFieldText(field, words, style) da lo que muestra un campo numérico pintado. La lista de visualización lleva el campo en el tramo del chip (inline.field, con el sizePx y el padPx de la composición).
Un libro puede guardar estas opciones en su configuración: pdfGeneration.forms admite los mismos campos (currency, currencyBefore, separatorStyle, font). renderToPdf y el canvas toman cada uno de su propia opción forms primero, luego del pdfGeneration.forms del primer documento y, por último, de los valores por defecto. No cambia la maquetación, solo cómo se escriben y se pintan los campos. En el Sandbox es el grupo Campos de formulario de la sección PDF.
pdfGeneration: {
forms: { currency: 'USD', currencyBefore: true, separatorStyle: 0, font: { family: 'Lora', weight: 400 } },
}Desde esm.sh en un navegador, importa https://esm.sh/postext-pdf?bundle. La compilación por defecto de pdf-lib en esm.sh deja sus clases de anotación en un módulo aparte, y pdf-lib rechaza entonces el widget de cada campo: el PDF conserva las casillas, pero pierde formatos, cálculos y marcas, con un aviso formField por campo. ?bundle compila pdf-lib en un solo módulo y deja postext fuera, compartido con la página. Un empaquetador (Vite, webpack, Next.js) y Node no se ven afectados.
La exportación IDML escribe los mismos campos como campos de formulario de InDesign (véase Uso programático › Paquetes de InDesign).
#Enlaces en el PDF
Las palabras de un enlace Markdown (consulta Formato del documento › Enlaces) se convierten en anotaciones de enlace URI, una por cada tramo de palabras enlazadas de una línea. Cada anotación cubre la caja de la línea y no lleva borde. En un PDF accesible, cada tramo es un elemento Link cuyo /Contents es su texto. Solo se enlazan destinos absolutos http:, https:, mailto:, tel: y ftp:, porque una URL relativa no tiene base dentro de un PDF. Los caracteres que quedan fuera del ASCII imprimible se codifican con secuencias de porcentaje. Las citas :ref y las filas del índice conservan sus enlaces internos al documento.
#Ejemplo completo en el navegador: componer, renderizar, descargar
Todo junto: construir el VDT, generar el PDF y lanzar la descarga desde el navegador:
import { buildDocument, createMeasurementCache } from 'postext';
import { renderToPdf } from 'postext-pdf';
import { createPdfFontProvider } from './pdfFontProvider';
const fontProvider = createPdfFontProvider();
export async function downloadPdf(markdown: string, config: PostextConfig) {
const cache = createMeasurementCache();
const vdt = buildDocument({ markdown }, config, cache);
const bytes = await renderToPdf(vdt, { fontProvider });
const blob = new Blob([bytes.slice().buffer], { type: 'application/pdf' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'document.pdf';
document.body.appendChild(a);
a.click();
a.remove();
setTimeout(() => URL.revokeObjectURL(url), 1000);
}Importante: llama a ensureConfigFontsLoaded(config) (o equivalente) antes de buildDocument cuando tu configuración haga referencia a fuentes web. La maquetación se mide con las métricas que el navegador tenga en ese momento para esa familia: si la fuente real aún no ha llegado, el VDT se mide con una fuente de reserva y el PDF no coincidirá con la salida en canvas o en HTML. El Sandbox lo hace explícitamente antes de cada generación (véase packages/postext-sandbox/src/viewport/pdf/PdfViewport.tsx).
#Ejemplo en vivo: un PDF en el navegador
El flujo completo anterior, en funcionamiento en el navegador: el pen importa postext y postext-pdf desde una CDN, carga las fuentes web, construye el documento, incrusta los cortes de Fontsource a través del proveedor de fuentes y entrega los bytes a un enlace que abre el archivo en una pestaña nueva y a otro de descarga. El PDF resultante tiene los mismos saltos de línea que la salida en canvas y HTML, fuentes incrustadas reales y marcadores del documento.
import { buildDocument } from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';
const markdown = `# The Lantern
The lantern hung from a nail by the door, and every evening someone lit it. Nobody remembered who had put the nail there, or why the lantern was never moved.
## Two columns
Postext lays this text out in **two columns**, breaking each paragraph with the *Knuth–Plass* algorithm and hyphenating with TeX patterns. Widows and orphans are avoided, and the columns are balanced on the last page.
The light it gave was small, but it was enough to find the step. The lantern hung from a nail by the door, and every evening someone lit it. Nobody remembered who had put the nail there, or why the lantern was never moved.`;
const config = {
page: { sizePreset: '17x24' },
layout: { layoutType: 'double' },
bodyText: { fontFamily: 'EB Garamond', fontSize: { value: 10, unit: 'pt' } },
};
// The PDF embeds real font files. Fontsource publishes one static WOFF2 per
// weight and style; decompress it to the TTF bytes pdf-lib can embed.
const fontProvider = async (family, weight, style) => {
const id = family.toLowerCase().replace(/\s+/g, '-');
const url = `https://cdn.jsdelivr.net/npm/@fontsource/${id}@latest/files/${id}-latin-${weight}-${style}.woff2`;
const res = await fetch(url);
if (!res.ok) throw new Error(`font fetch failed: ${res.status} ${url}`);
return decompressWoff2(new Uint8Array(await res.arrayBuffer()));
};
// Layout is measured with the browser's fonts, so load them before building:
// otherwise the PDF would not match the canvas or HTML output.
await Promise.all([
document.fonts.load('16px "EB Garamond"'),
document.fonts.load('bold 16px "EB Garamond"'),
document.fonts.load('italic 16px "EB Garamond"'),
document.fonts.load('bold 16px "Open Sans"'), // the default heading face
]);
const doc = buildDocument({ markdown }, config);
// Same VDT, now translated to PDF points: identical line breaks and placement.
const bytes = await renderToPdf(doc, { fontProvider });
// A PDF viewer cannot run inside this sandboxed result frame,
// so hand the file to a new tab and to a download link.
const url = URL.createObjectURL(new Blob([bytes], { type: 'application/pdf' }));
document.getElementById('open').href = url;
document.getElementById('download').href = url;
document.getElementById('links').hidden = false;
document.getElementById('status').textContent =
`${doc.pages.length} page(s) · ${(bytes.length / 1024).toFixed(0)} KB PDF`;index.html
<p id="status">Rendering…</p>
<p id="links" hidden>
<a id="open" target="_blank" rel="noopener">Open lantern.pdf in a new tab</a> ·
<a id="download" download="lantern.pdf">Download it</a>
</p>style.css
body {
margin: 16px;
font-family: system-ui, sans-serif;
}Carga un editor interactivo desde codepen.io. El ejemplo importa la última versión publicada de postext desde un CDN.
#Renderizar el PDF en un worker
postext-pdf/worker saca renderToPdf del hilo principal. El worker escribe el texto, las figuras vectoriales, el árbol de estructura y el propio archivo. Hay dos tareas que necesitan la página, así que el worker se las pide al hilo principal: descargar las fuentes y convertir un SVG en mapa de bits a través de un <img>. En un libro de cientos de páginas, la generación tarda segundos que, si no, congelarían la página; para unas pocas páginas, llamar directamente a renderToPdf es más sencillo.
import { createPdfWorker } from 'postext-pdf/worker';
const pdfWorker = createPdfWorker();
const bytes = await pdfWorker.render(docs, {
fontProvider, // se ejecuta en este hilo
resourceBytes: new Map([['mapa.svg', bytesSvg]]), // un Map; sus buffers pasan al worker
onProgress: ({ phase, pages, totalPages }) => mostrarProgreso(phase, pages, totalPages),
onWarning: (w) => console.info(w.message),
});
pdfWorker.dispose();render(docs, options)acepta un documento o la lista de documentos de los capítulos de un libro. Acepta las opciones derenderToPdf, con dos diferencias.resourceBytes(ypreviewBytes) es unMap<string, Uint8Array>cuyos buffers se transfieren, así que pasa copias de los bytes que quieras conservar.rasterizeSvg, si se indica, se ejecuta en el hilo principal; por defecto lo hacen elImagey el canvas de la propia página.- Cada handle genera un documento cada vez.
dispose()termina el worker y rechaza cualquier generación que siga pendiente con unAbortError(DOMException), que debe tratarse como una cancelación. Si el proveedor responde con una fuente o una imagen después dedispose(), la respuesta se descarta. inspect(bytes)lee de nuevo un PDF terminado en el worker (inspectPrintPdf) y se resuelve con su informe, o conundefinedsi los bytes no se pueden leer como PDF. Los bytes se copian, así que los tuyos siguen sirviendo. No se lee nada si no lo llamas.createPdfWorker({ worker })acepta unWorkerque crees tú, para las herramientas de compilación que controlan las URL de los workers. Ese worker debe ejecutarpostext-pdf/worker/entry.
Desde una CDN. Por defecto, el script del worker se carga desde la URL del propio paquete (new URL('./pdf.worker.js', import.meta.url)). Una página de otro origen puede no poder arrancarlo: importado desde esm.sh, createPdfWorker() lanza Failed to construct 'Worker': Script at 'https://esm.sh/postext-pdf@…/pdf.worker.js' cannot be accessed from origin …. Arranca en su lugar un worker de módulo del mismo origen que importe la entrada (si fijas una versión, fija la misma en las dos URL):
import { createPdfWorker } from 'https://esm.sh/postext-pdf/worker';
const entrada = URL.createObjectURL(new Blob(
["import 'https://esm.sh/postext-pdf/worker/entry';"],
{ type: 'text/javascript' },
));
const pdfWorker = createPdfWorker({ worker: new Worker(entrada, { type: 'module' }) });El worker de composición de postext/worker no lo necesita: createLayoutWorker() arranca su propia entrada desde esm.sh sin opciones, y desde cualquier otro servidor con su opción url (consulta Cargar el worker desde una CDN).
#PDF listos para la imprenta
Para la producción de impresos, ajusta estas opciones de configuración antes de generar el PDF:
page.cutLines.enabled: true: añade un área de sangrado y marcas de corte alrededor del formato de corte, y da a cada página una TrimBox y una BleedBox. Véase Marcas de corte.print: { standard: 'pdfx4', outputProfile: 'fogra51' }(o'pdfx1a'): un archivo PDF/X con la condición de salida, la identificación y las cajas que revisa una imprenta; cada color y cada imagen RGB se separan con el perfil ICC, el 100 % K sobreimprime y las grandes masas negras salen en negro enriquecido. Véase Producción para imprenta (configuración).colorSpace: 'cmyk'(opdfGeneration: { forceColorSpace: true, colorSpace: 'cmyk' }): la misma separación sin la identificación PDF/X (las marcas de corte van siempre en color de registro). Los originales de impresión en PDF se incrustan tal como son.page.dpi: 300: los px por pulgada de la maquetación; un mapa de bits sin resolución propia se imprime a esta resolución a su tamaño natural. La verificación previa (preflight) avisa de las imágenes que quedan por debajo de 300 ppp a su tamaño impreso.ColorValue.cmyk: un color definido en CMYK se imprime con sus valores exactos.{ pageNegative: true }enRenderToPdfOptions: invierte el área de corte con un modo de fusión Diferencia (las marcas de corte no se invierten). Es útil en la verificación previa de tipografía oscura sobre fondo claro.
#Tintas planas
Una tinta plana (un Pantone, una tinta corporativa, un barniz) se imprime en su propia plancha. Un color con model: 'spot' lleva su tinta en ColorValue.spot: name es el nombre de la plancha tal como lo conoce la imprenta, cmyk es el aspecto de la tinta al 100 % (el equivalente que el PDF da a quien no tenga la tinta), tint es el tono en porcentaje (100 por defecto) y overprint hace que la tinta sobreimprima lo que tiene debajo en lugar de vaciarlo, como un barniz. hex es su representación en pantalla.
Un PDF CMYK o PDF/X escribe cada tinta como un espacio de color Separation con su nombre, y cada color de esa tinta se pinta a su tono: los colores con el mismo name comparten plancha. Así caben las tres formas habituales de trabajar: dos tintas (negro y una plana), cuatricromía con algunos elementos en plana, y un barniz sobreimpreso en zonas concretas. Si diagramStyle.singleInk usa una tinta plana, los diagramas SVG se imprimen en tonos de esa plancha. En un PDF RGB y en pantalla, el color se pinta con su hex.
Tintas planas dentro de un SVG. Véase Cómo funciona la tinta única.
colorPalette: [
{ id: 'brand', name: 'Brand', value: { hex: '#1f3f99', model: 'spot', spot: { name: 'PANTONE 286 C', cmyk: { c: 100, m: 66, y: 0, k: 2 } } } },
{ id: 'brand-40', name: 'Brand 40 %', value: { hex: '#a5b6dd', model: 'spot', spot: { name: 'PANTONE 286 C', cmyk: { c: 100, m: 66, y: 0, k: 2 }, tint: 40 } } },
{ id: 'varnish', name: 'Varnish', value: { hex: '#f4f4ee', model: 'spot', spot: { name: 'Varnish', cmyk: { c: 0, m: 0, y: 10, k: 0 }, overprint: true } } },
],
diagramStyle: { singleInk: true, inkColor: { hex: '#1f3f99', model: 'spot', paletteId: 'brand' } },El preflight cuenta una tinta plana como una sola tinta, la deja fuera del límite de cobertura y enumera las tintas planas del trabajo (spotInks), también las que nombran las imágenes SVG. Avisa si una tinta se define dos veces con valores distintos (spotInkConflict; el PDF usa la primera definición), si un SVG nombra una tinta que no define ningún color de la paleta ni ninguna entrada de la tabla de tintas con cmyk (spotInkUndefined; se imprime en una plancha propia, con el CMYK del color del SVG como equivalente, una plancha por nombre), si el PDF tiene que escribir el nombre de una plancha de otra forma (spotInkName, véase más abajo) y si dos nombres de plancha solo difieren en mayúsculas o espacios (spotInkSimilar: PANTONE 185 C y Pantone 185 C serían dos planchas). preflightDocument sabe qué tintas nombra un SVG por svgInks(fileId), una función que devuelve los nombres que svgSpotInks(markup) encuentra en el archivo; el panel Revisión del Sandbox y postext check se la pasan.
Nombres de plancha. El nombre se escribe tal como se teclea: las tildes, los símbolos y # llegan al PDF en UTF-8 (Rojo Médica es /Rojo#20M#C3#A9dica), que es como lo leen Acrobat, un RIP y el preflight de la imprenta. Un nombre que una plancha no admite se escribe con otro: All, None, Cyan, Magenta, Yellow y Black, en mayúsculas o minúsculas, llevan detrás la palabra ink (All ink); los caracteres de control se quitan, y un nombre de más de 127 bytes en UTF-8 se corta entre dos caracteres y termina en un hash corto, de modo que dos nombres largos que empiezan igual siguen siendo dos planchas. El spotInkName del preflight dice el motivo (problem: reserved, process, control o tooLong) y el nombre que escribe el PDF (written), y el render avisa de cada cambio por onWarning (spotInkRenamed). Para elegir tú el nombre, da a la tinta un pdfName en la tabla de tintas.
Una tinta por color. Un render de impresión reconoce un color por su hex de pantalla, así que dos colores que fijan sus valores de impresión —dos tintas, o una tinta y un color definido en CMYK— no pueden compartirlo. Si lo comparten, el segundo pasa al hex libre más cercano, a un paso e invisible en pantalla, y cada uno sale en su plancha. Un color de pantalla (model: 'hex') con el hex de una tinta plana se imprime como esa tinta; enlázalo a la entrada de la paleta para dejarlo explícito. El color que se mueve también cambia en pantalla, un paso (1/255) en un solo canal, el azul primero, en todas las salidas (canvas, HTML, EPUB y PDF RGB). Queda muy por debajo de lo que el ojo distingue, y es el precio de un render de impresión que lee las tintas del hex pintado. La configuración guardada no cambia.
La tabla de tintas
print.inks dice cómo llegan a la imprenta las tintas del trabajo, las llamen como las llamen los colores, los SVG y los archivos importados. Una tinta que no aparece en la tabla se imprime como la definen sus colores.
interface PrintInk {
name: string; // La tinta tal como la nombra spot.name o un SVG.
aliases?: string[]; // Otros nombres de la misma tinta: salen en esta plancha.
pdfName?: string; // El nombre de la plancha en el PDF. Por defecto, name.
output?: 'spot' | 'process'; // 'process' imprime la tinta en CMYK, con su equivalente.
cmyk?: CmykPercent; // El equivalente al 100 %, por encima del de los colores.
overprint?: boolean; // Por encima del de los colores.
}Los nombres y los alias se comparan sin distinguir mayúsculas ni espacios repetidos. Renombrar es una línea, la usen cuantos colores la usen; un alias junta en una plancha los nombres que una muestra del diseñador, un SVG (data-spot, icc-named-color) o una paleta anterior daban a la misma tinta; y output: 'process' imprime una tinta en CMYK cuando la máquina no tiene cuerpo para ella, con todos sus tonos.
En el Sandbox, la tabla está en Diseño › Exportación › Preparación para imprenta › Tabla de tintas: una tarjeta por tinta con su Nombre de la tinta, Alias, Nombre de la plancha en el PDF, Se imprime como, CMYK alternativo y Sobreimpresión. Tintas que usan los colores enumera las tintas de los colores del libro que faltan en la tabla, cada una con un botón que la añade.
print: {
standard: 'pdfx4',
inks: [
{ name: 'Azul corporativo', pdfName: 'PANTONE 286 C', aliases: ['Pantone 286C', 'Azul'] },
{ name: 'Varnish', output: 'process' },
],
},Impresión a dos tintas
print.plates dice en qué planchas se imprime el trabajo, y no se imprime en ninguna otra: un libro en negro y una tinta plana, en dos tintas planas o solo en negro. Las planchas de cuatricromía se llaman Cyan, Magenta, Yellow y Black; una plancha de tinta plana se nombra como la nombra el PDF, o con un nombre o un alias de la tabla de tintas.
interface PrintPlatesConfig {
inks?: string[]; // Las planchas. Vacío: todas, como siempre.
images?: string[]; // Las planchas de las imágenes: una o dos.
curves?: Record<string, Array<[number, number]>>; // La curva de una plancha de imagen: [tono, tinta] en porcentaje.
}- Un color de una tinta que el trabajo imprime, o un color CMYK cuyos canales imprime, sale tal cual.
- Cualquier otro color se proyecta: se imprime con la mezcla de una plancha o dos que, a través del perfil de salida, más se le parece. Una mezcla de dos tintas es un espacio de color
DeviceNen el PDF, y un gris se queda solo enBlack. El negro enriquecido se descarta salvo que el trabajo imprima las cuatro tintas de cuatricromía. - Las imágenes salen en monotono, en una plancha, o en duotono, en dos: el tono de cada píxel (su luminosidad) pasa por la curva de cada plancha.
imageses por defectoBlack, o la primera plancha si el trabajo no imprime negro. La curva de un monotono es una recta; un duotono pone su primera plancha en las sombras y la segunda en los medios tonos.curvessustituye cualquiera de ellas.
print: {
standard: 'pdfx4',
plates: {
inks: ['Black', 'PANTONE 286 C'],
images: ['Black', 'PANTONE 286 C'],
curves: { 'PANTONE 286 C': [[0, 0], [50, 35], [100, 70]] },
},
},La comprobación previa enumera las planchas del trabajo y cada color que la proyección desplaza. Una tinta plana o un color CMYK que el trabajo no imprime es información cuando su mezcla queda a menos de ΔE 6, y un aviso si queda más lejos o mientras no se ha cargado el perfil de salida (offPlateInk, offPlateCmyk); un color de pantalla que queda a más de ΔE 6 también es un aviso (offPlateColor). Una plancha de tinta plana que ningún color ni ninguna entrada de la tabla de tintas define es un aviso: se imprime y se simula como negro. En un trabajo así se deja de lado el original de imprenta de una figura y su SVG se compone en las planchas; una página PDF colocada, o una imagen que no se puede decodificar, conserva sus propias tintas y el render avisa (artworkOffPlates). En el Sandbox las planchas se eligen en Preparación para imprenta → Planchas. Sus vistas previas y la vista de impresión muestran los colores como los define el libro, no como los imprimen las planchas: mira el PDF, donde Comprobar para imprenta enumera las tintas que usa.
#Color de las imágenes
Una imagen se separa desde los colores en que se hizo. print.imageColor dice cómo se leen sus píxeles:
interface PrintImageColorConfig {
embeddedProfile?: 'use' | 'ignore'; // El perfil ICC de la propia imagen. Por defecto, 'ignore'.
assignedRgbProfile?: { name: string; fileId: string }; // Leer toda imagen RGB con este .icc.
grayDotGain?: 'profile' | 'none' | number; // Imágenes en gris, en negro. Por defecto, 'none'.
cmykProfile?: 'convert' | 'keep'; // Una imagen CMYK de otra máquina. Por defecto, 'keep'.
}Los valores por defecto dejan las imágenes como las imprimían las versiones anteriores: toda imagen RGB se lee como sRGB ('ignore'), las imágenes en gris se separan como cualquier otra ('none') y una imagen CMYK conserva sus valores ('keep'). Cada comportamiento de la lista se activa con su campo.
- Su propio perfil. Un PNG (
iCCP) o un JPEG (ICC_PROFILE) que incrusta un perfil se lee a través de él, de modo que una fotografía en Adobe RGB o Display P3 se separa como se ve y no como si fuera sRGB. Una imagen sin perfil, o con perfil sRGB, se lee como sRGB, como hasta ahora.'ignore'lee todas las imágenes como sRGB. - Un perfil asignado.
assignedRgbProfilenombra un.iccguardado con el que se lee toda imagen RGB, lleve el perfil que lleve: por ejemplo, para un lote de fotografías que perdieron el suyo. Sus bytes llegan porresourceBytes; si faltan, se usan los perfiles de las imágenes, con un avisoimageProfileUnavailable. - Conservada para el RIP. En PDF/X-4 con
convertImages: false, una imagen con un perfil distinto de sRGB se escribe en sus propios colores, etiquetadaICCBasedcon ese perfil, y la convierte el RIP de la imprenta. - Escala de grises. Una imagen en escala de grises (un PNG o un JPEG en gris, o una con perfil de gris) se imprime solo en negro, nunca como un gris de cuatricromía. Sus tonos, leídos a través de su perfil (o como los muestra la pantalla), se ajustan a la máquina:
'profile', con el negro del perfil de salida, cuya ganancia de punto ya incluye la condición; un número es la ganancia de punto de la máquina en el tono del 50 %, en porcentaje (entre 10 y 30, normalmente), que se compensa en su lugar;'none'escribe los valores tal cual, como hasta ahora.
print: {
standard: 'pdfx4',
imageColor: { grayDotGain: 20 },
},- Una imagen CMYK de otra máquina. Una imagen CMYK cuyo perfil es otra condición de impresión (una fotografía separada para SWOP o para papel prensa en un libro para FOGRA) se separa de nuevo para la de salida (
cmykProfile: 'convert'), y el negro solo sigue siendo negro solo: un TIFF o un documento de Photoshop desde sus píxeles; un JPEG CMYK, cuyos píxeles no se descomprimen, se etiquetaICCBasedcon su propio perfil en PDF/X-4 para que lo convierta el RIP, y pasa tal cual en PDF/X-1a, que no admite esa etiqueta; ahí la comprobación previa avisa (cmykImageForeign) cuando el anfitrión le da el perfil de la imagen (imageProfile). En PDF/X-4 conconvertImages: false, un TIFF o un documento de Photoshop se etiqueta igual.'keep'imprime los valores de toda imagen CMYK tal cual.
Los ajustes de una sola imagen. El printColor de un recurso admite los mismos campos que print.imageColor del libro y los aplica solo a esa imagen: una fotografía cuyo perfil hay que ignorar, otra que se lee con un perfil asignado, una imagen en gris con otra ganancia de punto. En el Sandbox, la ficha de una imagen dice si se lee con su propio perfil («Color en imprenta»), cómo se ajustan sus grises a la máquina («Grises en imprenta») y qué perfil se le asigna («Perfil asignado», un archivo .icc); un paquete lleva los perfiles asignados, el del libro y los de las imágenes, en su carpeta profiles/. Los ajustes del libro están en Preparación para imprenta → Imágenes.
{ id: 'archive-photo', kind: 'bitmap', bitmap: { fileId: 'photo.jpg', format: 'jpeg', width: 2400, height: 1600 },
printColor: { embeddedProfile: 'ignore' } }#Colores definidos en CMYK
Un color escrito en CMYK conserva sus valores exactos: en una salida para imprenta, ColorValue.cmyk (en porcentaje) se usa tal cual, y hex es su representación en pantalla. Una entrada de la paleta definida en CMYK se aplica a todos los colores vinculados a ella.
colorPalette: [
{ id: 'brand', name: 'Brand', value: { hex: '#00a0e3', model: 'cmyk', cmyk: { c: 100, m: 0, y: 0, k: 0 } } },
],#Colores que sobreimprimen
Cualquier color puede sobreimprimir en una salida para imprenta: overprint: true en un ColorValue hace que todo lo que se pinta con él (texto, filetes, cajas, fondos) se imprima encima de lo que tiene debajo en lugar de calarlo. Un color de cuatricromía se escribe tal como se separa, con un estado gráfico de sobreimpresión; un color plano sobreimprime en la plancha de su tinta, aunque esa misma tinta en otro color cale. Un negro al 100 % K que sobreimprime conserva el tratamiento del negro: las masas grandes siguen saliendo en negro enriquecido (black.richBlack). Un PDF RGB y la pantalla lo ignoran. Ponlo en la entrada de la paleta para que sobreimprima todo color enlazado a ella, también sus tintes; un color enlazado toma el ajuste de la entrada y no tiene uno propio. La paleta de una parte o de una sección lo conserva: el texto en el color de la parte también sobreimprime.
colorPalette: [
{ id: 'title', name: 'Título', value: { hex: '#c00020', model: 'cmyk', cmyk: { c: 0, m: 100, y: 80, k: 10 }, overprint: true } },
],Una salida para imprenta reconoce un color por el hex que pinta la maquetación, así que un color que sobreimprime nunca comparte hex con uno que cala. Cuando coinciden, el que sobreimprime se desplaza un paso (1/255 en un canal), como hacen los colores planos; el color de una parte para una entrada que sobreimprime se aparta del mismo modo de cualquier color del libro que cale. Un color que sobreimprime y no deposita tinta (el blanco del papel, una tinta al 0 %) desaparece en imprenta: la comprobación previa lo marca como crítico (overprintWhite). Una salida con más colores distintos que códigos disponibles (unos 25 millones) cala el resto y avisa (overprintsExhausted). En el Sandbox, lo activa el interruptor «Sobreimprimir en imprenta» del selector de color.
#Preflight
interface PrintPreflightConfig {
enabled?: boolean;
minImageResolution?: number; // ppp al tamaño impreso.
criticalImageResolution?: number;
minRuleWidth?: Dimension;
smallTextSize?: Dimension;
safeZone?: Dimension;
bleedSnap?: Dimension;
checkFonts?: boolean;
}| Propiedad | Tipo | Por defecto | Descripción |
|---|---|---|---|
enabled | boolean | true | Ejecuta las comprobaciones. |
minImageResolution | number | 300 | Un mapa de bits colocado que, a su tamaño impreso y con el recorte incluido, quede por debajo de esta cantidad de píxeles por pulgada recibe un aviso: figuras, imágenes de celdas de tabla, imágenes de diseño, viñetas de cómic. Un mapa de bits sin resolución propia se imprime a su tamaño natural a page.dpi, así que en una página maquetada a 150 dpi todas esas imágenes se imprimen a 150 ppp; uno con resolución propia (bitmap.resolution, layout.bitmapResolution) se imprime a su tamaño natural a esa resolución. |
criticalImageResolution | number | 150 | Por debajo de este valor, el aviso es crítico. Nunca puede superar minImageResolution. |
minRuleWidth | Dimension | 0.25pt | Filetes, bordes, filetes entre columnas, filetes de tabla y bordes de viñeta de cómic más finos que este valor. |
smallTextSize | Dimension | 9pt | Texto con un cuerpo inferior a este valor y compuesto en más de una tinta (un color de cuatricromía, negro enriquecido): se emborrona cuando se desplazan las planchas. El texto negro, solo en K, nunca cuenta. |
safeZone | Dimension | 5mm | Texto situado a menos de esta distancia del corte, donde la guillotina puede cortarlo. |
bleedSnap | Dimension | 3mm | Una caja o una imagen que se detiene a esta distancia del corte sin llegar al sangrado: llévala a sangre o apártala del corte. |
checkFonts | boolean | true | Avisa de las fuentes que no incrusta un PDF colocado (el Sandbox revisa cada original de imprenta con inspectPrintMaster). Postext incrusta todas las fuentes con las que compone. |
preflightDocument(doc, options) ejecuta las comprobaciones sobre un documento maquetado y devuelve una lista de incidencias, cada una con un kind, una severity ('critical', 'warning' o 'info'), el pageIndex absoluto en el libro, el rect afectado (en píxeles de página) y, cuando el elemento lo tiene, su rango en el texto de origen. Los tipos son lowImageResolution, declaredPixelsMismatch, rgbImage, thinRule, smallProcessText, inkLimit, safeZone y nearTrim. Sin un transform, un color neutro cuenta como una tinta y cualquier otro como tres, y no se comprueba la cobertura; con él, los recuentos y la cobertura son exactos. La resolución de una imagen se calcula a partir de los píxeles que declara su recurso o, cuando imageSize(fileId) los proporciona (bitmapInfo sobre los bytes, o la imagen decodificada), de los del propio archivo: una declaración que difiere del archivo en más de un píxel se notifica una vez como declaredPixelsMismatch, con nivel de aviso cuando declara más píxeles de los que tiene el archivo. placedImageResolutions(doc, { resources, imageSize }) enumera todos los mapas de bits colocados con su resolución efectiva en ppp, esté activada o no la verificación previa. Los rótulos de una figura cuentan como texto para smallProcessText, inkLimit y safeZone.
import { bitmapInfo, outputTransform, parseIccProfile, preflightDocument, resolvePrintConfig } from 'postext';
import { inspectPrintMaster } from 'postext-pdf';
const print = resolvePrintConfig(config.print);
const transform = outputTransform(parseIccProfile(fogra51Bytes), { intent: print.renderingIntent });
const issues = preflightDocument(doc, {
print,
transform,
resources, // tamaños en píxeles de los mapas de bits
imageSize: (fileId) => bitmapInfo(bytesOf(fileId)), // los píxeles reales de los archivos
imageColor: (fileId) => colourOf(fileId), // 'rgb' | 'cmyk' | 'gray', según el archivo
});
if (issues.some((i) => i.severity === 'critical')) process.exit(1);
const master = await inspectPrintMaster(masterBytes);
// => { nonEmbeddedFonts: ['Helvetica'], rgb: true, transparency: false }#Implementación de referencia
El componente PdfViewport del Sandbox (packages/postext-sandbox/src/viewport/pdf/PdfViewport.tsx) une las piezas anteriores en una vista previa en vivo con botones para regenerar, descargar e imprimir, y es un buen punto de partida para cualquier integración de PDF en el navegador. Construye el VDT a través del worker de composición compartido (consulta Ejecutar la composición en un Web Worker) para que pulsar Regenerar no congele la interfaz mientras se compone el libro: el hilo principal solo se encarga de renderToPdf (que ya es rápido una vez que existe el VDT).