ngx-export-as
Version:
[](https://badge.fury.io/js/ngx-export-as) [](https://opensource.org/licenses/MIT)
591 lines (587 loc) • 19 kB
TypeScript
import { Observable } from 'rxjs';
import * as i0 from '@angular/core';
/**
* Supported file export formats
* @type SupportedExtensions
*
* Available export formats:
* - 'pdf': Portable Document Format
* - 'png': Portable Network Graphics image
* - 'xlsx': Microsoft Excel spreadsheet (OpenXML format)
* - 'xls': Microsoft Excel spreadsheet (legacy format)
* - 'docx': Microsoft Word document (OpenXML format) - Requires target config es2015
* - 'doc': Microsoft Word document (legacy format) - Requires target config es2015
* - 'txt': Plain text file
* - 'csv': Comma-Separated Values
* - 'json': JavaScript Object Notation
* - 'xml': Extensible Markup Language
*/
type SupportedExtensions = 'pdf' | 'png' | 'xlsx' | 'xls' | 'docx' | 'doc' | 'txt' | 'csv' | 'json' | 'xml';
/**
* Configuration interface for exporting HTML/Table elements to various file formats
*
* @interface ExportAsConfig
*
* @example
* ```typescript
* const config: ExportAsConfig = {
* type: 'pdf',
* elementIdOrContent: 'myTableId',
* options: {
* filename: 'export.pdf',
* image: { type: 'jpeg', quality: 0.98 },
* html2canvas: { scale: 2 },
* jsPDF: { unit: 'in', format: 'letter', orientation: 'portrait' }
* }
* };
* ```
*/
interface ExportAsConfig {
/**
* The target export file format
* @type {SupportedExtensions}
*/
type: SupportedExtensions;
/**
* The HTML element ID or content to export
* - For element ID: pass the ID as a string (e.g., 'myTableId')
* - For PDF: can also accept HTMLElement, Canvas, Image, or raw content string
* @type {string}
*/
elementIdOrContent: string;
/**
* Whether to automatically download the file after generation
* - true: File will be downloaded automatically
* - false/undefined: File content will be returned as base64 or JSON
* @type {boolean}
* @optional
*/
download?: boolean;
/**
* The filename for the exported file (without extension)
* Extension will be added automatically based on the export type
* @type {string}
* @optional
*/
fileName?: string;
/**
* Format-specific options for customizing the export behavior
*
* Options vary by export type:
* - **PDF**: html2pdf.js options (margins, orientation, filename, jsPDF, html2canvas, pdfCallbackFn)
* - **PNG**: html2canvas options (scale, backgroundColor, logging, etc.)
* - **XLSX/XLS**: SheetJS options (bookType, sheet name, etc.)
* - **DOCX/DOC**: html-docx-js options (orientation, margins, etc.)
*
* @type {any}
* @optional
*
* @example
* ```typescript
* // PDF options
* options: {
* margin: 10,
* filename: 'myfile.pdf',
* image: { type: 'jpeg', quality: 0.98 },
* html2canvas: { scale: 2 },
* jsPDF: { unit: 'mm', format: 'a4', orientation: 'portrait' },
* pdfCallbackFn: (pdf) => {
* // Custom PDF modifications
* pdf.addPage();
* pdf.text('Header', 10, 10);
* }
* }
*
* // PNG options
* options: {
* scale: 2,
* backgroundColor: '#ffffff',
* logging: false
* }
*
* // DOCX options
* options: {
* orientation: 'landscape',
* margins: { top: '20', bottom: '20' }
* }
* ```
*/
options?: any;
}
/**
* Angular service for exporting HTML/Table elements to various file formats
*
* @description
* This service provides functionality to export HTML content, tables, or specific DOM elements
* into various file formats including PDF, PNG, Excel, Word documents, CSV, JSON, and XML.
*
* Supports both browser download and base64 content retrieval for further processing.
*
* **As of v1.21.0:** This is a standalone service - no NgModule required.
* Provide it directly in your component or app.config.ts.
*
* @export
* @class ExportAsService
*
* @example
* ```typescript
* // Standalone Component (Recommended)
* import { Component, inject } from '@angular/core';
*
* @Component({
* selector: 'app-export',
* standalone: true,
* providers: [ExportAsService]
* })
* export class ExportComponent {
* private readonly exportAsService = inject(ExportAsService);
*
* exportToPDF() {
* const config: ExportAsConfig = {
* type: 'pdf',
* elementIdOrContent: 'tableId'
* };
* this.exportAsService.save(config, 'my-export').subscribe(() => {
* console.log('Export completed');
* });
* }
* }
* ```
*
* @example
* ```typescript
* // App-wide provider (app.config.ts)
* export const appConfig: ApplicationConfig = {
* providers: [ExportAsService]
* };
* ```
*/
declare class ExportAsService {
private platformId;
/**
* Creates an instance of ExportAsService
* @param {Object} platformId - Angular platform identifier for SSR compatibility
* @memberof ExportAsService
*/
constructor(platformId: Object);
/**
* Retrieves the exported content as a base64 string or JSON object
*
* @description
* This is the main method for retrieving exported content without downloading.
* The return type varies by format:
* - Most formats: base64 encoded string
* - JSON format: returns actual JSON object (not base64)
*
* @param {ExportAsConfig} config - Export configuration object
* @returns {Observable<string | null>} Observable containing the base64 string or null
*
* @example
* ```typescript
* const config: ExportAsConfig = {
* type: 'pdf',
* elementIdOrContent: 'myTableId'
* };
*
* this.exportAsService.get(config).subscribe(content => {
* console.log('Base64 content:', content);
* // Use content for upload, preview, etc.
* });
* ```
*
* @memberof ExportAsService
*/
get(config: ExportAsConfig): Observable<string | null>;
/**
* Exports and automatically downloads the file to the user's device
*
* @description
* This method triggers an automatic download of the exported content.
* The file extension is automatically appended based on the export type.
*
* @param {ExportAsConfig} config - Export configuration object
* @param {string} fileName - The name of the file to be saved (without extension)
* @returns {Observable<string | null>} Observable that completes when download starts
*
* @example
* ```typescript
* private readonly exportAsService = inject(ExportAsService);
*
* downloadReport() {
* const config: ExportAsConfig = {
* type: 'xlsx',
* elementIdOrContent: 'dataTable',
* options: { /* SheetJS options *\/ }
* };
*
* this.exportAsService.save(config, 'quarterly-report').subscribe(() => {
* console.log('Download started');
* });
* }
* ```
*
* @memberof ExportAsService
*/
save(config: ExportAsConfig, fileName: string): Observable<string | null>;
/**
* Converts a base64 data URL string to a Blob object
*
* @description
* Extracts the MIME type and decodes the base64 string to create a Blob.
* Useful for handling binary data in browsers.
*
* @param {string} content - Base64 encoded data URL string (e.g., "data:image/png;base64,...")
* @returns {Observable<Blob>} Observable containing the Blob object
*
* @example
* ```typescript
* private readonly exportAsService = inject(ExportAsService);
*
* convertToBlob() {
* const dataUrl = 'data:image/png;base64,iVBORw0KGgo...';
* this.exportAsService.contentToBlob(dataUrl).subscribe(blob => {
* console.log('Blob size:', blob.size);
* });
* }
* ```
*
* @memberof ExportAsService
*/
contentToBlob(content: string): Observable<Blob>;
/**
* Removes the data URL prefix from a base64 string
*
* @description
* Strips the MIME type prefix (e.g., "data:text/csv;base64,") from a base64 data URL,
* leaving only the raw base64 encoded content.
*
* @param {string} fileContent - The complete base64 data URL string
* @returns {string} The raw base64 string without the data URL prefix
*
* @example
* ```typescript
* const dataUrl = 'data:text/csv;base64,SGVsbG8gV29ybGQ=';
* const base64Only = this.removeFileTypeFromBase64(dataUrl);
* // Result: 'SGVsbG8gV29ybGQ='
* ```
*
* @memberof ExportAsService
*/
removeFileTypeFromBase64(fileContent: string): string;
/**
* Adds a data URL prefix to a raw base64 string
*
* @description
* Prepends the MIME type and base64 identifier to create a valid data URL
* that can be used in browsers.
*
* @param {string} fileContent - Raw base64 encoded string
* @param {string} fileMime - MIME type (e.g., "text/csv", "image/png")
* @returns {string} Complete base64 data URL string
*
* @example
* ```typescript
* const base64 = 'SGVsbG8gV29ybGQ=';
* const dataUrl = this.addFileTypeToBase64(base64, 'text/plain');
* // Result: 'data:text/plain;base64,SGVsbG8gV29ybGQ='
* ```
*
* @memberof ExportAsService
*/
addFileTypeToBase64(fileContent: string, fileMime: string): string;
/**
* Downloads a file from a data URL
*
* @description
* Converts a base64 data URL to a Blob and initiates a browser download.
*
* @param {string} fileName - The name for the downloaded file (with extension)
* @param {string} dataURL - Base64 data URL string
* @returns {void}
*
* @example
* ```typescript
* const dataUrl = 'data:text/csv;base64,SGVsbG8gV29ybGQ=';
* this.downloadFromDataURL('myfile.csv', dataUrl);
* ```
*
* @memberof ExportAsService
*/
downloadFromDataURL(fileName: string, dataURL: string): void;
/**
* Downloads a file from a Blob object
*
* @description
* Handles file download from Blob with cross-browser support including legacy IE.
* Creates an object URL and triggers the download appropriately for each browser.
*
* @param {Blob} blob - The Blob object containing file data
* @param {string} fileName - The name for the downloaded file (with extension)
* @returns {void}
*
* @example
* ```typescript
* const blob = new Blob(['Hello World'], { type: 'text/plain' });
* this.downloadFromBlob(blob, 'hello.txt');
* ```
*
* @memberof ExportAsService
*/
downloadFromBlob(blob: Blob, fileName: string): void;
/**
* Creates and triggers a download link programmatically
*
* @private
* @description
* Creates a temporary anchor element, simulates a click to trigger download,
* and then removes the element from the DOM.
*
* @param {string} fileName - The name for the downloaded file
* @param {string} url - The object URL or data URL to download
* @returns {void}
*
* @memberof ExportAsService
*/
private saveFile;
/**
* Exports content to PDF format
*
* @private
* @description
* Uses html2pdf.js library to convert HTML content to PDF.
* Supports custom PDF manipulation via pdfCallbackFn option.
* Accepts HTMLElement, Canvas, Image, or element ID as input.
*
* @param {ExportAsConfig} config - Export configuration with PDF-specific options
* @returns {Observable<string | null>} Observable with base64 PDF data or null if downloading
*
* @example
* ```typescript
* // PDF with custom options
* config.options = {
* margin: 10,
* filename: 'report.pdf',
* image: { type: 'jpeg', quality: 0.98 },
* html2canvas: { scale: 2 },
* jsPDF: { unit: 'mm', format: 'a4', orientation: 'portrait' },
* pdfCallbackFn: (pdf) => {
* const pageCount = pdf.internal.getNumberOfPages();
* for (let i = 1; i <= pageCount; i++) {
* pdf.setPage(i);
* pdf.text('Page ' + i, 10, 10);
* }
* }
* };
* ```
*
* @memberof ExportAsService
*/
private getPDF;
/**
* Applies a custom callback function to modify the PDF before output
*
* @private
* @description
* Allows custom modifications to the PDF object (headers, footers, page numbers, etc.)
* before final rendering or download.
*
* @param {any} pdf - The html2pdf instance
* @param {Function} pdfCallbackFn - Callback function to modify the PDF
* @returns {Promise} Promise that resolves after callback execution
*
* @memberof ExportAsService
*/
private applyPdfCallbackFn;
/**
* Exports content to PNG image format
*
* @private
* @description
* Uses html2canvas library to convert HTML element to PNG image.
* Captures the visual representation of the specified DOM element.
*
* @param {ExportAsConfig} config - Export configuration with html2canvas options
* @returns {Observable<string | null>} Observable with base64 PNG data or null if downloading
*
* @example
* ```typescript
* // PNG with custom options
* config.options = {
* scale: 2, // Higher quality
* backgroundColor: '#ffffff',
* logging: false,
* useCORS: true, // For external images
* allowTaint: false
* };
* ```
*
* @memberof ExportAsService
*/
private getPNG;
/**
* Exports HTML table to CSV format
*
* @private
* @description
* Extracts data from HTML table elements (th, td) and converts to CSV format.
* Each row becomes a CSV line with comma-separated values.
* Values are quoted to handle special characters.
*
* @param {ExportAsConfig} config - Export configuration (requires table element)
* @returns {Observable<string | null>} Observable with base64 CSV data or null if downloading
*
* @example
* ```typescript
* // HTML table structure required
* <table id="myTable">
* <tr><th>Name</th><th>Age</th></tr>
* <tr><td>John</td><td>30</td></tr>
* </table>
* ```
*
* @memberof ExportAsService
*/
private getCSV;
/**
* Exports HTML table to plain text format
*
* @private
* @description
* Reuses CSV export logic but saves as .txt file extension.
* Outputs comma-separated values in plain text format.
*
* @param {ExportAsConfig} config - Export configuration (requires table element)
* @returns {Observable<string | null>} Observable with base64 text data or null if downloading
*
* @memberof ExportAsService
*/
private getTXT;
/**
* Exports HTML table to Microsoft Excel format (.xls)
*
* @private
* @description
* Uses SheetJS (xlsx library) to convert HTML table to Excel format.
* Supports both legacy .xls and modern .xlsx formats.
* The resulting file is compatible with Microsoft Excel and other spreadsheet applications.
*
* @param {ExportAsConfig} config - Export configuration with SheetJS options
* @returns {Observable<string | null>} Observable with base64 Excel data or null if downloading
*
* @example
* ```typescript
* // Excel with custom options
* config.options = {
* bookType: 'xlsx',
* sheet: 'Sheet1',
* raw: false,
* dateNF: 'yyyy-mm-dd'
* };
* ```
*
* @memberof ExportAsService
*/
private getXLS;
/**
* Exports HTML table to Microsoft Excel format (.xlsx)
*
* @private
* @description
* Alias for getXLS method. Both .xls and .xlsx use the same underlying implementation
* via SheetJS library.
*
* @param {ExportAsConfig} config - Export configuration with SheetJS options
* @returns {Observable<string | null>} Observable with base64 Excel data or null if downloading
*
* @memberof ExportAsService
*/
private getXLSX;
/**
* Exports HTML table to JSON format
*
* @private
* @description
* Converts HTML table to JSON array of objects.
* First row is treated as headers (keys), subsequent rows as data values.
* Headers are normalized (lowercase, spaces removed).
*
* **Note:** Unlike other formats, this returns actual JSON objects, not base64.
*
* @param {ExportAsConfig} config - Export configuration (requires table element)
* @returns {Observable<any[] | null>} Observable with JSON array or null if downloading
*
* @example
* ```typescript
* // HTML table:
* // | Name | Age |
* // | John | 30 |
* // | Jane | 25 |
*
* // Result:
* [
* { "name": "John", "age": "30" },
* { "name": "Jane", "age": "25" }
* ]
* ```
*
* @memberof ExportAsService
*/
private getJSON;
/**
* Exports HTML table to XML format
*
* @private
* @description
* Converts HTML table to XML structure.
* First cell of each row becomes the class name attribute,
* remaining cells become data elements.
*
* @param {ExportAsConfig} config - Export configuration (requires table element)
* @returns {Observable<string | null>} Observable with base64 XML data or null if downloading
*
* @example
* ```typescript
* // HTML table:
* // | Name | Age | City |
* // | John | 30 | NYC |
* // | Jane | 25 | Boston |
*
* // Result:
* <?xml version="1.0" encoding="UTF-8"?>
* <Root>
* <Classes>
* <Class name="John">
* <data>30</data>
* <data>NYC</data>
* </Class>
* <Class name="Jane">
* <data>25</data>
* <data>Boston</data>
* </Class>
* </Classes>
* </Root>
* ```
*
* @memberof ExportAsService
*/
private getXML;
/**
* Encodes a string to base64 with UTF-8 support
*
* @private
* @description
* Wrapper around browser's btoa() with proper UTF-8 encoding.
* Handles special characters and international text correctly.
* Uses encodeURIComponent and unescape for proper character encoding.
*
* @param {string} content - The string content to encode
* @returns {string} Base64 encoded string
*
* @memberof ExportAsService
*/
private btoa;
static ɵfac: i0.ɵɵFactoryDeclaration<ExportAsService, never>;
static ɵprov: i0.ɵɵInjectableDeclaration<ExportAsService>;
}
export { ExportAsService };
export type { ExportAsConfig, SupportedExtensions };