nginstack

Class: HtmlToPdf

@nginstack/engine/lib/print/HtmlToPdf~ HtmlToPdf

new HtmlToPdf()

Classe que permite gerar um PDF a partir de um HTML.

Atualmente a geração é realizada por meio do chrome-headless-shell, que é uma versão do Chrome sem interface gráfica voltada para automação e execução de testes. Uma versão considerada estável do chrome-headless-shell é descarregada e instalada automaticamente pelo sistema no primeiro uso da classe HtmlToPdf.

A implementação atual da classe HtmlToPdf é mais moderna e robusta que a anterior, baseada no wkhtmltopdf. A versão anterior ainda está disponível por meio do módulo @nginstack/engine/lib/print/WkHtmlToPdf.js, mas o seu uso é desencorajado. A implementação legada não recebe mais manutenção, estando sujeita a falhas de segurança e compatibilidade com novas funcionalidades do HTML e CSS. O módulo legado deve ser utilizado apenas nos casos onde o uso da nova implementação apresente incompatibilidades que não possam ser resolvidas com ajustes de HTML e CSS, e apenas de forma transitória, pois ele será removido em versões futuras do sistema.

Uma das diferenças significativas entre as duas implementações é que a versão antiga implementa uma redução automática de conteúdo, enquanto a nova versão, baseada no Chrome, não possui essa funcionalidade, sendo mais fiel ao conteúdo original. Essa redução automática podia gerar resultados indesejados e não raramente era desativada por meio da flag "--disable-smart-shrinking". Códigos que não desativavam essa funcionalidade e precisam reduzir a quantidade de páginas dos PDFs gerados podem utilizar a propriedade #scale para ajustar manualmente a escala do conteúdo gerado. Valores próximos de 0.78 tendem a gerar resultados semelhantes aos obtidos com a versão legada.

Members

copies :number

Configura o número de copias das páginas a serem impressas no documento.

Type:
  • number

extraArguments :string

Argumentos de customização no formato de flags do WkHtmlToPdf, separados por espaço.

Esta é uma propriedade legada mantida apenas para facilitar a migração de códigos existentes que utilizam a implementação baseada no WkHtmlToPdf. Ao atribuir um valor a esta propriedade, as demais propriedades do objeto são atualizadas imediatamente com base nas flags informadas. Modificações realizadas nas propriedades após a atribuição se sobrepõem à definição de extraArguments.

As flags suportadas e as propriedades equivalentes são:

Flag Propriedade equivalente
--zoom n #scale
--orientation portrait|landscape #orientation
--page-size a4|a3|letter|legal|ledger|b4|b5 #pageSize
--page-width n #pageWidth
--page-height n #pageHeight
-L n ou --margin-left n #marginLeft
-R n ou --margin-right n #marginRight
-T n ou --margin-top n #marginTop
-B n ou --margin-bottom n #marginBottom
--footer-left template #footerTemplate
--footer-center template #footerTemplate
--footer-right template #footerTemplate
--footer-font-size n #footerTemplate
--footer-spacing n #marginBottom
--header-left template #headerTemplate
--header-center template #headerTemplate
--header-right template #headerTemplate
--header-font-size n #headerTemplate

Os templates de rodapé e cabeçalho aceitam os tokens [page], [toPage], [date], [title] e [url], que são convertidos para as classes CSS equivalentes do Chrome (ver #footerTemplate).

As flags --disable-smart-shrinking, --images e -q são ignoradas silenciosamente, pois indicam o comportamento padrão da nova implementação. Flags não reconhecidas geram um aviso no log e são ignoradas.

Type:
  • string
Deprecated:
  • Yes

footerTemplate :string|null

Template HTML do rodapé exibido em todas as páginas do PDF.

O template é um fragmento HTML que pode utilizar as seguintes classes CSS para inserir valores dinâmicos:

Classe CSS Valor inserido
pageNumber Número da página atual
totalPages Número total de páginas
date Data de impressão
title Título do documento
url URL da página

O template deve conter o estilo embutido necessário para a formatação desejada, pois o Chrome não aplica estilos externos ao rodapé. Quando definido, a exibição do rodapé é ativada automaticamente (equivalente a definir #showHeaderFooter como true).

Type:
  • string | null
Example
const HtmlToPdf = require('@nginstack/engine/lib/print/HtmlToPdf');

const pdf = new HtmlToPdf();
pdf.footerTemplate =
  '<div style="font-size:9px; width:100%; text-align: right; padding-right: 10mm">' +
    '<span class="pageNumber"></span>/<span class="totalPages"></span>' +
  '</div>';

grayscale :boolean

Indica se deve imprimir em escala de cinza.

Type:
  • boolean

headerTemplate :string|null

Template HTML do cabeçalho exibido em todas as páginas do PDF.

Aceita as mesmas classes CSS dinâmicas que #footerTemplate. O template deve conter o estilo embutido necessário para a formatação desejada, pois o Chrome não aplica estilos externos ao cabeçalho. Quando definido, a exibição do cabeçalho é ativada automaticamente (equivalente a definir #showHeaderFooter como true).

Type:
  • string | null
Example
const HtmlToPdf = require('@nginstack/engine/lib/print/HtmlToPdf');

const pdf = new HtmlToPdf();
pdf.headerTemplate =
  '<div style="font-size: 9px; width:100%; text-align:center">' +
    '<span class="title"></span>' +
  '</div>';

marginBottom :string|number|null

Margem inferior da página.

Os valores podem ser expressos como número (tratado como milímetros) ou como string com unidade: '10mm', '1cm', '0.4in', '28pt' ou '38px'. Quando null, o Chrome utiliza a margem padrão de aproximadamente 1 cm.

Type:
  • string | number | null

marginLeft :string|number|null

Margem esquerda da página.

Os valores podem ser expressos como número (tratado como milímetros) ou como string com unidade: '10mm', '1cm', '0.4in', '28pt' ou '38px'. Quando null, o Chrome utiliza a margem padrão de aproximadamente 1 cm.

Type:
  • string | number | null

marginRight :string|number|null

Margem direita da página.

Os valores podem ser expressos como número (tratado como milímetros) ou como string com unidade: '10mm', '1cm', '0.4in', '28pt' ou '38px'. Quando null, o Chrome utiliza a margem padrão de aproximadamente 1 cm.

Type:
  • string | number | null

marginTop :string|number|null

Margem superior da página.

Os valores podem ser expressos como número (tratado como milímetros) ou como string com unidade: '10mm', '1cm', '0.4in', '28pt' ou '38px'. Quando null, o Chrome utiliza a margem padrão de aproximadamente 1 cm.

Type:
  • string | number | null

orientation :string

Configura a orientação da impressão em retrato ou paisagem. Valores possíveis: 'portrait' ou 'landscape'. O valor padrão é 'portrait'.

Type:
  • string

pageHeight :string|number|null

Altura personalizada da página. Não pode ser configurada ao mesmo tempo que #pageSize.

Os valores podem ser expressos como número (tratado como milímetros) ou como string com unidade: '297mm', '29.7cm', '11.69in', '842pt' ou '1123px'. Deve ser configurada em conjunto com #pageWidth.

Type:
  • string | number | null

pageSize :string

Configura o tamanho da página. Valores possíveis: 'A4', 'A3', 'B4', 'B5', 'letter', 'legal' ou 'ledger'. O valor padrão é 'A4'.

Valor Largura Altura
'A4' 210 mm 297 mm
'A3' 297 mm 420 mm
'B4' 250 mm 353 mm
'B5' 176 mm 250 mm
'letter' 215,9 mm 279,4 mm
'legal' 215,9 mm 355,6 mm
'ledger' 431,8 mm 279,4 mm

Não pode ser configurado ao mesmo tempo que #pageWidth e #pageHeight.

Type:
  • string

pageWidth :string|number|null

Largura personalizada da página. Não pode ser configurado ao mesmo tempo que #pageSize.

Os valores podem ser expressos como número (tratado como milímetros) ou como string com unidade: '210mm', '21cm', '8.27in', '595pt' ou '794px'. Deve ser configurado em conjunto com #pageHeight.

Type:
  • string | number | null
Example
const HtmlToPdf = require('@nginstack/engine/lib/print/HtmlToPdf');

const pdf = new HtmlToPdf();
pdf.pageWidth = '210mm';  // largura A4
pdf.pageHeight = '297mm'; // altura A4

scale :number

Configura a escala de impressão.

O valor 1 é o tamanho original do conteúdo. Valores menores que 1 reduzem o tamanho do conteúdo, enquanto valores maiores aumentam. Por exemplo, o valor 0.5 reduz o conteúdo para metade do tamanho original e o valor 2 dobra o tamanho do conteúdo. O valor padrão é 1.

Type:
  • number
Example
const HtmlToPdf = require('@nginstack/engine/lib/print/HtmlToPdf');

const htmlToPdf = new HtmlToPdf();
htmlToPdf.scale = 0.8; // Reduz o conteúdo para 80% do tamanho original

showBackground :boolean

Indica se o fundo das páginas HTML deve ser impresso. O valor padrão é true.

Type:
  • boolean

showHeaderFooter :boolean

Indica se o cabeçalho e o rodapé devem ser exibidos no PDF. O valor padrão é false.

Quando #headerTemplate ou #footerTemplate são definidos, esta propriedade é ativada automaticamente. Use esta propriedade explicitamente apenas quando quiser exibir os templates padrão do Chrome (data no cabeçalho e número de página no rodapé) sem definir templates personalizados.

Type:
  • boolean

timeout :number

Configura o tempo em milissegundos de espera para execução do comando de impressão. Se o processo de impressão não terminar dentro desse intervalo, ocorre um erro de "timeout". Por padrão se considera um tempo de espera de 3 minutos (180000 ms).

Type:
  • number

title :string

Configura título do PDF. Se vazio, a tag "title" da primeira página é utilizada como título.

Type:
  • string

Methods

addPage(filePath)

Adiciona uma página ao conjunto de impressão, informando o caminho do arquivo HTML.

Parameters:
Name Type Description
filePath string

Caminho do arquivo Html.
Example
const HtmlToPdf = require('@nginstack/engine/lib/print/HtmlToPdf.js');

 const pdf = new HtmlToPdf();
 pdf.addPage('./caminho/pagina.html');
 pdf.print('arquivo.pdf');

addPageContent(fileName, content)

Adiciona uma página ao conjunto de impressão, informando nome e conteúdo da página HTML. Utilize esse método quando a página for gerada pela aplicação e não existir em disco, ou quando for um arquivo da Virtual File System.

Parameters:
Name Type Description
fileName string

Nome do arquivo HTML.
content UInt8Array | ArrayBuffer | string

Conteúdo do arquivo HTML.
Example
const HtmlToPdf = require('@nginstack/engine/lib/print/HtmlToPdf');
const pdf = new HtmlToPdf();
pdf.addPageContent('test.html', htmlContent);
pdf.print('test.pdf');

addResource(filePath)

Adiciona um arquivo de recurso, como uma imagem ou arquivo CSS, no diretório temporário de geração do PDF, permitindo que ele possa ser referenciado pelas páginas HTML por meio do nome do arquivo.

Parameters:
Name Type Description
filePath string

Caminho do arquivo de recurso.
Example
const HtmlToPdf = require('@nginstack/engine/lib/print/HtmlToPdf.js');

 const pdf = new HtmlToPdf();
 pdf.addPage('./caminho/pagina.html');
 pdf.addResource('./caminho/imagem.png');
 pdf.print('arquivo.pdf');

addResourceContent(fileName, content)

Adiciona um arquivo de recurso, que será carregado por uma página HTML. Utilize esse método quando o recurso for gerado dinamicamente pela aplicação e não existir em disco, ou quando for um arquivo da Virtual File System.

Parameters:
Name Type Description
fileName string

Nome do arquivo de recurso.
content UInt8Array | ArrayBuffer | string

Conteúdo do arquivo de recurso.
Example
const HtmlToPdf = require('@nginstack/engine/lib/print/HtmlToPdf.js');

const pdf = new HtmlToPdf();
const htmlContent =
  '<html><head><link rel="stylesheet" href="style.css"></head>' +
  '<body>' +
  '<h1>Imagem de exemplo</h1><img src="image.jpeg">' +
  '</body>' +
  '</html>';
pdf.addPageContent('test.html', htmlContent);
pdf.addResourceContent('style.css', 'h1 { color: #4b6b3d; } img { max-width: 100%; }');
pdf.addResourceContent('image.jpeg', virtualFS.getFileContent(imageKey));
pdf.print('test.pdf');

print(outputPath)

Cria um PDF a partir das páginas HTML adicionadas previamente pelos métodos addPage e addPageContent. O PDF gerado será gravado no caminho especificado por outputPath.

Parameters:
Name Type Description
outputPath string

Caminho do arquivo PDF de saída.