Convertendo HTML para PDF com Puppeteer: Configuração de Estilo e Paginação

Transformar HTML em PDFs é crucial para criar documentos padronizados, como relatórios, faturas e materiais de clientes. Marionetista, uma ferramenta de automação de navegador, ajuda você a gerenciar estilos, layouts e quebras de página para saída profissional em PDF. Aqui está uma rápida visão geral do que você pode fazer com Marionetista:

Gerar PDFs: Use o Puppeteer para converter HTML em PDFs refinados enquanto executa JavaScript e aplica CSS personalizado.
Estilos de controle: Defina tamanhos de página, margens, fontes, cabeçalhos, rodapés e muito mais usando CSS específico para impressão.
Gerenciar quebras de página: Use regras CSS para evitar dividir tabelas, títulos ou imagens entre páginas.
Otimize o desempenho: Melhore a qualidade e reduza o tamanho do arquivo com dimensionamento, otimização de imagem e manuseio eficiente de recursos.

Início Rápido: Instale o Puppeteer com npm install puppeteer, carregue seu HTML (como uma string, arquivo local ou URL) e configure as configurações de PDF como dimensões, margens e renderização de fundo. Use @media print Regras CSS para melhor controle sobre estilos de impressão.

Principais funcionalidades:

Personalização de página com @page regras.
Modelos de cabeçalho/rodapé para layouts profissionais.
Gerenciamento de conteúdo de várias páginas para evitar divisões estranhas em tabelas ou texto.

Com o Puppeteer, você pode automatizar e personalizar a geração de PDF para obter resultados consistentes e de alta qualidade.

🌐 Converta HTML para PDF com Marionetista in Node.js 🚀 Passo Completo ...

Introdução ao Puppeteer

Aprenda como configurar e usar o Puppeteer para gerar PDFs. Siga estas etapas para começar.

instalação

Antes de começar, certifique-se de ter o Node.js versão 14.0.0 ou superior instalado no seu sistema. Veja como configurar tudo:

Instalar o Node.js: Baixe em nodejs.org e conclua a instalação.
Criar uma pasta de projeto: Crie uma nova pasta para seu projeto.
Inicializar o projeto: Abra um terminal na pasta do seu projeto e execute npm init -y.
Instale o Puppeteer: Use o comando npm install puppeteer para adicionar o Puppeteer ao seu projeto.

Primeiro script de geração de PDF

Aqui está um script básico para converter HTML em PDF usando o Puppeteer:

<span class="hljs-keyword">const</span> puppeteer = <span class="hljs-built_in">require</span>(<span class="hljs-string">'puppeteer'</span>);

<span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span> <span class="hljs-title function_">generatePDF</span>(<span class="hljs-params"></span>) {
  <span class="hljs-keyword">const</span> browser = <span class="hljs-keyword">await</span> puppeteer.<span class="hljs-title function_">launch</span>();
  <span class="hljs-keyword">const</span> page = <span class="hljs-keyword">await</span> browser.<span class="hljs-title function_">newPage</span>();

  <span class="hljs-comment">// Set page content</span>
  <span class="hljs-keyword">await</span> page.<span class="hljs-title function_">setContent</span>(<span class="hljs-string">`
    <html>
      <body>
        <h1>Sample PDF Document</h1>
        <p>Generated with Puppeteer</p>
      </body>
    </html>
  `</span>);

  <span class="hljs-comment">// Generate PDF</span>
  <span class="hljs-keyword">await</span> page.<span class="hljs-title function_">pdf</span>({
    <span class="hljs-attr">path</span>: <span class="hljs-string">'output.pdf'</span>,
    <span class="hljs-attr">format</span>: <span class="hljs-string">'Letter'</span>,
    <span class="hljs-attr">margin</span>: {
      <span class="hljs-attr">top</span>: <span class="hljs-string">'1in'</span>,
      <span class="hljs-attr">right</span>: <span class="hljs-string">'1in'</span>,
      <span class="hljs-attr">bottom</span>: <span class="hljs-string">'1in'</span>,
      <span class="hljs-attr">left</span>: <span class="hljs-string">'1in'</span>
    }
  });

  <span class="hljs-keyword">await</span> browser.<span class="hljs-title function_">close</span>();
}

<span class="hljs-title function_">generatePDF</span>();

Salve este script como generate-pdf.js. Execute-o digitando node generate-pdf.js no seu terminal. O script criará um PDF com dimensões US Letter (8.5×11 polegadas) e margens de 1 polegada.

Opções de fonte HTML

O Puppeteer fornece várias maneiras de carregar conteúdo HTML para geração de PDF:

Carregamento direto de conteúdo: Use uma string contendo o HTML.

<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">setContent</span>(htmlString);

Acesso a arquivo local: Carregue um arquivo HTML do seu sistema local.

<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">goto</span>(<span class="hljs-string">`file:<span class="hljs-subst">${path.join(__dirname, <span class="hljs-string">'template.html'</span>)}</span>`</span>);

Carregando URL remoto: Obter HTML de um site ativo.

<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">goto</span>(<span class="hljs-string">'https://yourwebsite.com/page-to-convert'</span>);

Ao trabalhar com recursos externos, como imagens ou estilos, certifique-se de que eles estejam incorporados, usem URLs absolutos ou sejam armazenados localmente.

Dicas para Melhor Desempenho

Para garantir uma geração de PDF tranquila, tenha estas dicas em mente:

Uso page.waitForNetworkIdle() para aguardar que todas as solicitações de rede sejam concluídas.
Defina tempos limite apropriados para carregar recursos.
Manipule o carregamento de fontes explicitamente para evitar problemas de renderização.

Quando o HTML estiver pronto, você pode prosseguir para personalizar os estilos e as configurações do PDF.

Configurações de estilo PDF

Regras CSS específicas para impressão

Para adaptar seu conteúdo para saída em PDF, use @media print regras. Aqui está um exemplo:

<span class="hljs-keyword">@media</span> print {
  <span class="hljs-comment">/* Hide navigation menus and non-essential elements */</span>
  <span class="hljs-selector-tag">nav</span>, <span class="hljs-selector-tag">button</span>, <span class="hljs-selector-class">.no-print</span> {
    <span class="hljs-attribute">display</span>: none;
  }

  <span class="hljs-comment">/* Adjust text for better readability in PDFs */</span>
  <span class="hljs-selector-tag">body</span> {
    <span class="hljs-attribute">font-size</span>: <span class="hljs-number">12pt</span>;
    <span class="hljs-attribute">line-height</span>: <span class="hljs-number">1.5</span>;
  }

  <span class="hljs-comment">/* Ensure accurate background rendering */</span>
  * {
    -webkit-<span class="hljs-attribute">print-color-adjust</span>: exact;
  }
}

Se você quiser manter seus estilos baseados em tela em vez de aplicar estilos específicos de impressão, inclua esta linha antes de gerar o PDF:

<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">emulateMediaType</span>(<span class="hljs-string">'screen'</span>);

Depois que os estilos de impressão forem aplicados, você pode prosseguir para os ajustes de layout.

Configurações de layout de página

Defina as dimensões do PDF usando as opções do Puppeteer ou CSS @page regras. Para o Puppeteer, você pode usar a seguinte configuração:

<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">pdf</span>({
  <span class="hljs-attr">format</span>: <span class="hljs-string">'Letter'</span>,
  <span class="hljs-attr">margin</span>: {
    <span class="hljs-attr">top</span>: <span class="hljs-string">'0.75in'</span>,
    <span class="hljs-attr">right</span>: <span class="hljs-string">'0.5in'</span>,
    <span class="hljs-attr">bottom</span>: <span class="hljs-string">'0.75in'</span>,
    <span class="hljs-attr">left</span>: <span class="hljs-string">'0.5in'</span>
  },
  <span class="hljs-attr">landscape</span>: <span class="hljs-literal">false</span>,
  <span class="hljs-attr">preferCSSPageSize</span>: <span class="hljs-literal">true</span>
});

Para tamanhos de página mais personalizados, confie no CSS @page regras:

<span class="hljs-keyword">@page</span> {
  size: <span class="hljs-number">8.5in</span> <span class="hljs-number">11in</span>;
  <span class="hljs-attribute">margin</span>: <span class="hljs-number">0.75in</span> <span class="hljs-number">0.5in</span>;
}

Depois de configurar o layout, você pode ajustar os elementos de design para obter uma aparência elegante.

Elementos de texto e design

Para tornar o conteúdo visualmente claro e profissional, use estas regras CSS:

<span class="hljs-selector-tag">body</span> {
  <span class="hljs-attribute">font-family</span>: <span class="hljs-string">'Arial'</span>, sans-serif;
  <span class="hljs-attribute">color</span>: <span class="hljs-number">#333333</span>;
}

<span class="hljs-selector-tag">h1</span>, <span class="hljs-selector-tag">h2</span>, <span class="hljs-selector-tag">h3</span> {
  <span class="hljs-attribute">page-break-after</span>: avoid;
  <span class="hljs-attribute">color</span>: <span class="hljs-number">#000000</span>;
}

<span class="hljs-selector-tag">table</span> {
  <span class="hljs-attribute">width</span>: <span class="hljs-number">100%</span>;
  <span class="hljs-attribute">border-collapse</span>: collapse;
  <span class="hljs-attribute">page-break-inside</span>: avoid;
}

<span class="hljs-selector-tag">img</span> {
  <span class="hljs-attribute">max-width</span>: <span class="hljs-number">100%</span>;
  <span class="hljs-attribute">height</span>: auto;
  <span class="hljs-attribute">page-break-inside</span>: avoid;
}

Para cores de fundo consistentes, especialmente em seções críticas, adicione esta regra:

<span class="hljs-selector-class">.color-critical</span> {
  -webkit-<span class="hljs-attribute">print-color-adjust</span>: exact;
}

Esses ajustes garantem que seu PDF seja fácil de ler e visualmente atraente.

sbb-itb-23997f1

Controle de quebra de página

Propriedades CSS de quebra de página

Gerenciar quebras de página de forma eficaz garante que seu conteúdo flua suavemente entre as páginas. Use estas propriedades CSS para controlar onde o conteúdo se divide:

<span class="hljs-comment">/* Start new page before chapters */</span>
<span class="hljs-selector-class">.chapter</span> {
  <span class="hljs-attribute">page-break-before</span>: always;
}

<span class="hljs-comment">/* Keep headings together with their content */</span>
<span class="hljs-selector-tag">h2</span>, <span class="hljs-selector-tag">h3</span> {
  <span class="hljs-attribute">page-break-after</span>: avoid;
}

<span class="hljs-comment">/* Avoid splitting tables or figures */</span>
<span class="hljs-selector-tag">table</span>, <span class="hljs-selector-tag">figure</span> {
  <span class="hljs-attribute">page-break-inside</span>: avoid;
}

Essas regras ajudam a manter seu documento organizado e fácil de ler. Depois de configurar as quebras de página, concentre-se em configurar cabeçalhos e rodapés para alinhar com essas configurações.

Configuração de Cabeçalho e Rodapé

Configure cabeçalhos e rodapés no Puppeteer para dar ao seu PDF uma aparência profissional:

<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">pdf</span>({
  <span class="hljs-attr">displayHeaderFooter</span>: <span class="hljs-literal">true</span>,
  <span class="hljs-attr">headerTemplate</span>: <span class="hljs-string">`
    <div style="font-size: 10px; padding: 0 0.5in; width: 100%;">
      <span class="title"></span>
      <span class="date" style="float: right;"></span>
    </div>
  `</span>,
  <span class="hljs-attr">footerTemplate</span>: <span class="hljs-string">`
    <div style="font-size: 10px; text-align: center; width: 100%;">
      Page <span class="pageNumber"></span> of <span class="totalPages"></span>
    </div>
  `</span>,
  <span class="hljs-attr">margin</span>: {
    <span class="hljs-attr">top</span>: <span class="hljs-string">'1in'</span>,
    <span class="hljs-attr">bottom</span>: <span class="hljs-string">'1in'</span>
  }
});

Certifique-se de ajustar as margens para que o cabeçalho e o rodapé se encaixem corretamente sem sobrepor o conteúdo.

Gerenciamento de conteúdo multipágina

Com quebras de página e cabeçalhos/rodapés no lugar, concentre-se em gerenciar o conteúdo em várias páginas. O controle de layout adequado garante que seu documento permaneça claro e profissional:

<span class="hljs-comment">/* Keep captions with their images */</span>
<span class="hljs-selector-tag">figure</span> {
  <span class="hljs-attribute">display</span>: table;
  <span class="hljs-attribute">page-break-inside</span>: avoid;
}

<span class="hljs-selector-tag">figcaption</span> {
  <span class="hljs-attribute">display</span>: table-caption;
  <span class="hljs-attribute">caption-side</span>: bottom;
}

<span class="hljs-comment">/* Avoid splitting list items or table rows */</span>
<span class="hljs-selector-tag">li</span>, <span class="hljs-selector-class">.table-row</span> {
  <span class="hljs-attribute">page-break-inside</span>: avoid;
}

<span class="hljs-comment">/* Allow large tables to break across pages */</span>
<span class="hljs-selector-class">.table-wrapper</span> {
  <span class="hljs-attribute">page-break-inside</span>: auto;
}

Para tabelas grandes que abrangem várias páginas, envolva-as em um contêiner que permita quebras, mantendo as linhas intactas. Isso garante que os dados permaneçam fáceis de seguir, mesmo em conjuntos de dados longos.

Dica: permitir que o printBackground opção no Puppeteer para renderizar todos os elementos visuais, incluindo cores de fundo e imagens:

<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">pdf</span>({
  <span class="hljs-attr">printBackground</span>: <span class="hljs-literal">true</span>,
  <span class="hljs-attr">preferCSSPageSize</span>: <span class="hljs-literal">true</span>
});

Qualidade e desempenho do PDF

Melhorar a qualidade e o desempenho do PDF requer atenção ao dimensionamento, ao manuseio de imagens e ao gerenciamento de recursos. Essas etapas garantem que o documento final tenha uma aparência polida e funcione de forma eficiente.

Métodos de dimensionamento de conteúdo

O dimensionamento correto do conteúdo garante que ele permaneça legível e consistente no design. O Puppeteer oferece controles de dimensionamento detalhados para renderizar PDFs:

<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">pdf</span>({
  <span class="hljs-attr">scale</span>: <span class="hljs-number">0.8</span>,
  <span class="hljs-attr">preferCSSPageSize</span>: <span class="hljs-literal">true</span>,
  <span class="hljs-attr">format</span>: <span class="hljs-string">'Letter'</span>
});

Aqui, valores abaixo de 1 reduzem o conteúdo, enquanto valores acima de 1 o aumentam. Emparelhamento de escala com preferCSSPageSize garante que o PDF esteja de acordo com as dimensões definidas pelo CSS:

<span class="hljs-keyword">@page</span> {
  size: <span class="hljs-number">8.5in</span> <span class="hljs-number">11in</span>;
  <span class="hljs-attribute">margin</span>: <span class="hljs-number">0.5in</span>;
}

Gerenciamento de qualidade de imagem

Escolher o formato de imagem certo é crucial. PNG funciona bem para visuais detalhados como gráficos e logotipos, mas pode aumentar o tamanho do arquivo. JPEG é uma opção melhor para fotos, enquanto WebP muitas vezes é convertido, o que pode aumentar ainda mais o tamanho do arquivo.

Para melhorar a clareza da imagem, aumente o fator de escala do dispositivo:

<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">setViewport</span>({
  <span class="hljs-attr">width</span>: <span class="hljs-number">1200</span>,
  <span class="hljs-attr">height</span>: <span class="hljs-number">800</span>,
  <span class="hljs-attr">deviceScaleFactor</span>: <span class="hljs-number">2</span>
});

Problemas e soluções comuns

Lidar com desafios comuns como gerenciamento de recursos, tamanho de arquivo e erros pode melhorar significativamente o desempenho.

Gestão de Recursos
Use uma única instância e página do navegador para lidar com várias solicitações de PDF, reduzindo a sobrecarga:

<span class="hljs-keyword">const</span> browser = <span class="hljs-keyword">await</span> puppeteer.<span class="hljs-title function_">launch</span>({
  <span class="hljs-attr">args</span>: [<span class="hljs-string">'--no-sandbox'</span>, <span class="hljs-string">'--disable-setuid-sandbox'</span>]
});

<span class="hljs-keyword">const</span> page = <span class="hljs-keyword">await</span> browser.<span class="hljs-title function_">newPage</span>();
<span class="hljs-keyword">for</span> (<span class="hljs-keyword">const</span> request <span class="hljs-keyword">of</span> requests) {
  <span class="hljs-keyword">await</span> <span class="hljs-title function_">generatePDF</span>(page, request);
}

Otimização do tamanho do arquivo
Minimize o tamanho do arquivo removendo elementos desnecessários e otimizando imagens:

<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">evaluate</span>(<span class="hljs-function">() =></span> {
  <span class="hljs-variable language_">document</span>.<span class="hljs-title function_">querySelectorAll</span>(<span class="hljs-string">'.no-print'</span>).<span class="hljs-title function_">forEach</span>(<span class="hljs-function"><span class="hljs-params">el</span> =></span> el.<span class="hljs-title function_">remove</span>());

  <span class="hljs-variable language_">document</span>.<span class="hljs-title function_">querySelectorAll</span>(<span class="hljs-string">'img'</span>).<span class="hljs-title function_">forEach</span>(<span class="hljs-function"><span class="hljs-params">img</span> =></span> {
    img.<span class="hljs-property">loading</span> = <span class="hljs-string">'lazy'</span>;
    img.<span class="hljs-property">decoding</span> = <span class="hljs-string">'async'</span>;
  });
});

Tratamento de erros
Implementar estratégias para lidar com erros como tempos limite e novas tentativas:

<span class="hljs-keyword">const</span> <span class="hljs-title function_">generatePDF</span> = <span class="hljs-keyword">async</span> (<span class="hljs-params">page, options</span>) => {
  <span class="hljs-keyword">try</span> {
    <span class="hljs-keyword">await</span> page.<span class="hljs-title function_">goto</span>(options.<span class="hljs-property">url</span>, {
      <span class="hljs-attr">waitUntil</span>: <span class="hljs-string">'networkidle0'</span>,
      <span class="hljs-attr">timeout</span>: <span class="hljs-number">30000</span>
    });
    <span class="hljs-keyword">return</span> <span class="hljs-keyword">await</span> page.<span class="hljs-title function_">pdf</span>(options);
  } <span class="hljs-keyword">catch</span> (error) {
    <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'PDF generation failed:'</span>, error);
    <span class="hljs-keyword">throw</span> error;
  }
};

Conclusão

Usar o Puppeteer para converter HTML em PDF fornece ferramentas eficazes para criar documentos de nível profissional.

Principais etapas a seguir

Aplicar configurações de mídia de impressão com page.emulateMediaType('print').
Use regras CSS como page-break-inside: avoid para garantir que elementos como linhas de tabela permaneçam intactos.

Essas técnicas se baseiam em métodos anteriores de estilo e layout, servindo como uma base sólida para uma automação mais avançada.

Opções avançadas de automação

Você pode levar a geração de PDF ainda mais longe com estes recursos de automação adicionais:

Configuração de Ambiente
Configure diretórios de cache e configurações do navegador para garantir resultados consistentes em diferentes plataformas.
Tweaks desempenho
Ajuste as configurações de tempo limite e adicione mecanismos de nova tentativa para melhorar a confiabilidade durante o processo de geração.

Ao implantar esses métodos na produção, inclua tratamento de erros e registro para manter saídas em PDF consistentes e confiáveis.

Convertendo HTML para PDF com Puppeteer: Configuração de estilo e paginação