Transformar HTML em PDFs é essencial para criar documentos padronizados, como relatórios, faturas e materiais para clientes. O Puppeteer, uma ferramenta de automação de navegadores, ajuda você a gerenciar estilos, layouts e quebras de página para gerar PDFs profissionais. Confira rapidamente o que é possível fazer com o Puppeteer:
- Gerar PDFs: Use o Puppeteer para converter HTML em PDFs refinados enquanto executa JavaScript e aplica CSS personalizado.
- Controlar estilos: Defina tamanhos de página, margens, fontes, cabeçalhos, rodapés e muito mais com CSS específico para impressão.
- Gerenciar quebras de página: Use regras CSS para evitar que tabelas, títulos ou imagens sejam divididos entre páginas.
- Otimizar o desempenho: Melhore a qualidade e reduza o tamanho dos arquivos com escala, otimização de imagens e gerenciamento eficiente de recursos.
Início rápido: Instale o Puppeteer com npm install puppeteer, carregue seu HTML (como string, arquivo local ou URL) e configure definições do PDF, como dimensões, margens e renderização de plano de fundo. Use regras CSS @media print para ter mais controle sobre os estilos de impressão.
Principais recursos:
- Personalização de páginas com regras
@page. - Modelos de cabeçalho/rodapé para layouts profissionais.
- Gerenciamento de conteúdo em várias páginas para evitar divisões inadequadas em tabelas ou textos.
Com o Puppeteer, você pode automatizar e personalizar a geração de PDFs para obter resultados consistentes e de alta qualidade.
🌐 Converta HTML em PDF com Puppeteer no Node.js 🚀 Passo a passo completo ...
Primeiros passos com o Puppeteer
Saiba como configurar e usar o Puppeteer para gerar PDFs. Siga estas etapas para começar.
Configuração
Antes de começar, verifique se o Node.js versão 14.0.0 ou superior está instalado no seu sistema. Veja como configurar tudo:
- Instale o Node.js: Baixe-o em nodejs.org e conclua a instalação.
- Crie uma pasta de projeto: Crie uma nova pasta para seu projeto.
- Inicialize o projeto: Abra um terminal na pasta do projeto e execute
npm init -y. - Instale o Puppeteer: Use o comando
npm install puppeteerpara adicionar o Puppeteer ao projeto.
Primeiro script de geração de PDF
Veja 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();
// Definir o conteúdo da página
await page.setContent(`
<html>
<body>
<h1>Documento PDF de exemplo</h1>
<p>Gerado com Puppeteer</p>
</body>
</html>
`);
// Gerar 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 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 oferece várias formas de carregar conteúdo HTML para gerar PDFs:
Carregamento direto de conteúdo: Use uma string que contém o HTML.
await page.setContent(htmlString);Acesso a arquivo local: Carregue um arquivo HTML do seu sistema local.
await page.goto(`file:${path.join(__dirname, 'template.html')}`);Carregamento por URL remota: Busque HTML em um site ativo.
await page.goto('https://yourwebsite.com/page-to-convert');
Ao trabalhar com recursos externos, como imagens ou estilos, verifique se eles estão incorporados, usam URLs absolutas ou são armazenados localmente.
Dicas para melhor desempenho
Para garantir uma geração de PDF fluida, tenha estes pontos em mente:
- Use
page.waitForNetworkIdle()para aguardar a conclusão de todas as solicitações de rede. - Defina tempos limite adequados para carregar recursos.
- Controle explicitamente o carregamento de fontes para evitar problemas de renderização.
Quando seu HTML estiver pronto, você poderá personalizar os estilos e as configurações do PDF.
Configurações de estilo do PDF
Regras CSS específicas para impressão
Para adaptar seu conteúdo à saída em PDF, use regras @media print. Veja um exemplo:
@media print {
/* Ocultar menus de navegação e elementos não essenciais */
nav, button, .no-print {
display: none;
}
/* Ajustar o texto para melhor legibilidade em PDFs */
body {
font-size: 12pt;
line-height: 1.5;
}
/* Garantir a renderização precisa de planos de fundo */
* {
-webkit-print-color-adjust: exact;
}
}
Se quiser manter os estilos voltados para tela em vez de aplicar estilos específicos para impressão, inclua esta linha antes de gerar o PDF:
await page.emulateMediaType('screen');
Depois que os estilos de impressão forem aplicados, você poderá ajustar o layout.
Configurações de layout da página
Defina as dimensões do PDF usando opções do Puppeteer ou regras CSS @page. No 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, use regras CSS @page:
@page {
size: 8.5in 11in;
margin: 0.75in 0.5in;
}
Depois de configurar o layout, você poderá refinar os elementos de design para obter um visual mais profissional.
Elementos de texto e design
Para deixar 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 obter cores de plano 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.
sbb-itb-23997f1
Controle de quebras de página
Propriedades CSS de quebra de página
Gerenciar quebras de página com eficiência garante que seu conteúdo flua adequadamente entre as páginas. Use estas propriedades CSS para controlar onde o conteúdo será dividido:
/* Iniciar uma nova página antes dos capítulos */
.chapter {
page-break-before: always;
}
/* Manter títulos junto do respectivo conteúdo */
h2, h3 {
page-break-after: avoid;
}
/* Evitar a divisão de tabelas ou figuras */
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 alinhados a essas definições.
Configuração de cabeçalho e rodapé
Configure cabeçalhos e rodapés no Puppeteer para dar um visual profissional ao PDF:
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%;">
Página <span class="pageNumber"></span> de <span class="totalPages"></span>
</div>
`,
margin: {
top: '1in',
bottom: '1in'
}
});
Ajuste as margens para que o cabeçalho e o rodapé se encaixem corretamente sem sobrepor seu conteúdo.
Gerenciamento de conteúdo em várias páginas
Com as quebras de página e os cabeçalhos/rodapés definidos, concentre-se em gerenciar o conteúdo em várias páginas. O controle adequado do layout garante que seu documento permaneça claro e profissional:
/* Manter legendas junto das respectivas imagens */
figure {
display: table;
page-break-inside: avoid;
}
figcaption {
display: table-caption;
caption-side: bottom;
}
/* Evitar a divisão de itens de lista ou linhas de tabela */
li, .table-row {
page-break-inside: avoid;
}
/* Permitir que tabelas grandes sejam divididas entre páginas */
.table-wrapper {
page-break-inside: auto;
}
Para tabelas grandes que ocupam várias páginas, envolva-as em um contêiner que permita quebras, mantendo as linhas intactas. Isso garante que os dados continuem fáceis de acompanhar, mesmo em conjuntos de dados extensos.
Dica: Ative a opção
printBackgroundno Puppeteer para renderizar todos os elementos visuais, incluindo cores de plano de fundo e imagens:
await page.pdf({
printBackground: true,
preferCSSPageSize: true
});
Qualidade e desempenho do PDF
Melhorar a qualidade e o desempenho do PDF exige atenção à escala, ao tratamento de imagens e ao gerenciamento de recursos. Estas etapas garantem que o documento final tenha um visual profissional e funcione com eficiência.
Métodos de escala de conteúdo
Dimensionar o conteúdo corretamente garante que ele permaneça legível e consistente no design. O Puppeteer oferece controles detalhados de escala para renderizar PDFs:
await page.pdf({
scale: 0.8,
preferCSSPageSize: true,
format: 'Letter'
});
Nesse caso, valores abaixo de 1 reduzem o conteúdo, enquanto valores acima de 1 o ampliam. Combinar a escala com preferCSSPageSize garante que o PDF siga as dimensões definidas no CSS:
@page {
size: 8.5in 11in;
margin: 0.5in;
}
Gerenciamento da qualidade de imagens
Escolher o formato de imagem certo é essencial. PNG funciona bem para elementos visuais detalhados, como gráficos e logotipos, mas pode aumentar o tamanho do arquivo. JPEG é uma opção melhor para fotos, enquanto o WebP costuma ser convertido, o que pode aumentar ainda mais o tamanho do arquivo.
Para melhorar a nitidez das imagens, aumente o fator de escala do dispositivo:
await page.setViewport({
width: 1200,
height: 800,
deviceScaleFactor: 2
});
Problemas comuns e soluções
Resolver desafios comuns, como gerenciamento de recursos, tamanho de arquivo e erros, pode melhorar significativamente o desempenho.
Gerenciamento de recursos
Use uma única instância do navegador e uma página para lidar com várias solicitações de PDF, reduzindo a sobrecarga: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); }Otimização do tamanho do arquivo
Minimize o tamanho do arquivo removendo elementos desnecessários e otimizando imagens:await page.evaluate(() => { document.querySelectorAll('.no-print').forEach(el => el.remove()); document.querySelectorAll('img').forEach(img => { img.loading = 'lazy'; img.decoding = 'async'; }); });Tratamento de erros
Implemente estratégias para lidar com erros, como tempos limite e novas tentativas:const generatePDF = async (page, options) => { try { await page.goto(options.url, { waitUntil: 'networkidle0', timeout: 30000 }); return await page.pdf(options); } catch (error) { console.error('Falha na geração do PDF:', error); throw error; } };
Conclusão
Usar o Puppeteer para converter HTML em PDF oferece ferramentas eficazes para criar documentos de nível profissional.
Principais etapas a seguir
- Aplique configurações de mídia de impressão com
page.emulateMediaType('print'). - Use regras CSS como
page-break-inside: avoidpara garantir que elementos como linhas de tabelas permaneçam intactos.
Essas técnicas se baseiam nos métodos de estilo e layout apresentados anteriormente, servindo como uma base sólida para automações mais avançadas.
Opções avançadas de automação
Você pode levar a geração de PDFs ainda mais longe com estes recursos adicionais de automação:
- Configuração de ambiente
Configure diretórios de cache e definições do navegador para garantir resultados consistentes em diferentes plataformas. - Ajustes de desempenho
Ajuste as configurações de tempo limite e adicione mecanismos de nova tentativa para aprimorar a confiabilidade durante o processo de geração.
Ao implementar esses métodos em produção, inclua tratamento de erros e registros para manter saídas de PDF consistentes e confiáveis.
