Conversión de HTML a PDF con Puppeteer: Configuración de estilos y paginación

Tabla de contenidos.

Conversión de HTML a PDF con Puppeteer: Configuración de estilos y paginación

Convertir HTML en PDF es crucial para crear documentos estandarizados como informes, facturas y materiales para clientes. Titiritero, una herramienta de automatización del navegador, te ayuda a gestionar estilos, diseños y saltos de página para obtener resultados profesionales en PDF. Aquí tienes un breve resumen de lo que puedes hacer con Titiritero:

Generar archivos PDF:Utilice Puppeteer para convertir HTML en archivos PDF pulidos mientras ejecuta JavaScript y aplica CSS personalizado.
Estilos de control:Defina tamaños de página, márgenes, fuentes, encabezados, pies de página y más utilizando CSS específico de impresión.
Administrar saltos de página:Utilice reglas CSS para evitar dividir tablas, encabezados o imágenes en varias páginas.
Optimizar el rendimiento:Mejore la calidad y reduzca el tamaño de los archivos con escalado, optimización de imágenes y manejo eficiente de recursos.

Empieza:Instalar Puppeteer con npm install puppeteer, cargue su HTML (como cadena, archivo local o URL) y configure los ajustes del PDF, como las dimensiones, los márgenes y la representación del fondo. Use @media print Reglas CSS para un mejor control sobre los estilos de impresión.

Características:

Personalización de página con @page reglas.
Plantillas de encabezado/pie de página para diseños profesionales.
Gestión de contenidos de varias páginas para evitar divisiones incómodas en tablas o textos.

Con Puppeteer, puede automatizar y personalizar la generación de PDF para obtener resultados consistentes y de alta calidad.

🌐 Convierte HTML a PDF con Titiritero in Node.js 🚀 Paso completo...

Titiritero

Introducción a Puppeteer

Aprende a configurar y usar Puppeteer para generar archivos PDF. Sigue estos pasos para empezar.

Preparar

Antes de empezar, asegúrate de tener instalada la versión 14.0.0 o superior de Node.js en tu sistema. A continuación te explicamos cómo configurarlo todo:

Instalar Node.js:Descárgalo desde nodejs.org y completar la instalación.
Crear una carpeta de proyecto:Crea una nueva carpeta para tu proyecto.
Inicializar el proyecto:Abre una terminal en la carpeta de tu proyecto y ejecuta npm init -y.
Instalar Titiritero: Utilice el comando npm install puppeteer para agregar Puppeteer a tu proyecto.

Primer script de generación de PDF

Aquí hay un script básico para convertir HTML en PDF usando 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();

Guarde este script como generate-pdf.jsEjecútalo escribiendo node generate-pdf.js En tu terminal. El script creará un PDF con dimensiones Carta (8.5 x 11 pulgadas) y márgenes de 1 cm.

Opciones de código fuente HTML

Puppeteer ofrece múltiples formas de cargar contenido HTML para la generación de PDF:

Carga directa de contenido:Utilice una cadena que contenga el HTML.
```
await page.setContent(htmlString);
```
Acceso a archivos locales:Cargue un archivo HTML desde su sistema local.
```
await page.goto(`file:${path.join(__dirname, 'template.html')}`);
```

Carga de URL remota:Obtener HTML de un sitio web activo.

await page.goto('https://yourwebsite.com/page-to-convert');

Al trabajar con recursos externos como imágenes o estilos, asegúrese de que estén integrados, utilicen URL absolutas o estén almacenados localmente.

Consejos para un mejor rendimiento

Para garantizar una generación de PDF fluida, tenga en cuenta estos consejos:

Use page.waitForNetworkIdle() esperar a que finalicen todas las solicitudes de red.
Establezca tiempos de espera adecuados para cargar recursos.
Maneje la carga de fuentes explícitamente para evitar problemas de renderizado.

Una vez que su HTML esté listo, puede pasar a personalizar los estilos y configuraciones del PDF.

Configuración de estilo PDF

Reglas CSS específicas de impresión

Para adaptar su contenido para la salida en PDF, utilice @media print Reglas. Aquí tienes un ejemplo:

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

Si desea conservar los estilos basados en pantalla en lugar de aplicar estilos específicos de impresión, incluya esta línea antes de generar el PDF:

await page.emulateMediaType('screen');

Una vez aplicados los estilos de impresión, puedes pasar a los ajustes de diseño.

Configuración del diseño de página

Defina las dimensiones del PDF utilizando las opciones de Puppeteer o CSS @page Reglas. Para Puppeteer, puedes usar la siguiente configuración:

await page.pdf({
  format: 'Letter',
  margin: {
    top: '0.75in',
    right: '0.5in',
    bottom: '0.75in',
    left: '0.5in'
  },
  landscape: false,
  preferCSSPageSize: true
});

Para tamaños de página más personalizados, confíe en CSS @page reglas:

@page {
  size: 8.5in 11in;
  margin: 0.75in 0.5in;
}

Después de configurar el diseño, puede ajustar los elementos de diseño para lograr una apariencia pulida.

Elementos de texto y diseño

Para que el contenido sea visualmente claro y profesional, utilice estas reglas 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 obtener colores de fondo consistentes, especialmente en secciones críticas, agregue esta regla:

.color-critical {
  -webkit-print-color-adjust: exact;
}

Estos ajustes garantizan que su PDF sea fácil de leer y visualmente atractivo.

sbb-itb-23997f1

Control de salto de página

Propiedades CSS de salto de página

Gestionar eficazmente los saltos de página garantiza que el contenido fluya fluidamente entre páginas. Usa estas propiedades CSS para controlar dónde se divide el contenido:

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

Estas reglas ayudan a mantener el documento organizado y fácil de leer. Una vez configurados los saltos de página, concéntrese en configurar los encabezados y pies de página para que se ajusten a estas configuraciones.

Configuración de encabezado y pie de página

Configure encabezados y pies de página en Puppeteer para darle a su PDF un aspecto profesional:

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

Asegúrese de ajustar los márgenes para que el encabezado y el pie de página encajen correctamente sin superponerse al contenido.

Gestión de contenido de varias páginas

Con los saltos de página y los encabezados/pies de página implementados, concéntrese en gestionar el contenido en varias páginas. Un control adecuado del diseño garantiza que su documento se mantenga claro y profesional.

/* 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 tablas grandes que abarcan varias páginas, envuélvalas en un contenedor que permita saltos de línea y mantenga las filas intactas. Esto garantiza que los datos sean fáciles de seguir, incluso en conjuntos de datos extensos.

Consejo: Habilitar el printBackground Opción en Puppeteer para renderizar todos los elementos visuales, incluidos los colores de fondo y las imágenes:

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

Calidad y rendimiento de PDF

Mejorar la calidad y el rendimiento de un PDF requiere prestar atención al escalado, el manejo de imágenes y la gestión de recursos. Estos pasos garantizan que el documento final tenga un aspecto impecable y funcione eficientemente.

Métodos de escalamiento de contenido

Escalar el contenido correctamente garantiza su legibilidad y consistencia en el diseño. Puppeteer ofrece controles de escala detallados para renderizar archivos PDF:

await page.pdf({
  scale: 0.8,
  preferCSSPageSize: true,
  format: 'Letter'
});

Aquí, los valores inferiores a 1 reducen el contenido, mientras que los valores superiores a 1 lo amplían. Emparejamiento de escala con preferCSSPageSize garantiza que el PDF se adhiera a las dimensiones definidas por CSS:

@page {
  size: 8.5in 11in;
  margin: 0.5in;
}

Gestión de calidad de imagen

Elegir el formato de imagen correcto es crucial. PNG funciona bien para imágenes detalladas como gráficos y logotipos, pero puede aumentar el tamaño del archivo. JPEG es una mejor opción para fotos, mientras que WebP A menudo se convierte, lo que potencialmente aumenta aún más el tamaño del archivo.

Para mejorar la claridad de la imagen, aumente el factor de escala del dispositivo:

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

Problemas comunes y soluciones

Abordar desafíos comunes como la gestión de recursos, el tamaño de los archivos y los errores puede mejorar significativamente el rendimiento.

Gestión de Recursos
Utilice una única instancia y página del navegador para gestionar múltiples solicitudes de PDF, lo que reduce la 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);
}

Optimización del tamaño de archivo
Minimiza el tamaño del archivo eliminando elementos innecesarios y optimizando las imágenes:

await page.evaluate(() => {
  document.querySelectorAll('.no-print').forEach(el => el.remove());

  document.querySelectorAll('img').forEach(img => {
    img.loading = 'lazy';
    img.decoding = 'async';
  });
});

Gestión de errores
Implementar estrategias para manejar errores como tiempos de espera y reintentos:

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

Conclusión

El uso de Puppeteer para convertir HTML a PDF proporciona herramientas efectivas para crear documentos de calidad profesional.

Pasos clave a seguir

Aplicar la configuración de medios de impresión con page.emulateMediaType('print').
Utilice reglas CSS como page-break-inside: avoid para garantizar que elementos como las filas de la tabla permanezcan intactos.

Estas técnicas se basan en métodos de diseño y estilo anteriores y sirven como base sólida para una automatización más avanzada.

Opciones de automatización avanzadas

Puede llevar la generación de PDF a otro nivel con estas funciones de automatización adicionales:

Configuración del entorno
Configure directorios de caché y configuraciones del navegador para garantizar resultados consistentes en diferentes plataformas.
Ajustes de rendimiento
Ajuste la configuración de tiempo de espera y agregue mecanismos de reintento para mejorar la confiabilidad durante el proceso de generación.

Al implementar estos métodos en producción, incluya el manejo de errores y el registro para mantener salidas PDF consistentes y confiables.