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

Índice

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.

Características principais:

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 ...

Marionetista

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:

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.

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.
```
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')}`);
```

Carregando URL remoto: Obter HTML de um site ativo.

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.

Dicas para Melhor Desempenho

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

Use 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:

@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.

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:

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.

Elementos de texto e design

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.

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:

/* 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.

Configuração de Cabeçalho e Rodapé

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.

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:

/* 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 printBackground opção no Puppeteer para renderizar todos os elementos visuais, incluindo cores de fundo e imagens:

await page.pdf({
  printBackground: true,
  preferCSSPageSize: true
});

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:

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;
}

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:

await page.setViewport({
  width: 1200,
  height: 800,
  deviceScaleFactor: 2
});

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:

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
Implementar 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('PDF generation failed:', error);
    throw 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.