Pular para o conteúdo principal

Capítulo 3.18 · Parte II · O ofício

Uso programático: arquivos PDF

O postext-pdf a partir do código: instalação, a API, provedores de fontes no navegador e no Node, fontes CJK, bytes de recursos, texto vertical, workers e arquivos prontos para impressão

Atualizado 2026-11-1031 minNo capítulo 3 Configuraçãoenescadefritptzhjaar

Em poucas palavras

Esta página é para quem escreve código e quer um arquivo PDF. Mostra como instalar o pacote de PDF e transformar um livro diagramado em arquivo com poucas linhas. O pacote precisa dos arquivos das fontes; por isso, a página explica como entregá-los a ele, num navegador ou num servidor. Trata das fontes para chinês, japonês e coreano, das imagens, do texto escrito de cima para baixo e dos links. Termina com um exemplo completo e com arquivos prontos para a gráfica.

#Geração de PDF

A saída em PDF fica em um pacote separado, postext-pdf, para que integrações apenas web não paguem o custo de pdf-lib e @pdf-lib/fontkit. O renderizador de PDF não mede o texto de novo: consome exatamente o mesmo VDTDocument que você passaria a renderToCanvas ou renderToHtml e converte as coordenadas em pixels para pontos de PDF. Por isso as três saídas sempre coincidem nas quebras de linha, nas alturas das colunas e na posição dos recursos.

No navegador, construa o VDT pelo Web Worker. renderToPdf em si é rápido depois que o VDT existe; a parte cara é o pipeline de layout que o produziu. Executar esse pipeline no worker mantém a interface responsiva e permite que uma exportação de PDF reaproveite o mesmo cache de medição que a visualização ao vivo já aqueceu. Veja Conduzir a exportação de PDF a partir do worker para o fluxo recomendado. Os exemplos na thread principal abaixo são a referência do que os argumentos significam; em código de interface, construa primeiro o VDT no worker e chame diretamente apenas renderToPdf.

#Instalação

npm install postext postext-pdf

postext é uma peer dependency de postext-pdf. Cada versão de postext-pdf precisa do postext com que foi lançada, ou de um posterior da mesma versão major (o intervalo de peer é um intervalo com circunflexo sobre aquela versão: ^1.5.0 para a 1.5.0), porque importa funções que o postext acrescentou naquela versão. Atualize os dois juntos e, em uma CDN, fixe os dois na mesma versão.

#API pública

O pacote expõe um único ponto de entrada e alguns tipos:

  • renderToPdf(doc, options): Promise<Uint8Array>: recebe um VDTDocument (ou os capítulos de um livro como uma lista deles) e devolve os bytes brutos do PDF.
  • PdfFontProvider: a assinatura de callback (family, weight, style, request?) => Promise<Uint8Array | Uint8Array[]> que renderToPdf usa para pedir os bytes de uma fonte quando precisa incorporar uma nova combinação de família/peso/estilo. request.codePoints contém os caracteres que as páginas compõem naquela variante; a resposta é um arquivo, ou vários que juntos formam a variante (veja Fontes chinesas, japonesas e coreanas).
  • declaredFontFile(bytes, { unicodeRange?, order? }): PdfFontFile: um arquivo de uma variante que diz como a página o declarou: o unicode-range da regra @font-face dele e o lugar dela na ordem de declaração. Um PdfFontFile é um Uint8Array com essas duas propriedades opcionais (veja Fontes chinesas, japonesas e coreanas). Desde o postext-pdf 1.30.
  • RenderToPdfOptions: { fontProvider, forms?, resourceBytes?, previewBytes?, outlines?, accessible?, colorSpace?, pageNegative?, characterGrid?, baselineGrid?, onProgress?, onWarning?, rasterizeSvg?, harfbuzzWasm?, print?, outputProfile?, profileBaseUrl?, date? }. forms define como os campos de formulário escrevem os números (moeda, o lado em que ela fica, separadores) e a fonte em que mostram os valores (font; veja Campos de formulário). outlines, accessible e colorSpace assumem o pdfGeneration do documento quando omitidos (veja Geração de PDF (configuração)). resourceBytes é descrito em Bytes de recursos e matrizes de impressão; onWarning, em Quais variantes são pedidas ao provedor e em Avisos no documento. characterGrid: true imprime a grade que cjk.grid.show desenha na tela e que, de outro modo, o PDF deixa de fora (veja Grade de caracteres). harfbuzzWasm diz de onde carregar o harfbuzz.wasm do HarfBuzz (uma URL, relativa à página, ou os bytes do arquivo) para um documento com texto da direita para a esquerda ou de letras ligadas; se omitido, usa a cópia ao lado do módulo do postext-pdf e, depois, a mesma versão do harfbuzzjs no jsDelivr e no esm.sh. print recebe as configurações de produção gráfica (padrão PDF/X, perfil de saída, preto, preflight) e, se omitido, assume o print do documento; com um padrão PDF/X, ou com colorSpace: 'cmyk', cada cor passa pela separação de cores com o perfil ICC de saída, cujos bytes outputProfile fornece (senão, ele é baixado de profileBaseUrl, por padrão a cópia da pasta icc/ do postext na CDN do npm). date (um Date, um tempo em milissegundos ou uma data escrita, como o mtime de createBundle) é a data de criação e de modificação do arquivo e, em um PDF/X, as datas do pacote XMP e a origem do identificador do documento: o mesmo documento, gerado duas vezes com um mesmo date, dá os mesmos bytes. Se omitido, o arquivo leva a hora da chamada. Uma data inválida lança um erro.
  • PdfWarning: um problema não fatal informado por onWarning; distinga pelo kind: 'fontFallback' (PdfFontFallbackWarning), uma variante composta em outro corte da mesma família; 'missingGlyph' (PdfMissingGlyphWarning), caracteres para os quais nenhum arquivo de uma variante tem glifo; 'variableFontDefaultInstance' (PdfVariableFontWarning), uma fonte variável pedida em um peso diferente da instância padrão; 'cffEmbeddedWhole' (PdfCffEmbeddedWholeWarning), uma fonte CFF de mais de 2 MB incorporada inteira; 'complexShapingUnavailable' (PdfComplexShapingWarning), texto da direita para a esquerda ou de letras ligadas desenhado sem o HarfBuzz, que não pôde ser carregado (reason lista onde ele foi procurado), de modo que os sinais do árabe ficam mal posicionados; 'outputProfileUnavailable' (PdfPrintWarning), uma renderização em CMYK cujo perfil de saída não pôde ser carregado, convertida com a fórmula simples; 'pageNegativeIgnored' (PdfPrintWarning), a página em negativo deixada de fora de um arquivo PDF/X-1a; 'spotTintsExhausted' (PdfPrintWarning), um render que ficou sem códigos para retículas distintas de cores especiais (cerca de 25 milhões) e imprimiu o resto em quadricromia; 'spotInkRenamed' (PdfPrintWarning), uma tinta cuja chapa é escrita com outro nome (veja Cores especiais); 'imageProfileUnavailable' (PdfPrintWarning), o perfil atribuído às imagens RGB não pôde ser carregado e foram usados os perfis delas; 'pictureOriginalUnreadable' (PdfPrintWarning), um original TIFF ou Photoshop que não pôde ser decodificado, impresso a partir da prévia (previewBytes) ou como marcador; 'plateMixesApproximated' e 'artworkOffPlates' (PdfPrintWarning), um trabalho em poucas chapas (print.plates) que ficou sem códigos e compôs as cores restantes como a mistura já codificada mais próxima, ou que inseriu uma página PDF ou uma imagem que não conseguiu decodificar com as suas próprias tintas; ou 'missingImage', uma imagem sem bytes desenhada como espaço reservado (informado apenas a um onWarning que você passe; sem ele, os avisos de fontes vão para console.warn).
  • inspectPrintMaster(bytes): Promise<PrintMasterReport>: lê a primeira página de uma matriz de impressão em PDF e informa as fontes que ela usa sem incorporá-las (nonEmbeddedFonts), se ela pinta em RGB (rgb) e se usa transparência (transparency), para o preflight.
  • inspectPrintPdf(bytes): Promise<PrintPdfReport>: lê de volta um PDF pronto como faria o preflight de uma gráfica, todas as páginas: a versão e o número de páginas, a identificação PDF/X e a condição de saída (e se o perfil está incorporado), o formato final e a menor sangria, as páginas com outro formato final, sem TrimBox ou com uma caixa de página que não tem quatro números (malformedBoxPages, lidas como se ela faltasse), as fontes (fonts: nome, incorporada ou não, tipo; uma fonte usada incorporada e não incorporada aparece uma vez de cada forma), em que ele pinta (CMYK, cinza, cores especiais pelo nome, registro, e RGB separado em deviceRgb, sem perfil, e iccRgb, com perfil, cada um em pintura vector ou em images), transparências, sobreimpressão, anotações, um formulário interativo e se está marcado. Além das páginas, lê as aparências das anotações, os campos e os recursos padrão do formulário, os padrões de preenchimento (patterns), os glifos Type 3 e as imagens embutidas no conteúdo. Lê o que o arquivo diz, não o que a configuração pediu, e não lê a resolução das imagens, a tinta total, os fios finos demais nem o trapping. Percorre as páginas como inspectPrintMaster, que também relata RGB em degradês, padrões de preenchimento e glifos Type 3.
  • decompressWoff2(bytes): Uint8Array: função auxiliar que converte um arquivo WOFF2 em bytes TTF, o formato que pdf-lib consegue incorporar diretamente.
  • createPdfWorker(options?), de postext-pdf/worker: a mesma renderização em um Web Worker; veja Renderizar o PDF em um worker.

#Exemplo mínimo

import { buildDocument } from 'postext';
import { renderToPdf } from 'postext-pdf';
 
const vdt = buildDocument(
  { markdown: '# Chapter One\n\nThe story begins here…' },
  {
    page: { sizePreset: '17x24' },
    layout: { layoutType: 'double' },
    bodyText: { fontFamily: 'EB Garamond', fontSize: { value: 9, unit: 'pt' } }, // 9 pt substitui o padrão de 8 pt
  },
);
 
const pdfBytes = await renderToPdf(vdt, {
  fontProvider: async (family, weight, style) => {
    // Devolve os bytes TTF desta família/peso/estilo.
    // Veja a seção "Provedor de fontes" abaixo para uma implementação real.
    const res = await fetch(`/fonts/${family}-${weight}${style === 'italic' ? 'i' : ''}.ttf`);
    return new Uint8Array(await res.arrayBuffer());
  },
});
 
// `pdfBytes` é um Uint8Array: salve, baixe ou transmita por streaming.
const blob = new Blob([pdfBytes], { type: 'application/pdf' });
const url = URL.createObjectURL(blob);
window.open(url);

#Por que um provedor de fontes?

pdf-lib incorpora arquivos de fonte reais ao PDF: as fontes instaladas no navegador não estão disponíveis na hora da renderização, e uma fonte que você carregou só para medir na tela não basta, sozinha, para produzir um PDF autossuficiente. renderToPdf percorre as páginas em busca de cada variante que elas pintam (uma por combinação family|weight|style; veja Quais variantes são pedidas ao provedor) e chama o seu provedor uma vez por combinação única. O provedor devolve um Uint8Array com bytes TTF ou OTF, ou uma lista deles para uma variante servida em vários arquivos (veja Fontes chinesas, japonesas e coreanas); pdf-lib gera subconjuntos dos contornos TrueType e incorpora inteiros os arquivos CFF (.otf). Uma variante CFF é declarada como tal, como uma fonte CIDFontType0 com o programa CFF em FontFile3 (CIDFontType0C), que o pdffonts lista como CID Type 0C e que é o que o preflight de impressão espera. Uma variante CFF com chaves CID (Source Han, os arquivos .otf da Noto CJK) mantém a declaração TrueType, porque a numeração dos glifos dela não coincide com a usada pelo texto; para impressão, use as versões TrueType dessas famílias. Variantes às quais o provedor responde com o mesmo arquivo, como um corte regular que substitui o negrito que falta a uma família, compartilham uma única fonte incorporada. Uma variante com que nenhuma página acaba desenhando, como a do texto de uma figura SVG quando a figura é desenhada como imagem, fica fora do arquivo.

Use fontes estáticas por peso, não uma única fonte variável. O Google Fonts muitas vezes serve um único WOFF2 variável por família, cobrindo todo o eixo de pesos. pdf-lib só consegue incorporar a instância padrão de um arquivo variável; por isso, um parágrafo em negrito sairia com peso regular. O Fontsource publica arquivos WOFF2 estáticos por peso, que resolvem isso de forma limpa; é o padrão que o Sandbox usa. Um arquivo variável pedido em um peso diferente da instância padrão é informado com um aviso variableFontDefaultInstance.

Cada palavra do texto cai onde a diagramação a colocou. Em parágrafos, itens de lista, citações, boxes e outros textos corridos, cada palavra começa na posição que o VDT mediu, de modo que uma diferença entre as larguras do navegador e as da fonte incorporada nunca se acumula ao longo de uma linha. Uma linha sem formatação em linha é pintada como um único objeto de texto que move a pena entre as palavras; linhas justificadas, centralizadas e com formatação são pintadas palavra por palavra. Um caractere para o qual a fonte não tem glifo, que o navegador mediu em outra fonte e que o PDF pinta como a caixa de glifo ausente da fonte, não desloca nenhuma das palavras seguintes e é informado uma vez por variante como aviso missingGlyph. Um espaço que a fonte não tem, como o espaço estreito sem quebra ou o espaço de algarismo, assume a largura que o navegador lhe deu, e caracteres invisíveis como o word joiner e o espaço de largura zero não são desenhados. Um hífen sem quebra (U+2011) que a fonte não tem é desenhado com o hífen da fonte (U+2010), ou com o hífen-menos quando ela também não tem hífen, como o navegador o mostra; Open Sans e Outfit, entre outras, não têm nenhum dos dois. Nenhum desses casos conta como glifo ausente. Há duas exceções. Uma linha com letras da direita para a esquerda continua sendo pintada como um único trecho (veja Idiomas e escritas). O texto posicionado por um design (cabeços e rodapés, aberturas, títulos de boxes e outros elementos de design) é composto com as larguras da própria fonte incorporada, de modo que ali um glifo que falta à fonte ainda desloca o resto da linha.

#Quais variantes são pedidas ao provedor

renderToPdf percorre as páginas do mesmo jeito que as pinta e pede ao provedor apenas as variantes que elas desenham:

  • a variante regular de um bloco que compõe qualquer linha, e a negrito, itálica ou negrito-itálica de cada trecho efetivamente composto assim;
  • trechos de chips, marcadores de lista e o texto dos espaços de design (cabeços, fólios, faixas de abertura e de parte);
  • o texto de legenda, de nota e de células de tabela de cada recurso;
  • as variantes que o <text> de uma figura SVG indica, quando a figura é incorporada. Uma família que o provedor não consegue fornecer de jeito nenhum passa para a família seguinte da lista font-family do SVG.

Assim, uma família de títulos que nunca é composta em itálico nunca tem o itálico pedido, e uma figura sem nota nunca precisa das variantes de nota.

Quando o provedor recusa uma variante, a renderização continua. Outra variante da mesma família é incorporada no lugar e um PdfWarning é informado. A substituta é a primeira variante que carregar, testando os nove pesos padrão (100 a 900) na ordem que a correspondência de fontes do CSS usa, que também é a variante que o navegador mostra na visualização:

  1. primeiro o mesmo estilo. Para um peso de 400 a 500, vêm primeiro os pesos até 500, depois os mais leves, do mais próximo para baixo, depois os mais pesados, de 600 para cima. Para um peso abaixo de 400, vêm primeiro os pesos mais leves, do mais próximo para baixo, depois os mais pesados. Para um peso acima de 500, vêm primeiro os pesos mais pesados, depois os mais leves;
  2. depois o outro estilo, itálico para o redondo e redondo para o itálico, no peso pedido e nos outros pesos, na mesma ordem.

Por isso, uma família sem itálicos compõe em redondo os trechos em itálico, uma família que só traz 400 e 700 toma um 600 como 700, e uma família com um único corte compõe tudo nele. O provedor recebe um pedido de variante por vez, nessa ordem, e nunca duas vezes para a mesma variante, de modo que uma variante que nada usa nunca é incorporada. Uma família que o provedor não consegue servir de jeito nenhum recebe pedidos para cada uma dessas 18 variantes antes de a renderização falhar.

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);
  },
});

Sem onWarning, a mensagem vai para console.warn. O texto mantém as posições, que vêm do VDT e foram medidas com as variantes que o navegador tinha; por isso, uma substituta com larguras diferentes pode parecer apertada ou frouxa. Forneça a variante verdadeira para corrigir isso. Uma renderização só falha (postext-pdf: failed to load font(s): …) quando o provedor não consegue fornecer nenhuma variante de uma família em um peso padrão, redonda ou itálica.

#Provedor de fontes no navegador (Fontsource + WOFF2)

O Sandbox traz createPdfFontProvider() (packages/postext-sandbox/src/viewport/pdf/pdfFontProvider.ts), que você pode copiar para qualquer app de navegador. O essencial:

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}`);
      // O pdf-lib precisa de bytes TTF, então descompactamos o invólucro WOFF2 no cliente.
      return decompressWoff2(new Uint8Array(await res.arrayBuffer()));
    })();
 
    bytesCache.set(key, promise);
    return promise;
  };
}

Uma versão de produção também deveria:

  • Consultar os pesos disponíveis (via https://api.fontsource.org/v1/fonts/{id}) e ajustar o peso pedido ao mais próximo que a família realmente oferece, para que um pedido de weight: 600 em uma família que só tem {400, 700} ainda funcione.
  • Recorrer do itálico ao normal quando uma família não tem corte itálico para o peso pedido, em vez de fazer falhar a renderização inteira.
  • Reaproveitar o cache entre renderizações (mantenha bytesCache no escopo do módulo, não por chamada), para que gerar de novo o PDF depois de uma mudança de configuração saia praticamente de graça.

#Fontes chinesas, japonesas e coreanas

Uma fonte CJK não vem em um único arquivo pequeno. O Fontsource distribui a Noto Serif SC em cerca de cem arquivos por peso, cada um com uma parte dos caracteres e declarado na folha de estilo da família com o respectivo unicode-range (@fontsource/noto-serif-sc/400.css); o navegador baixa os arquivos que o texto de uma página toca. O arquivo latin que o provedor acima busca não tem nenhum caractere Han, e os subconjuntos nomeados estão incompletos: o chinese-simplified da Noto Serif SC não tem 釵, e o chinese-traditional da Noto Serif TC não tem nenhuma das marcas de largura total (),!?:;.

Por isso, um provedor pode responder a uma variante com vários arquivos. renderToPdf passa a ele os caracteres que as páginas compõem naquela variante (request.codePoints), reunidos de todos os capítulos antes de qualquer coisa ser desenhada, e o provedor devolve os arquivos que os contêm, na ordem em que o navegador os consulta. Cada arquivo é incorporado como um subconjunto próprio, e cada caractere é desenhado a partir do primeiro arquivo que tiver um glifo para ele: um capítulo que toca 60 fatias incorpora 60 subconjuntos pequenos. Uma variante pedida de novo, para o texto de uma figura SVG, por exemplo, só é pedida para os caracteres que os arquivos dela não têm. Um provedor que devolve um único Uint8Array funciona como antes. O provedor do Sandbox lê a folha de estilo do Fontsource do peso e do estilo e busca os arquivos cujos intervalos contêm o texto; o núcleo dele:

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) => {
  // Onde os intervalos se sobrepõem, o navegador tenta primeiro a última regra.
  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()))));
};

Uma família latina passa pelo mesmo código: um texto em inglês recebe só o arquivo latin, um texto em tcheco recebe latin e latin-ext.

Um navegador não fica com o primeiro arquivo que tem o glifo. Ele compõe cada caractere com o arquivo declarado por último entre aqueles cujo unicode-range o contém, e os arquivos de uma família se sobrepõem: o Fontsource repete as letras ASCII da Noto Serif JP no arquivo latin e nas fatias numeradas. Entre dois caracteres compostos com dois arquivos não há kerning; por isso, é o arquivo que decide a largura: o Chrome 154 compõe Shift_JIS com 4,25 em de largura quando as fatias são declaradas depois de latin, e o arquivo latin sozinho, que aplica kerning a t_ e a _J, o compõe com 4,32 em. Desde o postext-pdf 1.30, um provedor pode dizer como a página declarou cada arquivo: declaredFontFile(bytes, { unicodeRange, order }) devolve os mesmos bytes com o unicode-range da regra do arquivo, como o CSS o escreve, e o lugar dessa regra entre as da variante, um número qualquer que cresce com a ordem de declaração (o maior é o declarado por último).

import { declaredFontFile } from 'postext-pdf';
 
declaredFontFile(bytes, { unicodeRange: 'U+0000-00FF,U+0131,U+0152-0153', order: 0 });

Num documento com shaping no próprio idioma (bodyText.shapingLanguage: 'document', o padrão), quando os arquivos de uma variante trazem os intervalos, cada caractere é desenhado a partir do arquivo declarado por último cujo intervalo o contém e que tem um glifo para ele, como um navegador escolhe entre as regras @font-face, e uma letra e os sinais combinantes dela ficam num mesmo arquivo. Um caractere que nenhum intervalo contém é desenhado a partir do primeiro arquivo que tiver um glifo. Os arquivos sem esses dados, e todos os de um documento com 'host', são lidos na ordem dada, como antes; por isso, um provedor que descreve os arquivos continua pondo primeiro o declarado por último. Uma variante descrita assim é pedida de novo para todos os caracteres para os quais ainda não tinha sido pedida, porque um arquivo declarado depois pode tê-los. O provedor do Sandbox descreve os arquivos dele.

Os caracteres para os quais nenhum arquivo da variante tem glifo são desenhados com o glifo .notdef da fonte (uma caixa vazia na maioria das fontes), e renderToPdf os informa uma vez por variante depois de desenhar as páginas:

// { kind: 'missingGlyph', family: 'Noto Serif TC', weight: 400, style: 'normal',
//   characters: [',', '!', '?'], message: '…' }

O Sandbox lista esses avisos, e os dois descritos abaixo, no painel Verificações depois de cada PDF que gera. Quando o livro, os ajustes ou os recursos dele mudam, eles passam a ser marcados como vindos de um PDF anterior até que o próximo os substitua; abrir outro livro os apaga.

  • O negrito precisa de um arquivo estático por peso. O Fontsource serve cada peso da Noto Serif SC e TC como arquivos estáticos separados; por isso, o negrito funciona no Sandbox. Os arquivos do Google Fonts (NotoSerifSC[wght].ttf, 25 MB) são fontes variáveis: o pdf-lib incorpora a instância padrão delas, de modo que uma variante 700 sai impressa em 400, e renderToPdf informa isso como variableFontDefaultInstance. Para um pacote, gere uma instância estática por peso com o fontTools (fonttools varLib.instancer NotoSerifSC[wght].ttf wght=700) e reduza-a aos caracteres do livro com pyftsubset.
  • Use as versões TrueType. A Source Han Serif e os arquivos .otf da Noto Serif CJK têm contornos CFF, que o postext-pdf incorpora inteiros, de 8 a 25 MB por peso; uma fonte CFF com mais de 2 MB é informada como cffEmbeddedWhole. As versões TrueType (Google Fonts, Fontsource) são reduzidas aos glifos usados. Para japonês, a Noto Serif JP e a Noto Sans JP (Google Fonts, ou as fatias numeradas do Fontsource), a Shippori Mincho, a Zen Old Mincho e a BIZ UDMincho vêm em TrueType; a Source Han Serif JP e os arquivos .otf JP da Noto Serif CJK são CFF.
  • As formas japonesas de uma fonte pan-CJK. Um mesmo ponto de código de Han, de pontuação ou de aspas pode ser desenhado de um jeito no Japão e de outro na China, e uma fonte pan-CJK (Source Han, Noto CJK) contém os dois. O PDF faz o shaping de um documento japonês (locale: 'ja'), e de um isolamento em japonês (:ltr[…]{lang=ja}) em qualquer documento, com o sistema de idioma OpenType JAN , de modo que o recurso locl da fonte imprime as formas japonesas que o canvas e o HTML imprimem por meio de lang. Um isolamento em outro idioma dentro de um livro japonês passa pelo shaping com as formas daquele idioma (as formas padrão da fonte, no caso do chinês com 'host') e é marcado como um Span com o /Lang dele. Com bodyText.shapingLanguage: 'document', o padrão desde o postext 1.30, todo documento e todo isolamento passa pelo shaping no próprio idioma (ZHS para o chinês simplificado), como a diagramação o mediu; com 'host', documentos em chinês e em outros idiomas passam pelo shaping com as formas padrão da fonte, como antes. Uma fonte feita para o japonês, como a Noto Serif JP, tem formas padrão japonesas; mesmo assim, ela compõe as “ ” do texto japonês nas formas JAN .

Um caractere que falta em uma família não é tomado de outra: a Noto Serif TC não empresta da Noto Serif SC. Resolva a cobertura quando gerar os arquivos de fonte; a vitrine 红楼梦 copia da fonte SC os glifos que faltam aos subconjuntos TC dela.

#Provedor de fontes no servidor (Node, arquivos locais)

No Node você pode pular totalmente a etapa do WOFF2 e ler arquivos TTF/OTF do disco:

import { readFile } from 'node:fs/promises';
import { join } from 'node:path';
import type { PdfFontProvider } from 'postext-pdf';
 
const FONT_DIR = '/path/to/fonts';
 
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 e matrizes de impressão

resourceBytes(fileId) devolve os bytes brutos de uma imagem, e o renderizador identifica o formato:

  • PNG, JPEG, GIF e WebP são incorporados como imagens;
  • a marcação SVG é desenhada como caminhos vetoriais, com o text composto como texto real nas fontes incorporadas do documento, ou rasterizada a 600 dpi no navegador quando usa recursos fora do subconjunto vetorial. Um <style> que contém só regras @font-face (variantes que o autor incorporou) é ignorado e mantém a figura vetorial (desde o postext-pdf 1.25); qualquer outra folha de estilo a torna uma rasterização, feita com as variantes que o texto dela indica incorporadas a partir de fontProvider (a menos que diagramStyle.inlineFonts ou o svg.inlineFonts do recurso seja false);
  • os TIFF e os documentos do Photoshop (PSD, PSB) são impressos a partir dos próprios pixels: cinza, RGB ou CMYK, de 8 ou 16 bits, com o perfil ICC e a resolução que trazem. Um CMYK mantém as tintas como estão; o cinza e o RGB seguem print.imageColor. De um documento do Photoshop lê-se a imagem composta que ele salva com “Maximizar compatibilidade”; os TIFF com compressão JPEG não são lidos;
  • de um PDF, a primeira página é incorporada tal como está, como um form XObject.

Cada imagem é guardada no arquivo uma única vez, por mais vezes que seja desenhada. Um SVG desenhado como caminhos vetoriais vira um form XObject que todas as páginas pintam, de modo que uma moldura ou um logotipo no design de página de um documento de trinta páginas é escrito uma vez, não trinta; cada página a mais acrescenta algumas centenas de bytes. Até o postext-pdf 1.4, cada página levava a própria cópia dos caminhos.

Uma figura SVG pode indicar uma matriz de impressão em svg.pdfFileId: um PDF de uma página com a mesma figura, em geral o original do qual o SVG foi exportado. renderToPdf pede primeiro a resourceBytes o id da matriz. Ele incorpora essa página no lugar do SVG, com as fontes, os degradês e os espaços de cor intactos, em todo lugar onde o SVG é desenhado: como figura, como imagem de uma célula de tabela (TableCell.image), como imagem de design ou como ícone de boxe (também o marker dele). O VDT leva o id da matriz em cada um desses usos (svg.pdfFileId no recurso da figura, pdfFileId em uma imagem de célula e em um bloco de imagem de design), de modo que, em um livro, todos os capítulos recebem a matriz. Os renderizadores de canvas e HTML continuam desenhando o SVG. Os bytes do próprio SVG são usados no lugar em três casos: a matriz está faltando, não é um PDF ou a tinta única está ativada (diagramStyle.singleInk só recolore marcação SVG).

const resources: Resource[] = [{
  id: 'map', typeId: 'figure', kind: 'svg', createdAt: 0, updatedAt: 0,
  svg: { fileId: 'map.svg', width: 800, height: 600, pdfFileId: 'map.pdf' },
}];
const files = new Map([['map.svg', svgBytes], ['map.pdf', masterPdfBytes]]);
const pdf = await renderToPdf(buildDocument({ markdown, resources }, config), {
  fontProvider,
  resourceBytes: (fileId) => files.get(fileId),
});

Um hospedeiro também pode devolver os bytes da matriz para o id do próprio SVG, como faz bundleResourceBytes; as duas formas funcionam.

Um navegador não consegue mostrar um TIFF nem um documento do Photoshop, por isso um recurso de bitmap feito a partir de um deles guarda dois arquivos: bitmap.fileId é uma pré-visualização em PNG, que o canvas, o HTML e o EPUB mostram, e bitmap.printFileId (com printFormat: 'tiff' | 'psd') é o original. Um hospedeiro devolve os bytes do original para bitmap.fileId, como fazem bundleResourceBytes e o Sandbox, e o PDF é impresso a partir dele. Também passa a prévia, como previewBytes (bundlePreviewBytes em um pacote): um original que não pode ser decodificado é impresso a partir da prévia, com um aviso pictureOriginalUnreadable, e sem ela fica um marcador. decodePrintRaster(bytes) e rasterToRgba(raster) de postext leem o original e fazem a pré-visualização; o Sandbox a faz quando o arquivo é importado, e um pacote guarda o original como resources/<nome>.tif ou .psd ao lado da pré-visualização.

Um arquivo do Adobe Illustrator salvo com “Criar arquivo compatível com PDF” é um PDF e pode ser uma matriz de impressão como qualquer outro (.ai). As amostras dele são as suas próprias chapas: o preflight enumera as que a tabela de tintas renomeia, as que nenhuma cor do livro define e, em um trabalho com chapas próprias (print.plates), as que o trabalho não imprime, porque um arquivo inserido é impresso tal como está.

#Texto vertical no PDF

Uma página vertical (layout.writingMode: 'vertical-rl') é desenhada por meio de um referencial girado um quarto de volta, como o canvas a pinta, e o texto é composto coluna abaixo:

  • Os caracteres em pé são mostrados por meio de uma segunda fonte Type0 do mesmo arquivo incorporado: a mesma CIDFont, as mesmas larguras e o mesmo mapa ToUnicode, com Encoding /Identity-V (modo vertical). Uma sequência de caracteres é um único objeto de texto cujos glifos avançam sozinhos um eme coluna abaixo (DW2 [880 −1000]), de modo que os leitores de PDF selecionam e extraem uma coluna como uma única linha. Os glifos passam pelo shaping com os recursos OpenType vert e fwid, que dão as formas verticais a parênteses, aspas, vírgulas de enumeração do chinês continental, reticências e travessões; um caractere que já fica em pé como é mantém o glifo horizontal. Nada da fonte é incorporado duas vezes.
  • Palavras latinas e números longos correm de lado com a fonte horizontal; um número em uma célula fica em pé, comprimido até a largura de um eme quando é mais largo; uma marca para a qual a fonte não tem forma vertical é girada ou deslocada, como no canvas.
  • O tracking entre caracteres é escrito como números de TJ, que no modo vertical movem a pena coluna abaixo.
  • Cada linha vertical é marcada com um /ActualText com o texto dela, para que a cópia e a extração de texto a leiam como foi escrita. O pdftotext e o pdf.js leem as colunas de cima para baixo, da direita para a esquerda; o pdf.js começa uma nova linha em um número composto em uma célula.
  • Links, marcadores e destinos são mapeados sobre a folha: um link sobre uma linha vertical é um retângulo alto e estreito, e um marcador abre a página no topo da coluna do título correspondente.
  • Um PDF marcado declara o modo de escrita no elemento Document (o atributo de Layout WritingMode /TbRl, que todos os elementos herdam); a validação PDF/UA-1 (veraPDF) passa em um capítulo vertical.
  • Visualizadores: Acrobat, Preview, Chrome (PDFium), pdf.js e Poppler renderizam as fontes verticais. Um livro com encadernação à direita (page.binding) também pede aos visualizadores que mostrem as páginas duplas da direita para a esquerda (/Direction /R2L, /PageLayout /TwoPageRight); Acrobat e Foxit seguem isso, o Chrome não.

Um capítulo de 43 páginas composto em Noto Serif TC (os caracteres do livro, TrueType) tem cerca de 820 KB, a maior parte nos dois subconjuntos de fonte.

#Campos de formulário

Um chip com o atributo field é um campo de formulário preenchível (AcroForm). O chip é composto e pinta sua caixa como qualquer chip: o estilo dá a aparência e a largura mínima (minWidth), e as palavras dele são o valor inicial do campo. O PDF coloca um campo interativo sobre a caixa; um nome usado duas vezes é um só campo com dois widgets.

Quantidade :chip[ ]{style="field" field="pos.a.qty" kind="number"}
Preço :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)"}
Serviço :chip[ ]{style="box" field="pkg.a" kind="checkbox" on="1"}
Total do pedido :chip[ ]{style="field" field="order.total" format="currency" calc="sum(pos.a.total, product(pkg.a, 161.75))"}
Tamanho :chip[M]{style="field" field="size" kind="choice" options="S|M|L"}
  • kind: text (padrão), number, checkbox, choice (com options, separadas por |). Um chip com format ou calc e sem kind é um campo numérico.
  • on (uma caixa de seleção): o nome do estado marcado da caixa, que é o valor que os scripts dela leem quando ela está marcada. Com on="1", uma caixa marcada conta 1 em um cálculo, de modo que product(pkg.a, 161.75) soma um preço fixo quando ela é marcada. O padrão é Yes, que um cálculo conta como 0.
  • format: currency, decimal (duas casas decimais), integer. É escrito com AFNumber_Format e AFNumber_Keystroke do Acrobat, com os separadores do idioma do documento (1.234,56 em alemão e em português) a menos que RenderToPdfOptions.forms.separatorStyle diga outra coisa; a moeda é forms.currency (padrão €), antes do número a menos que forms.currencyBefore seja false. O valor inicial já é desenhado formatado.
  • calc: sum(…), product(…), min(…), max(…) ou avg(…). Os argumentos são outros campos pelo nome, números (com ponto decimal, 161.75) e cálculos aninhados: sum(pos.a.total, pos.b.total, product(pkg.a, 161.75)). Um cálculo só sobre campos é escrito como AFSimple_Calculate. Um com números ou cálculos aninhados vira um script de cálculo próprio e curto, que lê cada campo do mesmo jeito (AFMakeNumber do valor; o que não é número conta 0) e arredonda o resultado para seis casas decimais. Um campo calculado é somente leitura, e a ordem de cálculo leva em conta todos os campos que ele lê, inclusive os aninhados. Geram um aviso formField: um cálculo que lê um campo desconhecido (conta 0), um ciclo, um nome usado para dois tipos e uma caixa de seleção em um cálculo cujo valor on não é um número (conta sempre 0).
  • readonly, required, multiline e tooltip fazem o que o nome diz.

Um campo mostra o valor, e o que se digita nele, na fonte do seu chip (forms.font: 'chip', o padrão) ou em uma fonte do documento indicada por forms.font ({ family, weight?, style? }, pedida ao fontProvider como qualquer outra). Essa fonte é incorporada inteira, não como subconjunto, porque um subconjunto não teria os glifos do que for digitado depois; é incorporada uma só vez, por mais campos que a usem, nomeada nos recursos padrão do formulário (/DR) e na aparência padrão de cada campo (/DA), e os valores iniciais são desenhados com ela. Uma fonte inteira acrescenta o arquivo completo ao PDF (uma fonte de texto latina costuma ter de 50 a 300 KB, uma CJK vários MB), além do subconjunto usado pelo texto das páginas. O provedor pode responder com TrueType, OpenType ou WOFF2 (descompactado antes da incorporação). Os campos voltam à Helvetica, com um aviso formField, quando a fonte não pode ser incorporada inteira: a licença proíbe a incorporação (fsType da tabela OS/2 restrito ou só bitmap), o provedor a entrega em vários arquivos (uma fonte fatiada) ou o formato é WOFF ou uma coleção. Com forms.font: 'helvetica', usa-se a Helvetica sem incorporar nada. Alguns visualizadores (o Pré-Visualização do macOS, por exemplo) desenham o texto que está sendo digitado em uma fonte própria; o valor é o mesmo.

Acrobat, Foxit, pdf.js (Firefox) e a maioria dos visualizadores executam esses scripts. Um padrão de impressão (PDF/X) não admite campos interativos: nele os valores são pintados como texto, e o de um campo numérico do jeito que o formulário o mostra (formatado, alinhado ao fim da caixa dentro do paddingX do próprio estilo, na cor do chip).

O canvas pinta um campo numérico da mesma forma, então a prévia coincide com o PDF: passe para renderPageToCanvas (ou renderPage, renderToCanvas) a mesma opção forms que você passa para renderToPdf; nos dois, os separadores vêm por padrão do locale do documento (na falta dele, do idioma de hifenização). Uma única regra escreve os números em todo lugar, e o postext a exporta para outros geradores de saída: formNumberStyle(forms, lang) resolve as opções, formatFieldNumber(value, format, style) formata um valor (undefined para um texto que não é número) e numberFieldText(field, words, style) dá o que um campo numérico pintado mostra. A lista de exibição leva o campo no trecho do chip (inline.field, com o sizePx e o padPx da composição).

Um livro pode guardar essas opções na configuração: pdfGeneration.forms aceita os mesmos campos (currency, currencyBefore, separatorStyle, font). renderToPdf e o canvas tomam cada um primeiro da própria opção forms, depois do pdfGeneration.forms do primeiro documento e, por fim, dos valores padrão. Não muda a diagramação, só como os campos são escritos e pintados. No Sandbox é o grupo Campos de formulário da seção PDF.

pdfGeneration: {
  forms: { currency: 'USD', currencyBefore: true, separatorStyle: 0, font: { family: 'Lora', weight: 400 } },
}

Pelo esm.sh num navegador, importe https://esm.sh/postext-pdf?bundle. O build padrão do pdf-lib no esm.sh coloca as classes de anotação num módulo à parte, e o pdf-lib então recusa o widget de cada campo: o PDF mantém as caixas, mas perde formatos, cálculos e atributos, com um aviso formField por campo. ?bundle compila o pdf-lib num só módulo e deixa o postext de fora, compartilhado com a página. Um bundler (Vite, webpack, Next.js) e o Node não são afetados.

A exportação IDML grava os mesmos campos como campos de formulário do InDesign (veja Uso programático › Pacotes do InDesign).

As palavras de um link Markdown (veja Formato do documento › Links) viram anotações de link URI, uma por trecho de palavras com link em uma linha. Cada uma cobre a caixa da linha e não tem borda. Em uma renderização acessível, cada trecho é um elemento Link cujo /Contents é o texto do trecho. Só recebem link os destinos absolutos http:, https:, mailto:, tel: e ftp:, porque uma URL relativa não tem base dentro de um PDF. Os caracteres fora do ASCII imprimível são codificados com porcentagem. As citações :ref e as linhas do sumário mantêm os links dentro do documento.

#Exemplo completo no navegador: construir, renderizar, baixar

Juntando tudo: construir o VDT, renderizar em PDF e disparar o download a partir do 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: chame ensureConfigFontsLoaded(config) (ou equivalente) antes de buildDocument quando a sua configuração fizer referência a fontes web. A diagramação é medida com as métricas de fonte que o navegador tiver naquele momento para a família; se a fonte verdadeira ainda não chegou, o VDT é medido com uma substituta e o PDF não vai coincidir com a saída do canvas ou do HTML. O Sandbox faz isso explicitamente antes de cada renderização (veja packages/postext-sandbox/src/viewport/pdf/PdfViewport.tsx).

#Exemplo ao vivo: um PDF no navegador

O fluxo completo acima, rodando no navegador: o pen importa postext e postext-pdf de uma CDN, carrega as fontes web, constrói o documento, incorpora os cortes do Fontsource pelo provedor de fontes e entrega os bytes a um link que abre o arquivo em uma nova aba e a um link de download. O PDF resultante tem as mesmas quebras de linha que a saída do canvas e do HTML, fontes realmente incorporadas e marcadores de estrutura.

Postext · gerar um PDF no navegador
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;
}

Carrega um editor interativo de codepen.io. O exemplo importa a versão mais recente do postext de uma CDN.

#Renderizar o PDF em um worker

postext-pdf/worker tira renderToPdf da thread principal. O worker escreve o texto, as figuras vetoriais, a árvore de estrutura e o próprio arquivo. Duas tarefas precisam da página; por isso, o worker as pede à thread principal: buscar as fontes e rasterizar um SVG por meio de um <img>. Em um livro de centenas de páginas, a renderização leva segundos que, de outro modo, travariam a página; para poucas páginas, chamar renderToPdf diretamente é mais simples.

import { createPdfWorker } from 'postext-pdf/worker';
 
const pdfWorker = createPdfWorker();
const bytes = await pdfWorker.render(docs, {
  fontProvider,                                     // roda nesta thread
  resourceBytes: new Map([['map.svg', svgBytes]]),  // um Map; os seus buffers passam para o worker
  onProgress: ({ phase, pages, totalPages }) => showProgress(phase, pages, totalPages),
  onWarning: (w) => console.info(w.message),
});
pdfWorker.dispose();
  • render(docs, options) recebe um documento ou a lista de documentos de capítulos de um livro. Aceita as opções de renderToPdf, com duas diferenças. resourceBytes (e previewBytes) é um Map<string, Uint8Array> cujos buffers são transferidos; por isso, passe cópias dos bytes que você quer manter. rasterizeSvg, quando informado, roda na thread principal; por padrão, o Image e o canvas da própria página fazem o trabalho.
  • Um handle renderiza um documento por vez. dispose() encerra o worker e rejeita qualquer renderização ainda pendente com um AbortError (DOMException), que deve ser tratado como um cancelamento. Se o seu provedor responder com uma fonte ou uma imagem depois de dispose(), a resposta é descartada.
  • inspect(bytes) lê de volta um PDF pronto no worker (inspectPrintPdf) e se resolve com o relatório, ou com undefined quando os bytes não podem ser lidos como PDF. Os bytes são copiados, então os seus continuam utilizáveis. Nada é lido se você não o chamar.
  • createPdfWorker({ worker }) aceita um Worker criado por você, para ferramentas de build que controlam as URLs de workers. Esse worker precisa executar postext-pdf/worker/entry.

A partir de uma CDN. Por padrão, o script do worker é carregado da URL do próprio pacote (new URL('./pdf.worker.js', import.meta.url)). Uma página em outra origem pode não conseguir iniciá-lo: importado do esm.sh, createPdfWorker() lança Failed to construct 'Worker': Script at 'https://esm.sh/postext-pdf@…/pdf.worker.js' cannot be accessed from origin …. Em vez disso, inicie um worker de módulo da mesma origem que importe o ponto de entrada (se fixar uma versão, fixe a mesma nas duas URLs):

import { createPdfWorker } from 'https://esm.sh/postext-pdf/worker';
 
const entry = URL.createObjectURL(new Blob(
  ["import 'https://esm.sh/postext-pdf/worker/entry';"],
  { type: 'text/javascript' },
));
const pdfWorker = createPdfWorker({ worker: new Worker(entry, { type: 'module' }) });

O worker de layout de postext/worker não precisa dele: createLayoutWorker() inicia a própria entrada a partir do esm.sh sem nenhuma opção, e a partir de qualquer outro servidor com a opção url (veja Carregar o worker de um CDN).

#PDFs prontos para impressão

Para fluxos de produção gráfica, ajuste estas opções de configuração antes de renderizar:

  • page.cutLines.enabled: true: acrescenta a área de sangria e as marcas de corte ao redor do refile, e dá a cada página uma TrimBox e uma BleedBox. Veja Marcas de corte.
  • print: { standard: 'pdfx4', outputProfile: 'fogra51' } (ou 'pdfx1a'): um arquivo PDF/X com a condição de saída, a identificação e as caixas que uma gráfica confere; cada cor e cada imagem RGB separadas com o perfil ICC, o preto 100 % K sobreimpresso e as áreas pretas grandes em preto composto. Veja Produção gráfica (configuração).
  • colorSpace: 'cmyk' (ou pdfGeneration: { forceColorSpace: true, colorSpace: 'cmyk' }): a mesma separação, sem a identificação PDF/X (as marcas de corte ficam sempre na cor de registro). As matrizes de impressão em PDF são incorporadas como estão.
  • page.dpi: 300: os px por polegada da diagramação; um bitmap sem resolução própria é impresso com essa resolução no tamanho natural. O preflight informa as imagens abaixo de 300 ppi no tamanho impresso.
  • ColorValue.cmyk: uma cor definida em CMYK é impressa com os valores exatos.
  • { pageNegative: true } em RenderToPdfOptions: inverte a área de refile com um modo de mesclagem Difference (as marcas de corte não são invertidas). Útil em verificações de preflight de tipografia escura sobre fundo claro.

#Cores especiais

Uma cor especial (um Pantone, uma tinta corporativa, um verniz) é impressa na sua própria chapa. Uma cor com model: 'spot' leva a sua tinta em ColorValue.spot: name é o nome da chapa tal como a gráfica o conhece, cmyk é o aspeto da tinta a 100 % (o equivalente que o PDF dá a quem não tem a tinta), tint é a retícula em percentagem (100 por omissão) e overprint faz a tinta sobreimprimir o que está por baixo em vez de o vazar, como um verniz. hex é a sua representação no ecrã.

Um PDF CMYK ou PDF/X escreve cada tinta como um espaço de cor Separation com o seu nome, e cada cor dessa tinta é pintada na sua retícula: as cores com o mesmo name partilham chapa. Cabem assim os trabalhos habituais: duas cores (preto e uma especial), quadricromia com alguns elementos em especial e um verniz sobreimpresso em zonas escolhidas. Se diagramStyle.singleInk usar uma cor especial, os diagramas SVG são impressos em retículas dessa chapa. Num PDF RGB e no ecrã, a cor é pintada com o seu hex.

Cores especiais dentro de um SVG. Veja Como funciona a 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' } },

O preflight conta uma cor especial como uma só tinta, deixa-a fora do limite de cobertura e enumera as cores especiais do trabalho (spotInks), incluindo as que as imagens SVG nomeiam. Avisa quando uma tinta é definida duas vezes com valores diferentes (spotInkConflict; o PDF usa a primeira), quando um SVG nomeia uma tinta que nenhuma cor da paleta nem nenhuma entrada da tabela de tintas com cmyk define (spotInkUndefined; é impressa numa chapa própria, com o CMYK da cor do SVG como equivalente, uma chapa por nome), quando o PDF tem de escrever o nome de uma chapa de outra forma (spotInkName, veja abaixo) e quando dois nomes de chapa só diferem em maiúsculas ou espaços (spotInkSimilar: PANTONE 185 C e Pantone 185 C seriam duas chapas). preflightDocument sabe que tintas um SVG nomeia por svgInks(fileId), uma função que devolve os nomes que svgSpotInks(markup) encontra no arquivo; o painel Verificações do Sandbox e o postext check fornecem essa função.

Nomes de chapa. O nome é escrito tal como é digitado: os acentos, os símbolos e # chegam ao PDF em UTF-8 (Rojo Médica é /Rojo#20M#C3#A9dica), que é como o leem o Acrobat, um RIP e o preflight da gráfica. Um nome que uma chapa não aceita é escrito com outro: All, None, Cyan, Magenta, Yellow e Black, em maiúsculas ou minúsculas, recebem a palavra ink depois (All ink); os caracteres de controle são removidos, e um nome com mais de 127 bytes em UTF-8 é cortado entre dois caracteres e termina num hash curto, de modo que dois nomes longos que começam igual continuam a ser duas chapas. O spotInkName do preflight diz o motivo (problem: reserved, process, control ou tooLong) e o nome que o PDF escreve (written), e o render avisa de cada mudança por onWarning (spotInkRenamed). Para escolher o nome, dê à tinta um pdfName na tabela de tintas.

Uma tinta por cor. Um render de impressão reconhece uma cor pelo seu hex de ecrã, por isso duas cores que fixam os seus valores de impressão — duas tintas, ou uma tinta e uma cor definida em CMYK — não o podem partilhar. Se o partilharem, a segunda passa para o hex livre mais próximo, a um passo e invisível no ecrã, e cada uma sai na sua chapa. Uma cor de ecrã (model: 'hex') com o hex de uma cor especial é impressa como essa cor especial; ligue-a à entrada da paleta para o deixar explícito. A cor que se move também muda no ecrã, um passo (1/255) num só canal, o azul primeiro, em todas as saídas (canvas, HTML, EPUB e PDF RGB). Fica muito abaixo do que o olho distingue, e é o preço de um render de impressão que lê as tintas do hex pintado. A configuração guardada não muda.

A tabela de tintas

print.inks diz como as tintas do trabalho chegam à gráfica, seja qual for o nome que lhes dão as cores, os SVG e os arquivos importados. Uma tinta que não está na tabela é impressa tal como as suas cores a definem.

interface PrintInk {
  name: string;                    // A tinta tal como a nomeia spot.name ou um SVG.
  aliases?: string[];              // Outros nomes da mesma tinta: saem nesta chapa.
  pdfName?: string;                // O nome da chapa no PDF. Por omissão, name.
  output?: 'spot' | 'process';     // 'process' imprime a tinta em CMYK, com o seu equivalente.
  cmyk?: CmykPercent;              // O equivalente a 100 %, acima do das cores.
  overprint?: boolean;             // Acima do das cores.
}

Os nomes e os aliases são comparados sem distinguir maiúsculas nem espaços repetidos. Mudar o nome é uma linha, sejam quantas forem as cores que usam a tinta; um alias junta numa chapa os nomes que uma amostra do designer, um SVG (data-spot, icc-named-color) ou uma paleta anterior davam à mesma tinta; e output: 'process' imprime uma tinta em CMYK quando a máquina não tem unidade para ela, com todas as suas retículas.

No Sandbox, a tabela fica em Design › Exportação › Preparação para impressão › Tabela de tintas: um cartão por tinta com o Nome da tinta, os Apelidos, o Nome da chapa no PDF, Impressa como, o CMYK alternativo e a Sobreimpressão. Tintas usadas pelas cores lista as tintas das cores do livro que faltam na tabela, cada uma com um botão que a acrescenta.

print: {
  standard: 'pdfx4',
  inks: [
    { name: 'Azul corporativo', pdfName: 'PANTONE 286 C', aliases: ['Pantone 286C', 'Azul'] },
    { name: 'Varnish', output: 'process' },
  ],
},

Impressão a duas tintas

print.plates diz em que chapas o trabalho é impresso, e não se imprime em nenhuma outra: um livro em preto e uma cor especial, em duas cores especiais ou só em preto. As chapas de quadricromia chamam-se Cyan, Magenta, Yellow e Black; uma chapa de cor especial é nomeada como o PDF a nomeia, ou com um nome ou um alias da tabela de tintas.

interface PrintPlatesConfig {
  inks?: string[];                                // As chapas. Vazio: todas, como sempre.
  images?: string[];                              // As chapas das imagens: uma ou duas.
  curves?: Record<string, Array<[number, number]>>; // A curva de uma chapa de imagem: [tom, tinta] em percentagem.
}
  • Uma cor de uma tinta que o trabalho imprime, ou uma cor CMYK cujos canais ele imprime, sai tal como está.
  • Qualquer outra cor é projetada: é impressa com a mistura de uma ou duas chapas que, através do perfil de saída, mais se lhe assemelha. Uma mistura de duas tintas é um espaço de cor DeviceN no PDF, e um cinza fica só em Black. O preto composto é descartado, a não ser que o trabalho imprima as quatro tintas de quadricromia.
  • As imagens saem em monotom, numa chapa, ou em duotom, em duas: o tom de cada pixel (a sua luminosidade) passa pela curva de cada chapa. images é por omissão Black, ou a primeira chapa se o trabalho não imprimir preto. A curva de um monotom é uma reta; um duotom põe a primeira chapa nas sombras e a segunda nos meios-tons. curves substitui qualquer uma delas.
print: {
  standard: 'pdfx4',
  plates: {
    inks: ['Black', 'PANTONE 286 C'],
    images: ['Black', 'PANTONE 286 C'],
    curves: { 'PANTONE 286 C': [[0, 0], [50, 35], [100, 70]] },
  },
},

O preflight enumera as chapas do trabalho e cada cor que a projeção desloca. Uma cor especial ou uma cor CMYK que o trabalho não imprime é informação quando a sua mistura fica a menos de ΔE 6, e um aviso se fica mais longe ou enquanto o perfil de saída não foi carregado (offPlateInk, offPlateCmyk); uma cor de tela que fica a mais de ΔE 6 também é um aviso (offPlateColor). Uma chapa de cor especial que nenhuma cor nem nenhuma entrada da tabela de tintas define é um aviso: é impressa e simulada como preto. Num trabalho assim, o original de impressão de uma figura é posto de lado e o seu SVG é composto nas chapas; uma página PDF inserida, ou uma imagem que não pode ser decodificada, mantém as suas próprias tintas e o render avisa (artworkOffPlates). No Sandbox as chapas são escolhidas em Preparação para impressão → Chapas. As suas pré-visualizações e a pré-visualização de impressão mostram as cores como o livro as define, não como as chapas as imprimem: veja o PDF, onde Verificar para impressão lista as tintas que ele usa.

#Cor das imagens

Uma imagem é separada a partir das cores em que foi feita. print.imageColor diz como os seus pixels são lidos:

interface PrintImageColorConfig {
  embeddedProfile?: 'use' | 'ignore';                  // O perfil ICC da própria imagem. Por padrão, 'ignore'.
  assignedRgbProfile?: { name: string; fileId: string }; // Ler toda imagem RGB com este .icc.
  grayDotGain?: 'profile' | 'none' | number;           // Imagens em cinza, no preto. Por padrão, 'none'.
  cmykProfile?: 'convert' | 'keep';                    // Uma imagem CMYK de outra máquina. Por padrão, 'keep'.
}

Os valores padrão deixam as imagens como as versões anteriores as imprimiam: toda imagem RGB é lida como sRGB ('ignore'), as imagens em tons de cinza são separadas como qualquer outra ('none') e uma imagem CMYK mantém seus valores ('keep'). Cada comportamento da lista é ativado pelo seu campo.

  • O próprio perfil. Um PNG (iCCP) ou um JPEG (ICC_PROFILE) que incorpora um perfil é lido por meio dele, de modo que uma fotografia em Adobe RGB ou Display P3 é separada como aparece, e não como se fosse sRGB. Uma imagem sem perfil, ou com perfil sRGB, é lida como sRGB, como antes. 'ignore' lê todas as imagens como sRGB.
  • Um perfil atribuído. assignedRgbProfile indica um .icc armazenado pelo qual toda imagem RGB é lida, seja qual for o perfil que ela incorpore: por exemplo, para um lote de fotografias que perderam o seu. Os bytes dele vêm de resourceBytes; se faltarem, são usados os perfis das próprias imagens, com um aviso imageProfileUnavailable.
  • Mantida para o RIP. No PDF/X-4 com convertImages: false, uma imagem com um perfil diferente de sRGB é gravada nas suas próprias cores, marcada como ICCBased com esse perfil, e o RIP da gráfica a converte.
  • Escala de cinza. Uma imagem em escala de cinza (um PNG ou um JPEG em cinza, ou uma com perfil de cinza) é impressa só no preto, nunca como um cinza de quadricromia. Os seus tons, lidos pelo próprio perfil (ou como a tela os mostra), são ajustados à máquina: 'profile', pelo preto do perfil de saída, cujo ganho de ponto a condição já inclui; um número é o ganho de ponto da máquina no tom de 50 %, em porcentagem (entre 10 e 30, normalmente), que é compensado em seu lugar; 'none' grava os valores como estão, como antes.
print: {
  standard: 'pdfx4',
  imageColor: { grayDotGain: 20 },
},
  • Uma imagem CMYK de outra máquina. Uma imagem CMYK cujo perfil é outra condição de impressão (uma fotografia separada para SWOP ou para papel jornal em um livro para FOGRA) é separada de novo para a de saída (cmykProfile: 'convert'), e o que é só preto continua só preto: um TIFF ou um documento do Photoshop a partir dos seus pixels; um JPEG CMYK, cujos pixels não são descomprimidos, é marcado como ICCBased com o próprio perfil no PDF/X-4 para que o RIP o converta, e passa como está no PDF/X-1a, que não admite essa marcação; ali o preflight avisa disso (cmykImageForeign) quando o host lhe dá o perfil da imagem (imageProfile). No PDF/X-4 com convertImages: false, um TIFF ou um documento do Photoshop é marcado do mesmo modo. 'keep' imprime os valores de toda imagem CMYK como estão.

Os ajustes de uma só imagem. O printColor de um recurso aceita os mesmos campos que o print.imageColor do livro e os aplica só a essa imagem: uma fotografia cujo perfil deve ser ignorado, outra lida por um perfil atribuído, uma imagem em cinza com outro ganho de ponto. No Sandbox, o cartão de uma imagem define se ela é lida pelo próprio perfil (“Cor na impressão”), como os cinzas dela se ajustam à máquina (“Cinzas na impressão”) e que perfil lhe é atribuído (“Perfil atribuído”, um arquivo .icc); um pacote leva os perfis atribuídos, o do livro e os das imagens, na sua pasta profiles/. Os ajustes do livro ficam em Preparação para impressão → Imagens.

{ id: 'archive-photo', kind: 'bitmap', bitmap: { fileId: 'photo.jpg', format: 'jpeg', width: 2400, height: 1600 },
  printColor: { embeddedProfile: 'ignore' } }

#Cores definidas em CMYK

Uma cor escrita em CMYK mantém os valores exatos: ColorValue.cmyk (em porcentagem) é aplicado como está numa renderização de impressão, e hex é a forma como ela aparece na tela. Uma entrada da paleta definida em CMYK vale para todas as cores vinculadas a ela.

colorPalette: [
  { id: 'brand', name: 'Brand', value: { hex: '#00a0e3', model: 'cmyk', cmyk: { c: 100, m: 0, y: 0, k: 0 } } },
],

#Cores que sobreimprimem

Qualquer cor pode sobreimprimir numa renderização de impressão: overprint: true num ColorValue faz com que tudo o que é pintado com ela (texto, fios, boxes, fundos) seja impresso sobre o que está por baixo em vez de o vazar. Uma cor de quadricromia é escrita como se separa, sob um estado gráfico de sobreimpressão; uma cor especial sobreimprime na chapa da sua tinta, mesmo onde a mesma tinta em outra cor vaza. Um preto a 100 % K que sobreimprime mantém o tratamento do preto: as áreas grandes continuam saindo em preto composto (black.richBlack). Um PDF em RGB e a tela o ignoram. Defina-o na entrada da paleta para que sobreimprima toda cor vinculada a ela, inclusive os seus tons; uma cor vinculada segue o ajuste da entrada e não tem um próprio. A paleta de uma parte ou de uma seção o mantém: o texto na cor da parte também sobreimprime.

colorPalette: [
  { id: 'title', name: 'Title', value: { hex: '#c00020', model: 'cmyk', cmyk: { c: 0, m: 100, y: 80, k: 10 }, overprint: true } },
],

Uma renderização de impressão reconhece uma cor pelo hex que o layout pinta, por isso uma cor que sobreimprime nunca compartilha o hex com uma que vaza. Quando coincidem, a que sobreimprime se desloca um passo (1/255 num canal), como fazem as cores especiais; a cor de uma parte para uma entrada que sobreimprime se afasta da mesma forma de qualquer cor do livro que vaza. Uma cor que sobreimprime e não deposita tinta (o branco do papel, uma tinta a 0 %) desaparece na impressão: o preflight a marca como crítica (overprintWhite). Uma renderização com mais cores distintas do que códigos disponíveis (cerca de 25 milhões) vaza o restante e avisa (overprintsExhausted). No Sandbox, isso é definido pelo interruptor “Sobreimprimir na impressão” do seletor de cor.

#Preflight

interface PrintPreflightConfig {
  enabled?: boolean;
  minImageResolution?: number;       // ppi no tamanho impresso.
  criticalImageResolution?: number;
  minRuleWidth?: Dimension;
  smallTextSize?: Dimension;
  safeZone?: Dimension;
  bleedSnap?: Dimension;
  checkFonts?: boolean;
}
PropriedadeTipoPadrãoDescrição
enabledbooleantrueExecuta as verificações.
minImageResolutionnumber300Um bitmap colocado com menos pixels por polegada que isso no tamanho impresso, recorte incluído, recebe um aviso: figuras, imagens em células de tabela, imagens de design, quadros de quadrinhos. Um bitmap sem resolução própria é impresso com page.dpi no tamanho natural dele; por isso, uma página diagramada a 150 dpi imprime cada imagem assim a 150 ppi; um bitmap com resolução (bitmap.resolution, layout.bitmapResolution) é impresso com essa resolução no tamanho natural.
criticalImageResolutionnumber150Abaixo disso, o aviso é crítico. Nunca acima de minImageResolution.
minRuleWidthDimension0.25ptFios, bordas, fios entre colunas, fios de tabela e bordas de quadros de quadrinhos mais finos que isso.
smallTextSizeDimension9ptTexto menor que isso composto em mais de uma tinta (uma cor de quadricromia, preto composto): fica borrado quando as chapas se deslocam. O texto preto, só em K, nunca conta.
safeZoneDimension5mmTexto mais perto do refile que isso, onde a guilhotina pode cortá-lo.
bleedSnapDimension3mmUma caixa ou imagem que para a essa distância do refile sem chegar à sangria: leve-a para a sangria ou recue-a.
checkFontsbooleantrueInforma as fontes que um PDF inserido não incorpora (o Sandbox inspeciona cada matriz de impressão com inspectPrintMaster). O Postext incorpora todas as fontes que compõe.

preflightDocument(doc, options) executa as verificações num documento diagramado e devolve uma lista de problemas, cada um com um kind, uma severity ('critical', 'warning' ou 'info'), o pageIndex absoluto no livro, o rect do elemento em questão (px da página) e, quando o elemento tem, o intervalo de origem dele. Os tipos são lowImageResolution, declaredPixelsMismatch, rgbImage, thinRule, smallProcessText, inkLimit, safeZone e nearTrim. Sem um transform, uma cor neutra conta como uma tinta e qualquer outra como três, e a cobertura não é verificada; com um, as contagens e a cobertura são exatas. A resolução de uma imagem é calculada a partir dos pixels que o recurso dela declara, ou dos do próprio arquivo quando imageSize(fileId) os fornece (bitmapInfo sobre os bytes, ou a imagem decodificada): uma declaração que se afasta do arquivo em mais de um pixel é informada uma vez como declaredPixelsMismatch, um aviso quando declara mais pixels do que o arquivo tem. placedImageResolutions(doc, { resources, imageSize }) lista cada bitmap colocado com o ppi efetivo, com o preflight ligado ou não. Os rótulos de uma figura contam como texto para smallProcessText, inkLimit e 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,                                    // tamanhos em pixels dos bitmaps
  imageSize: (fileId) => bitmapInfo(bytesOf(fileId)),  // os pixels reais dos arquivos
  imageColor: (fileId) => colourOf(fileId),     // 'rgb' | 'cmyk' | 'gray', tirado do arquivo
});
if (issues.some((i) => i.severity === 'critical')) process.exit(1);
 
const master = await inspectPrintMaster(masterBytes);
// => { nonEmbeddedFonts: ['Helvetica'], rgb: true, transparency: false }

#Implementação de referência

O componente PdfViewport do Sandbox (packages/postext-sandbox/src/viewport/pdf/PdfViewport.tsx) liga as peças acima em uma visualização ao vivo com botões para gerar de novo, baixar e imprimir, e é um bom ponto de partida para qualquer integração de PDF no navegador. Ele constrói o VDT pelo worker de layout compartilhado (veja Executar a diagramação em um Web Worker), para que clicar em Regenerar não congele a interface enquanto o pipeline roda; a thread principal só cuida de renderToPdf (que já é rápido depois que o VDT existe).