导出为 PDF

导出为 PDF 功能允许您直接从编辑器生成 PDF 文件。

# 演示

以下演示允许您根据编辑器的内容生成 PDF 文件。 编辑文档，然后单击导出为 PDF 工具栏按钮 以将内容保存为 PDF。

# 工作原理

PDF 导出功能会收集使用 editor.getData() 方法 生成的 HTML 和 默认编辑器内容样式，以及您在配置中提供的样式。 然后，它将它们发送到 CKEditor 云服务 HTML 到 PDF 转换器服务。 该服务会生成一个 PDF 文件并将其返回给用户的浏览器，以便他们将其以 PDF 格式保存在磁盘上。

此功能的关键方面是其 配置。 为了确保生成的 PDF 与 WYSIWYG 编辑器中显示的相同内容尽可能接近，必须仔细配置该功能。

补充的 分页功能 允许您在将文档导出为 PDF 后查看分页符的位置。 借助实时预览，用户可以在编辑文档时微调输出文档的结构。 分页功能还显示页面计数并允许您在文档页面之间导航。

# 开始之前

购买许可证后，请按照以下步骤操作，如 导出为 PDF 快速入门指南 中所述

• 登录 CKEditor 生态系统客户仪表板.
• 创建用于授权所需的令牌端点.
• 安装 并 配置 CKEditor 5 导出为 PDF 插件。

# 安装

在 安装编辑器 后，将该功能添加到您的插件列表和工具栏配置中

import { ClassicEditor } from 'ckeditor5';
import { ExportPdf } from 'ckeditor5-premium-features';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ ExportPdf, /* ... */ ],
        toolbar: [ 'exportPdf', '|', /* ... */ ],
        exportPdf: {
            tokenUrl: 'https://example.com/cs-token-endpoint',
            stylesheets: [
                'path/to/editor-styles.css',
                'path/to/my-styles.css'
            ],
            fileName: 'my-file.pdf',
            converterOptions: {
                format: 'A4',
                margin_top: '20mm',
                margin_bottom: '20mm',
                margin_right: '12mm',
                margin_left: '12mm',
                page_orientation: 'portrait'
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 配置

配置是允许 HTML 到 PDF 转换器服务生成尽可能接近富文本编辑器中创建的内容的 PDF 文档的关键。

配置由 3 个主要部分组成

• The converter options 告知 HTML 到 PDF 转换器服务页面的格式（A4、Letter）、页面方向等。
• The style sheets 发送到服务。它们允许使用与在编辑器中应用于内容相同的样式来设置 PDF 文档中的内容样式。
• The content styles used in the editor 在页面上呈现时。

这些选项需要保持同步。例如

• 发送到服务的样式表必须定义与编辑器中使用的相同的排版。
• 编辑器的内容容器应该以反映转换器选项中定义的页面大小和边距的方式进行样式设置。
• 在使用编辑器的页面上定义的所有网页字体也必须发送到服务。

继续阅读以了解如何实现这一点。

# 默认配置

这是 CKEditor 5 的 PDF 导出功能的默认配置。

{
    exportPdf: {
        stylesheets: [
            'EDITOR_STYLES'
        ],
        fileName: 'document.pdf',
        converterUrl: 'https://pdf-converter.cke-cs.com/v1/convert',
        converterOptions: {
            format: 'A4',
            margin_top: '0mm',
            margin_bottom: '0mm',
            margin_right: '0mm',
            margin_left: '0mm',
            page_orientation: 'portrait',
            header_html: undefined,
            footer_html: undefined,
            header_and_footer_css: undefined,
            wait_for_network: true,
            wait_time: 0
        },
        dataCallback: ( editor ) => editor.getData()
    }
}

# EDITOR_STYLES 选项

EDITOR_STYLES 是 stylesheets 配置选项的默认值，但它不适用于 v42.0.0 中引入的新安装方法，这些方法目前在文档中显示为默认方法。我们保留它以实现向后兼容性，但由于新的设置将样式表与编辑器分开加载，因此它将不适用于此字符串。

经验法则是，如果您希望导出保留样式，始终使用编辑器的内容样式添加样式表。它们的路径取决于您的应用程序设置，例如

{
    exportPdf: {
        stylesheets: [
            './ckeditor5-content.css'
            './styles.css'
        ],
        // ...
    }
}

在上面的代码段中，我们假设这两个样式表都通过客户端的相对路径可用。例如，一些框架允许将文件放置在 public 文件夹中。

# 插件选项

对于某些用例，默认配置就足够了。正如您在上面的示例中看到的，您可以通过调整 PDF 导出插件配置来改进 PDF 文件的外观。

• config.exportPdf.stylesheets

  您可以设置应该在 HTML 到 PDF 转换期间包含的样式表的路径（相对路径或绝对 URL）。在编辑器 42.0.0 版本之前，如果您想扩展 编辑器的默认内容样式，您必须在自定义样式的路径之前传递一个特殊的 'EDITOR_STYLES' 令牌。此特殊字符串现在仅在旧版设置中受支持（使用 webpack 或 DLL 的自定义构建）。

  注意：路径的顺序很重要。如果您有自定义元素或覆盖了编辑器的默认内容样式，则您文件路径应该放在 'EDITOR_STYLES' 令牌之后。请参阅 config.exportPdf.stylesheets 文档中的示例。

• config.exportPdf.fileName

  设置生成的 PDF 文件的名称（以及扩展名）。默认名称为 document.pdf。您可以在上面的 默认配置 列表中看到它被调用。

  但是，此选项还允许使用回调来生成动态文件名。在下面的示例中，文档的标题将用作生成的 PDF 文件的文件名。

  // Dynamic file name.
  const exportPdfConfig = {
      fileName: () => {
          const articleTitle = document.querySelector( '#title' );
          return `${ articleTitle.value }.pdf`;
      }
  }
  

• config.exportPdf.converterUrl

  默认情况下，PDF 导出功能配置为使用 CKEditor 云服务 HTML 到 PDF 转换器服务来生成 PDF 文件。但是，您可以使用此选项提供本地转换器的 URL。联系我们 如果你需要这个功能。

• config.exportPdf.tokenUrl

  令牌 URL 或令牌请求函数。此字段是可选的，您应该在导出到 PDF 功能需要不同的 tokenUrl 时使用它。如果您使用 cloudServices 配置来提供相同的 tokenUrl，则可以跳过此选项。在大多数情况下，您可能希望在 cloudServices 中提供令牌，因为其他插件（如 Easy Image 或 实时协作）也将使用此令牌。在本指南中，为了明确说明需要此值，我们将它保留在 exportPdf 配置内部。

• config.exportPdf.converterOptions

  该插件允许您提供自定义的 HTML 到 PDF 转换器配置。

• config.exportPdf.dataCallback

  默认情况下，该插件使用 editor.getData() 收集发送到转换服务的 HTML。您可以使用此选项自定义编辑器的数据。例如，使用此设置可以在导出的 PDF 文件中启用 突出显示跟踪的更改。

      dataCallback: editor => editor.getData( {
          showSuggestionHighlights: true
      } ),
  

# HTML 到 PDF 转换器功能

# 图像

目前，该插件仅支持绝对 URL 以及图像的 Base64 格式。请参阅 转换器文档。

# 网页字体

如果您通过 @import 或 @font-face 声明使用网页字体，您可以将包含它们的 .css 文件的路径传递给 config.exportPdf.stylesheets。提供的路径的顺序很重要 - 您应该首先列出包含网页字体声明的样式表。如需了解更多技术细节，请查看 API 文档 和 转换器文档。

# 页眉和页脚

转换器允许您设置文档的页眉和页脚，类似于 Microsoft Word 或 Google Docs。

const converterOptions = {
    margin_top: '15mm',
    margin_bottom: '15mm',
    margin_right: '15mm',
    margin_left: '15mm',
    header_html: '<div class="styled">Header content</div>',
    footer_html: '<div class="styled-counter"><span class="pageNumber"></span></div>',
    header_and_footer_css: '#header, #footer { background: hsl(0, 0%, 95%); } .styled { font-weight: bold; text-align: center; } .styled-counter { font-size: 1em; color: hsl(0, 0%, 60%); }',
}

注意

• 为了确保页眉或页脚显示，边距必须足够大以容纳它。在上面的代码中，margin_top 对应于页眉，margin_bottom 对应于页脚。在这个例子中，这两个元素的高度都将等于 15mm。
• 您可以为页眉和页脚设置背景。要实现这一点，请在 header_and_footer_css 选项中使用 #header 或 #footer 选择器。不要在 header_html 或 footer_html 选项中使用这些 ID 以避免重复。这些元素由 HTML 到 PDF 转换器提供。

正如您在上面的示例中看到的，您甚至可以设置 pageNumber。但还有更多 - 如需了解更多信息，请参阅 转换器的文档。

# 其他

• 默认情况下，生成的 PDF 文件使用 UTF-8 编码。
• 默认情况下，转换器设置 color-adjust: exact;。这意味着您的 PDF 文档将保留颜色、图像和样式，就像您在编辑器中看到的那样。
• 生成的文档可以加水印。请参阅下面部分中的示例和演示。

# 示例

查看一些配置示例，这些示例将向您展示如何自定义导出到 PDF 功能。在第一个示例中，您将学习如何添加自定义样式。第二个示例将向您展示如何设置页面格式。在第三个示例中，您可以看到如何在配置中使用网页字体。

# 重新使用自定义编辑器样式

The default configuration of the ExportPdf plugin attaches the default editor content styles to the HTML content sent to the converter.

但是，如果您需要，您还可以设置其他 CSS 文件的路径。让我们假设您已经有一个 my-custom-editor-styles.css，其中包含您在网站上使用的编辑器内容的自定义样式，但您还想将这些样式包含在生成的 PDF 文件中。

以下是示例代码

import { ClassicEditor } from 'ckeditor5';
import { ExportPdf } from 'ckeditor5-premium-features';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ ExportPdf, /* ... */ ],
        toolbar: [ 'exportPdf', '|', /* ... */ ],
        exportPdf: {
            stylesheets: [
                'path/to/editor-styles.css',
                'path/to/my-styles.css'
            ],
            fileName: 'my-document.pdf'
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

以下是相应的编辑器样式的外观

/* my-custom-editor-styles.css */

/* Custom link color. */
.ck.ck-content a {
    color: purple;
}

/* Custom header styling. */
.ck.ck-content h1 {
    border-bottom: 2px solid;
}

/* Another custom styling... */
/* ... */

使用这些设置，生成的 PDF 文件中的内容应该具有与 WYSIWYG 编辑器中相同的样式。

# 设置页面格式

一致性是一个重要因素。为了确保编辑器内容和生成的 PDF 文件看起来相同，您需要匹配它们的格式设置。您可以更改现有的样式表或使用一个新的样式表，例如 format.css。默认情况下，CKEditor 云服务 HTML 到 PDF 转换器设置为 A4 格式，但您可以在配置中更改此设置。

假设您想要创建一个美国 Letter 格式的文档，并使用标准边距（每边 19mm），以下是您可以使用的示例代码

import { ClassicEditor } from 'ckeditor5';
import { ExportPdf } from 'ckeditor5-premium-features';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ ExportPdf, /* ... */ ],
        toolbar: [ 'exportPdf', '|', /* ... */ ],
        exportPdf: {
            stylesheets: [
                'path/to/editor-styles.css',
                'path/to/my-styles.css'
            ],
            fileName: 'my-document.pdf',
            converterOptions: {
                // Document format settings with proper margins.
                format: 'Letter',
                margin_top: '19mm',
                margin_bottom: '19mm',
                margin_right: '19mm',
                margin_left: '19mm',
                page_orientation: 'portrait'
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

现在设置相应的编辑器样式

/* format.css */

/* Styles for the editable. */
.ck.ck-content.ck-editor__editable {
    /* US Letter size. */
    width: 215.9mm;
    /* Padding is your document's margin. */
    padding: 19mm;
    /* You do not want to change the size of the editor by applying the new padding values. */
    box-sizing: border-box;
    /* ... */
}

使用这些设置，生成的 PDF 文件中的内容应该具有与编辑器中相同的美国 Letter 格式布局。

# 提供网页字体样式

这次您想在插件中添加一个网页字体。让我们假设编辑器在具有特定排版的页面上使用，因此编辑器中的内容从页面继承字体样式。因此，这些样式需要传递到 HTML 到 PDF 转换器服务。

下面的示例使用来自 Google Fonts 服务的网页字体。为了您的方便，@import 声明以及您的网站需要的任何字体样式都保存在一个单独的文件中，例如 fonts.css。

/* fonts.css */

@import url('https://fonts.googleapis.com/css2?family=Source+Sans+Pro:wght@400;700&display=swap');

html, body {
    font-family: "Source Sans Pro", sans-serif;
    /* ... */
}

/* ... */

这使您能够在插件中使用网页字体设置，而无需进行任何额外的调整。只需在 config.exportPdf.stylesheets 配置选项中传递文件的路径即可。

这里的顺序很重要。字体声明应该放在样式表数组的开头。否则，无法保证字体样式将应用于 PDF 文件。请参阅 config.exportPdf.stylesheets API 文档了解更多详细信息。

import { ClassicEditor } from 'ckeditor5';
import { ExportPdf } from 'ckeditor5-premium-features';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ ExportPdf, /* ... */ ],
        toolbar: [ 'exportPdf', '|', /* ... */ ],
        exportPdf: {
            stylesheets: [
                'path/to/fonts.css',
                'path/to/editor-styles.css',
                'path/to/my-styles.css'
            ],
            // More configuration of the export to PDF feature.
            // ...
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

由于这一点，编辑器继承了字体设置，您可以确保它们也将应用于生成的 PDF 文件。

查看 fonts.css 文件的另一个示例。假设您的网站使用 Source Sans Pro 字体，但这次您希望在 WYSIWYG 编辑器中使用 Inter 字体。该文件应该如下所示

/* fonts.css */

/* Import the web font for your website. */
@import url('https://fonts.googleapis.com/css2?family=Source+Sans+Pro:wght@400;700&display=swap');
/* Import the web font for your editor. */
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap');

/* Use the Source Sans Pro web font in your website. */
html, body {
    font-family: "Source Sans Pro", sans-serif;
    /* ... */
}

/* Use the Inter web font in your editor. */
.ck.ck-content.ck-editor__editable {
    font-family: "Inter", sans-serif;
    /* ... */
}

/* ... */

将文件设置为这样用于您的网站，并在 config.exportPdf.stylesheets 中重复使用它，可以使整个设置尽可能简单。

# 为文档添加水印

除了添加页眉和页脚之外，还可以将水印添加到生成的文档中。这可以通过利用 config.exportPdf.dataCallback 来实现。

为此，您需要首先获取正在发送到转换器的数据，并使用水印标记更新它。

exportPdf: {
    // More configuration of the export to PDF.
    // ...
    dataCallback: ( editor ) => {
        return `
            ${ editor.getData() }
            <div class="watermark">Draft document</div>
        `;
    },
    // More configuration of the export to PDF.
    // ...
}

然后 使用正确的样式更新自定义 CSS 文件

.watermark {
    font-size: 50px;
    opacity: 0.5;
    color: black;
    position: fixed;
    left: 20%;
    top: 50%;
    transform: rotate(25deg);
    letter-spacing: 10px
}

您可以在下面看到一个简化的演示，其中包含最终结果。单击 工具栏按钮以生成带有水印的文档。