.png)
.svg){kind=icon}
Marzo 25, 2025
•
7
min leer
Conversión de HTML a PDF con Puppeteer: Configuración de estilos y paginación
George Miloradovich
Investigador, redactor y entrevistador de casos prácticos
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:
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:
@page reglas.Con Puppeteer, puede automatizar y personalizar la generación de PDF para obtener resultados consistentes y de alta calidad.
Aprende a configurar y usar Puppeteer para generar archivos PDF. Sigue estos pasos para empezar.
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:
npm init -y.npm install puppeteer para agregar Puppeteer a tu proyecto.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.
Puppeteer ofrece múltiples formas de cargar contenido HTML para la generación de PDF:
await page.setContent(htmlString);
await page.goto(`file:${path.join(__dirname, 'template.html')}`);
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.
Para garantizar una generación de PDF fluida, tenga en cuenta estos consejos:
page.waitForNetworkIdle() esperar a que finalicen todas las solicitudes de red.Una vez que su HTML esté listo, puede pasar a personalizar los estilos y configuraciones del PDF.
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.
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.
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.
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.
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.
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
printBackgroundOpció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
});
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.
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;
}
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
});
Abordar desafíos comunes como la gestión de recursos, el tamaño de los archivos y los errores puede mejorar significativamente el rendimiento.
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;
}
};
El uso de Puppeteer para convertir HTML a PDF proporciona herramientas efectivas para crear documentos de calidad profesional.
page.emulateMediaType('print').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.
Puede llevar la generación de PDF a otro nivel con estas funciones de automatización adicionales:
Al implementar estos métodos en producción, incluya el manejo de errores y el registro para mantener salidas PDF consistentes y confiables.
