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

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

Introducción a Puppeteer

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

Configuración

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:

<span class="hljs-keyword">const</span> puppeteer = <span class="hljs-built_in">require</span>(<span class="hljs-string">'puppeteer'</span>);

<span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span> <span class="hljs-title function_">generatePDF</span>(<span class="hljs-params"></span>) {
  <span class="hljs-keyword">const</span> browser = <span class="hljs-keyword">await</span> puppeteer.<span class="hljs-title function_">launch</span>();
  <span class="hljs-keyword">const</span> page = <span class="hljs-keyword">await</span> browser.<span class="hljs-title function_">newPage</span>();

  <span class="hljs-comment">// Set page content</span>
  <span class="hljs-keyword">await</span> page.<span class="hljs-title function_">setContent</span>(<span class="hljs-string">`
    <html>
      <body>
        <h1>Sample PDF Document</h1>
        <p>Generated with Puppeteer</p>
      </body>
    </html>
  `</span>);

  <span class="hljs-comment">// Generate PDF</span>
  <span class="hljs-keyword">await</span> page.<span class="hljs-title function_">pdf</span>({
    <span class="hljs-attr">path</span>: <span class="hljs-string">'output.pdf'</span>,
    <span class="hljs-attr">format</span>: <span class="hljs-string">'Letter'</span>,
    <span class="hljs-attr">margin</span>: {
      <span class="hljs-attr">top</span>: <span class="hljs-string">'1in'</span>,
      <span class="hljs-attr">right</span>: <span class="hljs-string">'1in'</span>,
      <span class="hljs-attr">bottom</span>: <span class="hljs-string">'1in'</span>,
      <span class="hljs-attr">left</span>: <span class="hljs-string">'1in'</span>
    }
  });

  <span class="hljs-keyword">await</span> browser.<span class="hljs-title function_">close</span>();
}

<span class="hljs-title function_">generatePDF</span>();

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.

<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">setContent</span>(htmlString);

Acceso a archivos locales:Cargue un archivo HTML desde su sistema local.

<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">goto</span>(<span class="hljs-string">`file:<span class="hljs-subst">${path.join(__dirname, <span class="hljs-string">'template.html'</span>)}</span>`</span>);

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

<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">goto</span>(<span class="hljs-string">'https://yourwebsite.com/page-to-convert'</span>);

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:

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

<span class="hljs-keyword">@media</span> print {
  <span class="hljs-comment">/* Hide navigation menus and non-essential elements */</span>
  <span class="hljs-selector-tag">nav</span>, <span class="hljs-selector-tag">button</span>, <span class="hljs-selector-class">.no-print</span> {
    <span class="hljs-attribute">display</span>: none;
  }

  <span class="hljs-comment">/* Adjust text for better readability in PDFs */</span>
  <span class="hljs-selector-tag">body</span> {
    <span class="hljs-attribute">font-size</span>: <span class="hljs-number">12pt</span>;
    <span class="hljs-attribute">line-height</span>: <span class="hljs-number">1.5</span>;
  }

  <span class="hljs-comment">/* Ensure accurate background rendering */</span>
  * {
    -webkit-<span class="hljs-attribute">print-color-adjust</span>: 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:

<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">emulateMediaType</span>(<span class="hljs-string">'screen'</span>);

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:

<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">pdf</span>({
  <span class="hljs-attr">format</span>: <span class="hljs-string">'Letter'</span>,
  <span class="hljs-attr">margin</span>: {
    <span class="hljs-attr">top</span>: <span class="hljs-string">'0.75in'</span>,
    <span class="hljs-attr">right</span>: <span class="hljs-string">'0.5in'</span>,
    <span class="hljs-attr">bottom</span>: <span class="hljs-string">'0.75in'</span>,
    <span class="hljs-attr">left</span>: <span class="hljs-string">'0.5in'</span>
  },
  <span class="hljs-attr">landscape</span>: <span class="hljs-literal">false</span>,
  <span class="hljs-attr">preferCSSPageSize</span>: <span class="hljs-literal">true</span>
});

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

<span class="hljs-keyword">@page</span> {
  size: <span class="hljs-number">8.5in</span> <span class="hljs-number">11in</span>;
  <span class="hljs-attribute">margin</span>: <span class="hljs-number">0.75in</span> <span class="hljs-number">0.5in</span>;
}

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:

<span class="hljs-selector-tag">body</span> {
  <span class="hljs-attribute">font-family</span>: <span class="hljs-string">'Arial'</span>, sans-serif;
  <span class="hljs-attribute">color</span>: <span class="hljs-number">#333333</span>;
}

<span class="hljs-selector-tag">h1</span>, <span class="hljs-selector-tag">h2</span>, <span class="hljs-selector-tag">h3</span> {
  <span class="hljs-attribute">page-break-after</span>: avoid;
  <span class="hljs-attribute">color</span>: <span class="hljs-number">#000000</span>;
}

<span class="hljs-selector-tag">table</span> {
  <span class="hljs-attribute">width</span>: <span class="hljs-number">100%</span>;
  <span class="hljs-attribute">border-collapse</span>: collapse;
  <span class="hljs-attribute">page-break-inside</span>: avoid;
}

<span class="hljs-selector-tag">img</span> {
  <span class="hljs-attribute">max-width</span>: <span class="hljs-number">100%</span>;
  <span class="hljs-attribute">height</span>: auto;
  <span class="hljs-attribute">page-break-inside</span>: avoid;
}

Para obtener colores de fondo consistentes, especialmente en secciones críticas, agregue esta regla:

<span class="hljs-selector-class">.color-critical</span> {
  -webkit-<span class="hljs-attribute">print-color-adjust</span>: 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:

<span class="hljs-comment">/* Start new page before chapters */</span>
<span class="hljs-selector-class">.chapter</span> {
  <span class="hljs-attribute">page-break-before</span>: always;
}

<span class="hljs-comment">/* Keep headings together with their content */</span>
<span class="hljs-selector-tag">h2</span>, <span class="hljs-selector-tag">h3</span> {
  <span class="hljs-attribute">page-break-after</span>: avoid;
}

<span class="hljs-comment">/* Avoid splitting tables or figures */</span>
<span class="hljs-selector-tag">table</span>, <span class="hljs-selector-tag">figure</span> {
  <span class="hljs-attribute">page-break-inside</span>: 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:

<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">pdf</span>({
  <span class="hljs-attr">displayHeaderFooter</span>: <span class="hljs-literal">true</span>,
  <span class="hljs-attr">headerTemplate</span>: <span class="hljs-string">`
    <div style="font-size: 10px; padding: 0 0.5in; width: 100%;">
      <span class="title"></span>
      <span class="date" style="float: right;"></span>
    </div>
  `</span>,
  <span class="hljs-attr">footerTemplate</span>: <span class="hljs-string">`
    <div style="font-size: 10px; text-align: center; width: 100%;">
      Page <span class="pageNumber"></span> of <span class="totalPages"></span>
    </div>
  `</span>,
  <span class="hljs-attr">margin</span>: {
    <span class="hljs-attr">top</span>: <span class="hljs-string">'1in'</span>,
    <span class="hljs-attr">bottom</span>: <span class="hljs-string">'1in'</span>
  }
});

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.

<span class="hljs-comment">/* Keep captions with their images */</span>
<span class="hljs-selector-tag">figure</span> {
  <span class="hljs-attribute">display</span>: table;
  <span class="hljs-attribute">page-break-inside</span>: avoid;
}

<span class="hljs-selector-tag">figcaption</span> {
  <span class="hljs-attribute">display</span>: table-caption;
  <span class="hljs-attribute">caption-side</span>: bottom;
}

<span class="hljs-comment">/* Avoid splitting list items or table rows */</span>
<span class="hljs-selector-tag">li</span>, <span class="hljs-selector-class">.table-row</span> {
  <span class="hljs-attribute">page-break-inside</span>: avoid;
}

<span class="hljs-comment">/* Allow large tables to break across pages */</span>
<span class="hljs-selector-class">.table-wrapper</span> {
  <span class="hljs-attribute">page-break-inside</span>: 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: Active la característica de printBackground Opción en Puppeteer para renderizar todos los elementos visuales, incluidos los colores de fondo y las imágenes:

<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">pdf</span>({
  <span class="hljs-attr">printBackground</span>: <span class="hljs-literal">true</span>,
  <span class="hljs-attr">preferCSSPageSize</span>: <span class="hljs-literal">true</span>
});

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:

<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">pdf</span>({
  <span class="hljs-attr">scale</span>: <span class="hljs-number">0.8</span>,
  <span class="hljs-attr">preferCSSPageSize</span>: <span class="hljs-literal">true</span>,
  <span class="hljs-attr">format</span>: <span class="hljs-string">'Letter'</span>
});

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:

<span class="hljs-keyword">@page</span> {
  size: <span class="hljs-number">8.5in</span> <span class="hljs-number">11in</span>;
  <span class="hljs-attribute">margin</span>: <span class="hljs-number">0.5in</span>;
}

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:

<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">setViewport</span>({
  <span class="hljs-attr">width</span>: <span class="hljs-number">1200</span>,
  <span class="hljs-attr">height</span>: <span class="hljs-number">800</span>,
  <span class="hljs-attr">deviceScaleFactor</span>: <span class="hljs-number">2</span>
});

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:

<span class="hljs-keyword">const</span> browser = <span class="hljs-keyword">await</span> puppeteer.<span class="hljs-title function_">launch</span>({
  <span class="hljs-attr">args</span>: [<span class="hljs-string">'--no-sandbox'</span>, <span class="hljs-string">'--disable-setuid-sandbox'</span>]
});

<span class="hljs-keyword">const</span> page = <span class="hljs-keyword">await</span> browser.<span class="hljs-title function_">newPage</span>();
<span class="hljs-keyword">for</span> (<span class="hljs-keyword">const</span> request <span class="hljs-keyword">of</span> requests) {
  <span class="hljs-keyword">await</span> <span class="hljs-title function_">generatePDF</span>(page, request);
}

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

<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">evaluate</span>(<span class="hljs-function">() =></span> {
  <span class="hljs-variable language_">document</span>.<span class="hljs-title function_">querySelectorAll</span>(<span class="hljs-string">'.no-print'</span>).<span class="hljs-title function_">forEach</span>(<span class="hljs-function"><span class="hljs-params">el</span> =></span> el.<span class="hljs-title function_">remove</span>());

  <span class="hljs-variable language_">document</span>.<span class="hljs-title function_">querySelectorAll</span>(<span class="hljs-string">'img'</span>).<span class="hljs-title function_">forEach</span>(<span class="hljs-function"><span class="hljs-params">img</span> =></span> {
    img.<span class="hljs-property">loading</span> = <span class="hljs-string">'lazy'</span>;
    img.<span class="hljs-property">decoding</span> = <span class="hljs-string">'async'</span>;
  });
});

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

<span class="hljs-keyword">const</span> <span class="hljs-title function_">generatePDF</span> = <span class="hljs-keyword">async</span> (<span class="hljs-params">page, options</span>) => {
  <span class="hljs-keyword">try</span> {
    <span class="hljs-keyword">await</span> page.<span class="hljs-title function_">goto</span>(options.<span class="hljs-property">url</span>, {
      <span class="hljs-attr">waitUntil</span>: <span class="hljs-string">'networkidle0'</span>,
      <span class="hljs-attr">timeout</span>: <span class="hljs-number">30000</span>
    });
    <span class="hljs-keyword">return</span> <span class="hljs-keyword">await</span> page.<span class="hljs-title function_">pdf</span>(options);
  } <span class="hljs-keyword">catch</span> (error) {
    <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'PDF generation failed:'</span>, error);
    <span class="hljs-keyword">throw</span> 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.