Como sincronizar variáveis de paginação em PDFs gerados com Puppeteer em múltiplos documentos

Ao gerar vários PDFs a partir de URLs distintas usando Puppeteer, uma dúvida recorrente é como manter uma continuidade na paginação, especialmente ao tentar incluir números de página e total de páginas nos rodapés. Essa prática é comum em relatórios ou documentos compostos, onde a sequência lógica das páginas precisa ser preservada para facilitar a navegação.

Diagnóstico do problema

O desafio central é que cada PDF é criado de forma independente, o que impede o uso direto de variáveis globais ou sequenciais entre os processos de geração. Além disso, as opções padrão do Puppeteer, como page.pdf(), oferecem suporte limitado para manipulação dinâmica de paginação, principalmente quando se quer refletir o número total de páginas de todos os PDFs combinados. A decisão fica mais saudável quando o time consegue medir o impacto depois.

Outro ponto importante é entender como o Puppeteer gerencia o fluxo de geração de PDFs e como o Chrome DevTools Protocol, utilizado por baixo dos panos, fornece informações de paginação. Apesar de existirem opções para inserir conteúdo nos rodapés via displayHeaderFooter, a atualização dinâmica dessas variáveis entre múltiplos PDFs não é trivial. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco.

Abordagem de solução

A estratégia recomendada é criar uma etapa de pré-processamento em duas fases:

1. Pré-cálculo do total de páginas: Antes de gerar os PDFs finais, deve-se criar uma fase de simulação onde cada URL é renderizada em modo de 'preview' para determinar a quantidade de páginas que cada uma produzirá. Isso pode ser feito com uma configuração de page.pdf() que apenas gera o PDF na memória, analisando o número de páginas a partir do resultado ou usando ferramentas de análise de PDF.

2. Geração sequencial com controle de paginação: Com os totais de cada documento em mãos, é possível calcular o pageNumber inicial para cada PDF subsequente, somando o total de páginas anteriores. Assim, ao gerar cada PDF final, podem-se inserir variáveis de paginação no rodapé, usando displayHeaderFooter com conteúdo estático ou dinâmico, preenchendo as variáveis de acordo com o cálculo realizado.

Para exemplificar, considere o seguinte pseudocódigo:

const totais = []. // Armazena o número de páginas de cada URL
// Primeiro, calcula o total de páginas de cada URL
for (const url of urls) {
  const previewPdf = await gerarPdfPreview(url). // gera em memória
  const totalPaginas = contarPaginas(previewPdf). // função que analisa o PDF
  totais.push(totalPaginas). }
// Depois, gera os PDFs finais, ajustando o número inicial da paginação
let paginaInicial = 1. for (let i = 0. i < urls.length. i++) {
  const total = totais[i]. const footerContent = `${paginaInicial} de ${soma(totais)}`. await gerarPdfComPaginaçao(urls[i], footerContent, paginaInicial). paginaInicial += total. }

Limites e trade-offs

Esse método implica em duas passagens de geração de PDF por URL, o que pode aumentar o tempo total do processo. Além disso, a análise do PDF para determinar o total de páginas pode exigir uso de bibliotecas externas ou processamento adicional, dependendo do formato e tamanho dos documentos. Esse contexto ajuda a separar ganho real de novidade difícil de sustentar. A decisão fica mais saudável quando o time consegue medir o impacto depois. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco.

Outro ponto a se considerar é a complexidade do conteúdo dinâmico. Caso o conteúdo dos PDFs seja altamente variável ou dependente de dados em tempo real, fazer o pré-cálculo de páginas pode não refletir a realidade final, levando a discrepâncias na paginação.

Passos práticos

• Implementar uma função que gere os PDFs em modo de pré-visualização para contar páginas.
• Armazenar os totais de páginas de cada documento antes de gerar os PDFs finais.
• Calcular o início da paginação para cada documento com base na soma anterior.
• Inserir variáveis dinâmicas no rodapé usando displayHeaderFooter, ajustando as variáveis de paginação para cada PDF.
• Testar com diferentes tamanhos de conteúdo e ajustar o método de contagem de páginas conforme necessário.

Essa abordagem garante maior controle sobre a paginação em documentos compostos, evitando inconsistências na apresentação final. Como alternativa, alguns sistemas avançados de geração de PDFs suportam APIs que facilitam essa sincronização, mas, na prática, fazer o controle manual costuma ser suficiente e mais flexível. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. Esse contexto ajuda a separar ganho real de novidade difícil de sustentar. A decisão fica mais saudável quando o time consegue medir o impacto depois.