ngx-opalbytes-feature-pdf

ngx-opalbytes-feature-pdf é uma biblioteca Angular projetada para facilitar a conversão de conteúdo HTML para documentos PDF em suas aplicações Angular. Ela fornece serviços e utilitários para exportar facilmente conteúdo dinâmico como PDFs.

Instalação

Para instalar esta biblioteca, execute o seguinte comando:

``bash
npm install ngx-opalbytes-feature-pdf
`

Dependências

Esta biblioteca possui as seguintes dependências de pacotes, que devem ser instaladas em seu projeto:

Peer Dependencies:

* @angular/common: ^21.0.0
* @angular/core: ^21.0.0
* html2canvas: ^1.4.1 (Utilizado para renderizar HTML em um canvas)
* jspdf: ^4.0.0 (Utilizado para gerar o documento PDF)

Dependencies:

* tslib: ^2.3.0 (Biblioteca de tempo de execução para TypeScript)

Utilização

$3

O ProcessoDetalhesExportService demonstra um caso de uso avançado onde um componente dinâmico (ProtocoloPdfTemplateComponent) é criado, preenchido com dados, e então exportado para PDF.

`typescript
import (
ApplicationRef,
createComponent,
EnvironmentInjector,
inject,
Injectable,
} from '@angular/core';

import { Observable } from 'rxjs';

import { CaoPdfExportService, IPdfExportOptions, IExportResult } from 'ngx-opalbytes-feature-pdf';

import { IProtocoloData } from '@domain.models/processo/protocolo-data.interface';

import { ProtocoloPdfTemplateComponent } from '@shared.components/protocolo-pdf-template/protocolo-pdf-template';

@Injectable({
providedIn: 'root',
})
export class ProcessoDetalhesExportService {
private pdfExportService = inject(CaoPdfExportService);
private appRef = inject(ApplicationRef);
private injector = inject(EnvironmentInjector);

/**
* Exporta protocolo para PDF usando template customizado
*/
exportProtocoloPdf(protocoloData: IProtocoloData): Observable {
const timestamp = new Date().toISOString().slice(0, 10);
const filename = protocolo-${protocoloData.numeroProtocolo}-${timestamp}.pdf;

const options: IPdfExportOptions = {
filename,
format: 'a4',
orientation: 'portrait',
quality: 0.95,
compress: true,
includeDate: false, // Já tem data no template
margin: {
top: 10,
right: 10,
bottom: 10,
left: 10,
},
scale: 2,
backgroundColor: '#ffffff',
};

// Criar componente dinamicamente
const componentRef = createComponent(ProtocoloPdfTemplateComponent, {
environmentInjector: this.injector,
});

// Definir os dados do protocolo
componentRef.setInput('data', protocoloData);

// Anexar ao DOM
this.appRef.attachView(componentRef.hostView);
const domElement = componentRef.location.nativeElement as HTMLElement;
document.body.appendChild(domElement);

// Aguardar um tick para garantir renderização
return new Observable((observer) => {
setTimeout(() => {
// Exportar para PDF
this.pdfExportService.exportToPdf(domElement, options, 'single-page').subscribe({
next: (result) => {
// Limpar o componente do DOM
document.body.removeChild(domElement);
this.appRef.detachView(componentRef.hostView);
componentRef.destroy();

observer.next(result);
observer.complete();
},
error: (error) => {
// Limpar o componente do DOM em caso de erro
document.body.removeChild(domElement);
this.appRef.detachView(componentRef.hostView);
componentRef.destroy();

observer.error(error);
},
});
}, 100); // 100ms para garantir renderização
});
}
}
`

Detalhes das Interfaces

$3

| Atributo | Tipo | Obrigatório | Descrição |
| :--- | :--- | :--- | :--- |
| filename | string | Sim | Nome do arquivo PDF a ser gerado. |
| format | 'a4' \| 'letter' \| 'legal'| Não | Formato da página. Padrão: 'a4'. |
| orientation | 'portrait' \| 'landscape'| Não | Orientação da página. Padrão: 'portrait'. |
| quality | number | Não | Qualidade da imagem (0 a 1) usada pelo html2canvas. Padrão: 0.95. |
| compress | boolean | Não | Se o PDF deve ser comprimido. Padrão: true. |
| includeDate| boolean | Não | Adiciona um rodapé com a data de geração. |
| margin | { top, right, bottom, left } | Não | Margens da página em mm. |
| scale | number | Não | Fator de escala para o html2canvas. Padrão: 2. |
| backgroundColor | string | Não | Cor de fundo do canvas. Padrão: '#ffffff'. |
| watermark | { text, opacity } | Não | Adiciona uma marca d'água de texto ao PDF. |

$3

| Atributo | Tipo | Obrigatório | Descrição |
| :--- | :--- | :--- | :--- |
| element | HTMLElement | Sim | O elemento HTML a ser exportado. |
| excludeSelectors| string[] | Não | Array de seletores CSS para excluir da captura. |
| includeSelectors| string[] | Não | Array de seletores CSS para incluir na captura. |

$3

| Atributo | Tipo | Descrição |
| :--- | :--- | :--- |
| status | ExportStatus | O status final da exportação (Success, Error). |
| filename | string | O nome do arquivo gerado (em caso de sucesso). |
| error | string | Mensagem de erro (em caso de falha). |
| timestamp | Date | Data e hora da conclusão da exportação. |
| size | number | Tamanho estimado do arquivo em bytes. |

$3

| Atributo | Tipo | Descrição |
| :--- | :--- | :--- |
| stage | 'capturing' \| 'converting' \| 'saving'| O estágio atual do processo de exportação. |
| progress | number | Percentual de progresso (0 a 100). |
| message | string | Mensagem descritiva do estágio atual. |

$3

| Método | Retorno | Descrição |
| :--- | :--- | :--- |
| export(element, options) | Observable| Executa a lógica de exportação para um dado elemento HTML e opções. |

---

Detalhes dos Serviços e Utilitários

$3

Funcionalidades:
* exportToPdf(element, options, type): Inicia o processo de exportação.
* element: O HTMLElement a ser exportado.
* options: IPdfExportOptions para configurar a saída.
* type: 'single-page' ou 'multi-page' para selecionar a estratégia.
* reset(): Reseta o estado do serviço para o estado inicial (Idle).

Estado Reativo (Signals):
* isExporting(): computed - Retorna true se uma exportação estiver em andamento.
* hasError(): computed - Retorna true se a última exportação resultou em erro.
* lastResult(): Signal - Contém o resultado da última exportação.
* errorMessage(): Signal - Contém a mensagem de erro da última exportação.

$3

* SinglePageExportStrategy: Estratégia para exportar conteúdo que cabe em uma única página. Ajusta as opções para otimizar para uma página.
* MultiPageExportStrategy: Estratégia padrão para conteúdo longo que pode se estender por várias páginas.

$3

Funcionalidades:
* captureHtmlToCanvas(element, options): Captura um HTMLElement e o renderiza em um usando html2canvas. Ignora elementos com a classe .no-print ou o atributo data-no-export.
* convertCanvasToPdf(canvas, options): Converte o gerado em um objeto jsPDF, lidando com paginação, margens e orientação.
* savePdf(pdf, filename): Inicia o download do arquivo PDF gerado no navegador.
* addWatermark(pdf, watermark) (privado): Adiciona uma marca d'água em todas as páginas do PDF.
* addDateFooter(pdf) (privado): Adiciona um rodapé com a data e hora de geração em todas as páginas.

Construindo a Biblioteca

Para construir a biblioteca ngx-opalbytes-feature-pdf, execute:

`bash
ng build ngx-opalbytes-feature-pdf
`

Os artefatos de construção serão armazenados no diretório dist/ngx-opalbytes-feature-pdf.

Publicando a Biblioteca

Após a construção, você pode publicar sua biblioteca no registro npm:

1. Navegue até o diretório de saída da compilação:
`bash
cd dist/ngx-opalbytes-feature-pdf
`

2. Publique usando o npm:
`bash
npm publish
``