@ckeditor/ckeditor5-export-pdf
Version:
Export to PDF feature for CKEditor 5.
320 lines (319 loc) • 9.78 kB
TypeScript
/**
* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
*/
/**
* @module export-pdf/exportpdf
* @publicApi
*/
import { Plugin, type Editor } from 'ckeditor5/src/core.js';
import { Notification } from 'ckeditor5/src/ui.js';
import type { InitializedToken, TokenUrl } from '@ckeditor/ckeditor5-cloud-services';
import { ExportPdfUI } from './exportpdfui.js';
/**
* The export to PDF feature.
*
* It allows you to generate a PDF file directly from the editor content.
*
* For a detailed overview, check the {@glink features/converters/export-pdf export to PDF} feature documentation.
*/
export declare class ExportPdf extends Plugin {
/**
* @inheritDoc
*/
static get pluginName(): "ExportPdf";
/**
* @inheritDoc
*/
static get isOfficialPlugin(): true;
/**
* @inheritDoc
*/
static get isPremiumPlugin(): true;
/**
* @inheritDoc
*/
static get requires(): readonly ["CloudServices", typeof Notification, typeof ExportPdfUI];
/**
* @inheritDoc
*/
init(): void;
}
/**
* The configuration of the export to PDF feature. It is used by the PDF export features from the `@ckeditor/ckeditor5-export-pdf` package.
*
* ```ts
* ClassicEditor
* .create( editorElement, {
* exportPdf: ... // Export to PDF feature options.
* } )
* .then( ... )
* .catch( ... );
* ```
*
* See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
*/
export interface ExportPdfConfig {
/**
* The version of the HTML to PDF converter API.
*
* @default '1'
*/
version?: 1 | 2;
/**
* Paths to the `.css` files containing additional styling for the editor's content (**the order of provided items matters**).
*
* ```ts
* const exportPdfConfig = {
* stylesheets: [ './path/to/custom-style.css' ]
* }
* ```
*
* **NOTE:** If `stylesheets` are not provided, the plugin will sent only
* {@glink getting-started/setup/css the default editor content styles}
* to the converter.
*
* **Default editor's content styles**:
* {@glink getting-started/setup/css The default editor content styles}
* are applied to the generated PDF thanks to the `'EDITOR_STYLES'` token, which is provided to the `stylesheets` by default.
* If you don't want them to be applied, you have to omit the token:
*
* **NOTE:** The `'EDITOR_STYLES'` string is only supported in legacy custom builds with webpack or DLLs.
* In other setups you always need to pass the stylesheets.
*
* ```ts
* const exportPdfConfig = {
* stylesheets: [ './path/to/custom-editor-styles.css' ]
* }
* ```
*
* **Web fonts:** If you want to {@glink features/converters/export-pdf#providing-web-font-styles use web fonts} in your PDF document,
* you should provide a path to the file containing the web font declaration before the `'EDITOR_STYLES'` token and other style sheets:
*
* ```ts
* const exportPdfConfig = {
* stylesheets: [
* './path/to/fonts.css'
* './path/to/editor-styles.css',
* ]
* }
* ```
*
* **Web fonts and custom styling:** For more advanced styling, your configuration should look like this:
*
* ```ts
* const exportPdfConfig = {
* stylesheets: [
* './path/to/fonts.css',
* './path/to/editor-styles.css',
* './path/to/custom-styles.css'
* ]
* }
* ```
*
* @default `[ 'EDITOR_STYLES' ]`
*/
stylesheets?: Array<string>;
/**
* The name of the generated PDF file.
*
* ```ts
* // Static file name.
* const exportPdfConfig = {
* fileName: 'my-document.pdf'
* }
*
* // Dynamic file name.
* const exportPdfConfig = {
* fileName: () => {
* const articleTitle = document.querySelector( '#title' );
*
* return `${ articleTitle.value }.pdf`;
* }
* }
* ```
*
* **NOTE:** The file name must contain the `.pdf` extension.
* Otherwise your operating system or device may have trouble identifying the file type.
*
* @default 'document.pdf'
*/
fileName?: string | (() => string);
/**
* A URL to the HTML to PDF converter.
*
* ```ts
* const exportPdfConfig = {
* converterUrl: 'https://myconverter.com/v1/'
* }
* ```
*
* **NOTE:** The plugin uses the default HTML to PDF converter delivered by CKEditor Cloud Services.
* You can provide a URL to an on-premises converter instead.
*
* @default 'https://pdf-converter.cke-cs.com/v1/convert'
*/
converterUrl?: string;
/**
* The HTML to PDF converter options.
*
* **NOTE:** Configuring the plugin is not mandatory but it is highly recommended,
* especially if you want to get the most accurate results when generating the PDF file.
* To learn more, please check the [HTML to PDF converter configuration](https://pdf-converter.cke-cs.com/docs).
*
* ```ts
* const exportPdfConfig = {
* converterOptions: {
* ...
* }
* }
* ```
*
* @default `{
* format: 'A4',
* margin_top: '0',
* margin_bottom: '0',
* margin_right: '0',
* margin_left: '0',
* page_orientation: 'portrait',
* header_html: undefined,
* footer_html: undefined,
* header_and_footer_css: undefined,
* wait_for_network: true,
* wait_time: 0
* }`
*/
converterOptions?: ExportPdfConverterOptions | ExportPdfConverterOptionsV2;
/**
* A function to gather the HTML to be converted to PDF.
*
* **NOTE:** This option may be useful when the editor does not have `getData()` method,
* or if the HTML to be converted should be different than the edited one.
*
* ```ts
* const exportPdfConfig = {
* dataCallback: ( editor: Editor ) => {
* return `
* <header id="header">${ editor.data.get( { rootName: 'header' } ) }</header>
* <div id="content">${ editor.data.get( { rootName: 'content' } ) }</div>
* `;
* }
* }
* ```
*
* @default `( editor: Editor ) => editor.getData()`
*/
dataCallback?: (editor: Editor) => string;
/**
* A token URL or a token request function. This field is optional and should be used only when a different `tokenUrl` is required for
* the export to PDF feature.
*
* **Note:** The token can be disabled with the `false` value provided.
*
* See: {@link module:cloud-services/cloudservicesconfig~CloudServicesConfig#tokenUrl}
*/
tokenUrl?: TokenUrl | false;
/**
* The authentication token.
*
* See: {@link module:cloud-services/cloudservices~CloudServices#token}
*/
token?: InitializedToken;
/**
* The application unique identifier.
*/
appID?: string;
}
/**
* The HTML to PDF converter options for V1 of the converter API.
*/
export type ExportPdfConverterOptions = {
format?: ExportPdfPageFormat;
margin_top?: string;
margin_bottom?: string;
margin_right?: string;
margin_left?: string;
header_html?: string;
footer_html?: string;
header_and_footer_css?: string;
page_orientation?: 'portrait' | 'landscape' | string & Record<never, never>;
wait_for_network?: boolean;
wait_time?: number;
merge_fields?: {
prefix: string;
suffix: string;
data: Record<string, string>;
};
};
/**
* Predefined page formats used in the HTML to PDF converter.
* Supported in both V1 and V2 APIs.
*/
export type ExportPdfPageFormat = 'Letter' | 'Legal' | 'Tabloid' | 'Ledger' | 'A0' | 'A1' | 'A2' | 'A3' | 'A4' | 'A5' | 'A6' | string & Record<never, never>;
/**
* The HTML to PDF converter options for V2 of the converter API.
*/
export type ExportPdfConverterOptionsV2 = {
document?: {
size?: ExportPdfPageFormat | {
height: string;
width: string;
};
orientation?: 'portrait' | 'landscape';
margins?: {
top?: string;
bottom?: string;
left?: string;
right?: string;
enable_mirror_margins?: boolean;
};
};
headers?: {
default?: ExportPdfSectionDefinitionV2;
first?: ExportPdfSectionDefinitionV2;
odd?: ExportPdfSectionDefinitionV2;
even?: ExportPdfSectionDefinitionV2;
};
footers?: {
default?: ExportPdfSectionDefinitionV2;
first?: ExportPdfSectionDefinitionV2;
odd?: ExportPdfSectionDefinitionV2;
even?: ExportPdfSectionDefinitionV2;
};
rendering?: {
wait_for_selector?: string;
wait_for_network?: boolean;
wait_time?: number;
};
base_url?: string;
extra_http_headers?: Record<string, Record<string, string>>;
merge_fields?: {
prefix: string;
suffix: string;
data: Record<string, string>;
};
disable_compression?: boolean;
security?: {
owner_password: string;
};
signature?: {
certificate: string;
certificate_password: string;
reason?: string;
location?: string;
};
metadata?: {
title?: string;
author?: string;
subject?: string;
keywords?: Array<string>;
custom_fields?: Record<string, string>;
};
};
/**
* Definition of a section (header or footer) in V2 of the HTML to PDF converter.
*/
export type ExportPdfSectionDefinitionV2 = {
html: string;
css?: string;
};