.png)
.svg){kind=icon}
25 de março de 2025
.
7
min ler
Convertendo HTML para PDF com Puppeteer: Configuração de estilo e paginação
Jorge Miloradovitch
Pesquisador, redator e entrevistador de casos de uso
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:
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.
Características principais:
@page regras.Com o Puppeteer, você pode automatizar e personalizar a geração de PDF para obter resultados consistentes e de alta qualidade.
Aprenda como configurar e usar o Puppeteer para gerar PDFs. Siga estas etapas para começar.
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:
npm init -y.npm install puppeteer para adicionar o Puppeteer ao seu projeto.Aqui está um script básico para converter HTML em PDF usando o Puppeteer:
const puppeteer = require('puppeteer');
async function generatePDF() {
const browser = await puppeteer.launch();
const page = await browser.newPage();
// Set page content
await page.setContent(`
<html>
<body>
<h1>Sample PDF Document</h1>
<p>Generated with Puppeteer</p>
</body>
</html>
`);
// Generate PDF
await page.pdf({
path: 'output.pdf',
format: 'Letter',
margin: {
top: '1in',
right: '1in',
bottom: '1in',
left: '1in'
}
});
await browser.close();
}
generatePDF();
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.
O Puppeteer fornece várias maneiras de carregar conteúdo HTML para geração de PDF:
await page.setContent(htmlString);
await page.goto(`file:${path.join(__dirname, 'template.html')}`);
await page.goto('https://yourwebsite.com/page-to-convert');
Ao trabalhar com recursos externos, como imagens ou estilos, certifique-se de que eles estejam incorporados, usem URLs absolutos ou sejam armazenados localmente.
Para garantir uma geração de PDF tranquila, tenha estas dicas em mente:
page.waitForNetworkIdle() para aguardar que todas as solicitações de rede sejam concluídas.Quando o HTML estiver pronto, você pode prosseguir para personalizar os estilos e as configurações do PDF.
Para adaptar seu conteúdo para saída em PDF, use @media print regras. Aqui está um exemplo:
@media print {
/* Hide navigation menus and non-essential elements */
nav, button, .no-print {
display: none;
}
/* Adjust text for better readability in PDFs */
body {
font-size: 12pt;
line-height: 1.5;
}
/* Ensure accurate background rendering */
* {
-webkit-print-color-adjust: 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:
await page.emulateMediaType('screen');
Depois que os estilos de impressão forem aplicados, você pode prosseguir para os ajustes de layout.
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:
await page.pdf({
format: 'Letter',
margin: {
top: '0.75in',
right: '0.5in',
bottom: '0.75in',
left: '0.5in'
},
landscape: false,
preferCSSPageSize: true
});
Para tamanhos de página mais personalizados, confie no CSS @page regras:
@page {
size: 8.5in 11in;
margin: 0.75in 0.5in;
}
Depois de configurar o layout, você pode ajustar os elementos de design para obter uma aparência elegante.
Para tornar o conteúdo visualmente claro e profissional, use estas regras CSS:
body {
font-family: 'Arial', sans-serif;
color: #333333;
}
h1, h2, h3 {
page-break-after: avoid;
color: #000000;
}
table {
width: 100%;
border-collapse: collapse;
page-break-inside: avoid;
}
img {
max-width: 100%;
height: auto;
page-break-inside: avoid;
}
Para cores de fundo consistentes, especialmente em seções críticas, adicione esta regra:
.color-critical {
-webkit-print-color-adjust: exact;
}
Esses ajustes garantem que seu PDF seja fácil de ler e visualmente atraente.
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:
/* Start new page before chapters */
.chapter {
page-break-before: always;
}
/* Keep headings together with their content */
h2, h3 {
page-break-after: avoid;
}
/* Avoid splitting tables or figures */
table, figure {
page-break-inside: 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.
Configure cabeçalhos e rodapés no Puppeteer para dar ao seu PDF uma aparência profissional:
await page.pdf({
displayHeaderFooter: true,
headerTemplate: `
<div style="font-size: 10px; padding: 0 0.5in; width: 100%;">
<span class="title"></span>
<span class="date" style="float: right;"></span>
</div>
`,
footerTemplate: `
<div style="font-size: 10px; text-align: center; width: 100%;">
Page <span class="pageNumber"></span> of <span class="totalPages"></span>
</div>
`,
margin: {
top: '1in',
bottom: '1in'
}
});
Certifique-se de ajustar as margens para que o cabeçalho e o rodapé se encaixem corretamente sem sobrepor o conteúdo.
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:
/* Keep captions with their images */
figure {
display: table;
page-break-inside: avoid;
}
figcaption {
display: table-caption;
caption-side: bottom;
}
/* Avoid splitting list items or table rows */
li, .table-row {
page-break-inside: avoid;
}
/* Allow large tables to break across pages */
.table-wrapper {
page-break-inside: 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
printBackgroundopção no Puppeteer para renderizar todos os elementos visuais, incluindo cores de fundo e imagens:
await page.pdf({
printBackground: true,
preferCSSPageSize: true
});
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.
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:
await page.pdf({
scale: 0.8,
preferCSSPageSize: true,
format: 'Letter'
});
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:
@page {
size: 8.5in 11in;
margin: 0.5in;
}
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:
await page.setViewport({
width: 1200,
height: 800,
deviceScaleFactor: 2
});
Lidar com desafios comuns como gerenciamento de recursos, tamanho de arquivo e erros pode melhorar significativamente o desempenho.
const browser = await puppeteer.launch({
args: ['--no-sandbox', '--disable-setuid-sandbox']
});
const page = await browser.newPage();
for (const request of requests) {
await generatePDF(page, request);
}
await page.evaluate(() => {
document.querySelectorAll('.no-print').forEach(el => el.remove());
document.querySelectorAll('img').forEach(img => {
img.loading = 'lazy';
img.decoding = 'async';
});
});
const generatePDF = async (page, options) => {
try {
await page.goto(options.url, {
waitUntil: 'networkidle0',
timeout: 30000
});
return await page.pdf(options);
} catch (error) {
console.error('PDF generation failed:', error);
throw error;
}
};
Usar o Puppeteer para converter HTML em PDF fornece ferramentas eficazes para criar documentos de nível profissional.
page.emulateMediaType('print').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.
Você pode levar a geração de PDF ainda mais longe com estes recursos de automação adicionais:
Ao implantar esses métodos na produção, inclua tratamento de erros e registro para manter saídas em PDF consistentes e confiáveis.
