TongoRender — HTML to PDF, Image & Screenshot API for Developers

PDFs de uma única página são diretos, mas documentos do mundo real — contratos, relatórios, manuais, catálogos — podem ter dezenas ou até centenas de páginas. Gerenciar quebras de página, manter cabeçalhos e rodapés consistentes e adicionar números de página requer um bom entendimento de estilos CSS de impressão e recursos de APIs de PDF. Este guia cobre tudo que você precisa para produzir documentos multi-página profissionais.

Regras de Quebra de Página CSS

CSS fornece várias propriedades para controlar onde quebras de página ocorrem:

Forçar Quebras de Página

/* Iniciar cada capítulo em uma nova página */
.chapter { break-before: page; }

/* Sintaxe legada alternativa */
.chapter { page-break-before: always; }

/* Forçar uma quebra após o índice */
.toc { break-after: page; }

Prevenir Quebras Indesejadas

/* Manter cabeçalhos com o conteúdo seguinte */
h2, h3 { break-after: avoid; }

/* Não quebrar dentro de cards, figuras ou linhas de tabela */
.card, figure, tr { break-inside: avoid; }

/* Manter pelo menos 3 linhas antes/depois de uma quebra */
p { widows: 3; orphans: 3; }

Quebras Específicas de Tabela

/* O navegador repetirá o thead em cada página */
table { width: 100%; border-collapse: collapse; }
thead { display: table-header-group; }
tfoot { display: table-footer-group; }
tr { break-inside: avoid; }

Cabeçalhos e Rodapés com TongoRender

O TongoRender suporta templates de cabeçalho e rodapé integrados do Chromium. Eles são renderizados separadamente do conteúdo principal e repetidos em cada página:

const response = await fetch('https://api.tongorender.io/v1/pdf', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.TONGORENDER_API_KEY,
  },
  body: JSON.stringify({
    html: documentHtml,
    format: 'A4',
    margin: { top: '25mm', bottom: '20mm', left: '15mm', right: '15mm' },
    displayHeaderFooter: true,
    headerTemplate: `
      <div style="font-size:9px; color:#666; width:100%; padding:0 15mm; display:flex; justify-content:space-between;">
        <span>Acme Corp — Confidencial</span>
        <span>Relatório Anual 2026</span>
      </div>
    `,
    footerTemplate: `
      <div style="font-size:9px; color:#666; width:100%; padding:0 15mm; display:flex; justify-content:space-between;">
        <span>Gerado em 2026-03-15</span>
        <span>Página <span class="pageNumber"></span> de <span class="totalPages"></span></span>
      </div>
    `,
  }),
});

Variáveis de Template Integradas

pageNumber — Número da página atual
totalPages — Número total de páginas
date — Data de impressão formatada
title — Título do documento do <title>

Exemplo Completo de Documento Multi-Página

function buildReport(data) {
  return `
  <!DOCTYPE html>
  <html lang="pt-BR">
  <head>
    <style>
      body { font-family: 'Georgia', serif; color: #333; line-height: 1.6; padding: 30px; }
      .cover { height: 100vh; display: flex; flex-direction: column; justify-content: center; align-items: center; text-align: center; break-after: page; }
      .cover h1 { font-size: 36pt; color: #1a1a2e; }
      .toc { break-after: page; }
      .chapter { break-before: page; }
      h2 { color: #1a1a2e; border-bottom: 2px solid #e2e8f0; break-after: avoid; }
      table { width: 100%; border-collapse: collapse; }
      thead { display: table-header-group; background: #1a1a2e; color: white; }
      tr { break-inside: avoid; }
      p { orphans: 3; widows: 3; }
    </style>
  </head>
  <body>
    <div class="cover">
      <h1>${data.title}</h1>
      <div>${data.subtitle}</div>
    </div>

    <div class="toc">
      <h2>Índice</h2>
      ${data.chapters.map((ch, i) => \`<div>${i + 1}. ${ch.title}</div>\`).join('')}
    </div>

    ${data.chapters.map(ch => \`
      <div class="chapter"><h2>${ch.title}</h2>${ch.content}</div>
    \`).join('')}
  </body>
  </html>`;
}

Armadilhas Comuns

Margens muito pequenas para cabeçalhos/rodapés — As margens superior e inferior devem ser grandes o suficiente para conter os templates de cabeçalho e rodapé.
Esquecendo display: table-header-group — Sem isso, cabeçalhos de tabela não se repetem nas páginas seguintes.
Usando position: fixed para cabeçalhos — Posicionamento fixo não funciona para cabeçalhos repetidos em impressão.
Cores de fundo não imprimindo — Defina printBackground: true nas opções da API.
Ignorando órfãos e viúvas — Uma única linha de um parágrafo isolada no topo ou final de uma página parece pouco profissional.

Com estilos CSS de impressão adequados e o suporte a cabeçalho/rodapé do TongoRender, você pode gerar documentos multi-página profissionais que rivalizam com ferramentas dedicadas de publicação.

Gere PDFs multi-página com o TongoRender — 100 renderizações gratuitas por mês, sem necessidade de cartão de crédito.