导出至 Word

导出至 Word 功能允许您直接从编辑器生成 .docx 文件。

# 演示

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

美味托斯卡纳聚会

欢迎信

尊敬的宾客：

我们很高兴欢迎您参加年度美味托斯卡纳聚会。我们希望您能享受活动安排以及在比兰奇诺酒店的住宿。

请查看附件中的完整活动日程。

年度美味托斯卡纳聚会总是充满烹饪惊喜。您可以在该地区顶级酒店之一的紧张一日游中体验托斯卡纳风味美食的精华。所有课程均由热衷于其职业的顶级厨师主导。我建议您将此日期标记在您的日历上！

安吉丽娜·卡尔维诺，美食记者

请至少提前半 个小时到达比兰奇诺酒店的前台，以确保注册过程尽可能顺利。

我们期待在活动中欢迎您。

维多利亚·瓦尔克，比兰奇诺酒店活动经理

 

 

 

美味托斯卡纳聚会日程安排

7 月 14 日星期六
上午 9:30 - 上午 11:30	美式咖啡与煮咖啡 - “了解您的咖啡”，由： 朱莉娅·奥兰达 斯特凡诺·加劳 朱塞佩·鲁索
下午 1:00 - 下午 3:00	托斯卡纳地区美食 - 现场烹饪1 加入最新鲜的食材 与丽塔·弗雷斯科
下午 5:00 - 晚上 8:00	托斯卡纳葡萄园一览 - 品酒 与弗雷德里科·里斯科利

¹ 现场烹饪课程报名需提前进行，因为座位有限。

 

# 工作原理

导出至 Microsoft Word 功能会收集使用editor.getData() 方法生成的 HTML 以及默认编辑器内容样式，以及您在配置中提供的样式。然后，它将这些内容发送到 CKEditor 云服务 HTML 到 DOCX 转换器服务。该服务会生成一个 Word 文件并将其返回给用户的浏览器，以便他们可以将其以 Word 格式保存到磁盘上。
您可以在专门的功能亮点博客文章中了解有关转换器和插件的更多信息。

您可以使用补充的 分页功能 来查看页面断开的位置（在将文档导出到 Word 之后）。但是，由于 Word 页面渲染的性质，结果可能不一致（阅读更多关于 已知问题）。您可以通过启用 auto_pagination: true 配置选项，强制 Word 中的分页断开。您也可以使用实时预览微调输出文档的结构。分页功能还显示页面计数并允许您在文档页面之间导航。

# 开始之前

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

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

# 安装

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

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

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ ExportWord, /* ... */ ],
        toolbar: [ 'exportWord', '|', /* ... */ ],
        exportWord: {
            tokenUrl: 'https://example.com/cs-token-endpoint',
            fileName: 'my-file.docx',
            converterOptions: {
                document: {
                    size: 'A4', // Default value, you do not need to specify it explicitly for A4.
                    margin: {
                        top: '20mm',
                        bottom: '20mm',
                        right: '12mm',
                        left: '12mm'
                    }
                }
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 配置

# 默认配置

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

{
    exportWord: {
        fileName: 'document.docx',
        converterUrl: 'https://docx-converter.cke-cs.com/v2/convert/html-docx',
        stylesheets: [
            'EDITOR_STYLES'
        ],
        converterOptions: {
            document: {
                size: 'A4',
                orientation: 'portrait',
                margin: {
                    top: '1in',
                    bottom: '1in',
                    right: '1in',
                    left: '1in',
                },
                language: 'en' // By default it is set to editor content language.
            },
        },
        dataCallback: ( editor ) => editor.getData( { pagination: true } )
    }
}

# EDITOR_STYLES 选项

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

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

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

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

# 插件选项

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

• config.exportWord.stylesheets

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

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

• config.exportWord.fileName

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

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

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

• config.exportWord.converterUrl

  默认情况下，Word 导出功能使用 CKEditor 云服务 HTML 到 DOCX 转换器服务来生成 Word 文件。您可以使用此选项提供本地转换器的 URL。如果您需要此功能，请 联系我们。

• config.exportWord.tokenUrl

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

• config.exportWord.converterOptions

  该插件允许您提供自定义的 CKEditor 云服务 HTML 到 DOCX 转换器配置.

• config.exportWord.dataCallback

  默认情况下，该插件使用 editor.getData( { pagination: true } ) 来收集发送到转换服务的 HTML。您可以使用此选项自定义编辑器的 数据。

  当使用 分页 功能时，pagination:true 选项会将额外的标记插入编辑器的 数据。因此，HTML 到 DOCX 转换器会创建一个类似于编辑器中显示的 Word 文档。

# 导出到 Word V1

注意：导出到 Word 默认情况下使用新版本的转换器，旧版本将不再接收更新。强烈建议迁移到 最新版本。有关从 v1 迁移到 v2 的更多详细信息，请参阅 迁移指南。要使用 v1，您需要在配置的 version 属性中指定版本，如以下代码段所示。

{
    exportWord: {
        // ...
        version: 1, // by default this is set to 2.
        converterOptions: {
            format: 'A4',
            orientation: 'portrait',
            margin_top: '1in',
            margin_bottom: '1in',
            margin_right: '1in',
            margin_left: '1in'
        },
        // ...
    }
}

// Let's keep the CSS string as a variable to avoid unnecessary string duplication.
const templateCSS = '.styled { color: #4b22aa; text-align: center; }'

const converterOptions = {
    header: [
        // Header template for all headers (without the `type` property).
        { html: '<p class="styled">Default header content</p>', css: templateCSS },
        // Header template only for the first page of the document.
        { html: '<p class="styled">First document page header content</p>', css: templateCSS, type: 'first' },
        // Header template for every even page of the document.
        { html: '<p class="styled">Every even page header content</p>', css: templateCSS, type: 'even' },
        // Header template for every odd page of the document.
        { html: '<p class="styled">Every odd page header content</p>', css: templateCSS, type: 'odd' }
    ],
    footer: [
        // Footer template for all footers (without the `type` property).
        { html: '<p class="styled">Default footer content</p>', css: templateCSS },
        // Footer template only for the first page of the document.
        { html: '<p class="styled">First document page footer content</p>', css: templateCSS, type: 'first' },
        // Footer template for every even page of the document.
        { html: '<p class="styled">Every even page footer content</p>', css: templateCSS, type: 'even' },
        // Footer template for every odd page of the document.
        { html: '<p class="styled">Every odd page footer content</p>', css: templateCSS, type: 'odd' }
    ],
}

# HTML 到 Word 转换器功能

# 样式化文档

默认情况下，导出到 Word 插件会获取编辑器内容样式并将其发送到 CKEditor 云服务 HTML 到 DOCX 转换器。您还可以通过提供外部 CSS 文件的路径来添加自定义样式。

// More editor's configuration.
// ...
exportWord: {
    fileName: 'document.docx',
    converterUrl: 'https://docx-converter.cke-cs.com/v2/convert/html-docx',
    stylesheets: [
        'path/to/editor-styles.css',
        'path/to/my-styles.css'
    ],
    // More configuration of the export to Word feature.
    // ...
}
// More editor's configuration.
// ...

# 支持的 CSS 属性

HTML 到 DOCX 转换器支持使用一组白名单属性的正确 CSS 继承。您可以使用它们来设置文档内容的样式。

您可以将以下 CSS 属性应用于以下元素：

• color
• background-color
• font-size
• font-family
• text-align

h1、h2、h3、h4、h5、h6、p、span、td、th、strong、i、u、s、sub、sup、mark。

您还可以使用 float CSS 属性定位图像，支持 left、right 和 none 值。

# 设置页面格式

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

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

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

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ ExportWord, /* ... */ ],
        toolbar: [ 'exportWord', '|', /* ... */ ],
        exportWord: {
            stylesheets: [
                'path/to/editor-styles.css',
                'path/to/my-styles.css'
            ],
            fileName: 'my-document.docx',
            converterOptions: {
                document: {
                    size: 'Letter',
                    // Document format settings with proper margins.
                    margin: {
                        top: '19mm',
                        bottom: '19mm',
                        right: '19mm',
                        left: '19mm'
                    }
                }
            }
        }
    } )
    .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 don't want to change the size of the editor by applying the new padding values. */
    box-sizing: border-box;
    /* ... */
}

通过这些设置，生成的 Word 文件中的内容应具有与编辑器中相同的 US Letter 格式布局。

# 页眉和页脚

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

const templateCSS = '.styled { color: #4b22aa; text-align: center; }'

const converterOptions = {
    headers: {
        // Header template for all headers.
        default : {
            html: '<p class="styled">Default header content</p>',
            css: templateCSS
        },
        // Header template only for the first page of the document.
        first: {
            html: '<p class="styled">First document page header content</p>',
            css: templateCSS
        },
        // Header template for every even page of the document.
        even: {
            html: '<p class="styled">Every even page header content</p>',
            css: templateCSS
        },
        // Header template for every odd page of the document.
        odd: {
            html: '<p class="styled">Every odd page header content</p>',
            css: templateCSS
        }
    },
    footers: {
        // Footer template for all footers.
        default: {
            html: '<p class="styled">Default footer content</p>',
            css: templateCSS
        },
        // Footer template only for the first page of the document.
        first: {
            html: '<p class="styled">First document page footer content</p>',
            css: templateCSS
        },
        // Footer template for every even page of the document.
        even: {
            html: '<p class="styled">Every even page footer content</p>',
            css: templateCSS
        },
        // Footer template for every odd page of the document.
        odd: {
            html: '<p class="styled">Every odd page footer content</p>',
            css: templateCSS
        }
    },
}

只有 headers 和 footers 对象，它们包含其他对象，其中键是您的页眉/页脚的 type。

关于 CSS，您可以使用与用于设置整个文档样式相同的 支持的属性 来设置 headers 和 footers 的样式。

更多详情请参考CKEditor Cloud Services HTML to DOCX 转换器文档。

如您所见，headers 和 footers 选项接受一个对象数组，用于定义特定页面类型的模板。如果您希望所有页面都使用一致的模板，则只需定义 default headers/footers 模板（**注意：**此设置故意省略了 type 属性）。

# 设置基本 URL

要启用对图像和链接的相对 URL 的正确解析，您需要传递 base_url 选项。

const conversionOptions = {
    base_url: 'https://ckeditor.npmjs.net.cn'
};

对于以下内容的编辑器内容

<p><a href="/">Our company homepage</a></p>
<p><img src="/logo.svg" alt="Our logo"></p>

此选项将导致将这些 URL 解析为其绝对形式

• / 将变为 https://ckeditor.npmjs.net.cn，
• /logo.svg 将变为 https://ckeditor.npmjs.net.cn/logo.svg。

# 评论和建议

当您的编辑器启用了协作功能（例如评论和修订跟踪）时，导出到 Word 功能将负责设置 CKEditor Cloud Services HTML to DOCX 转换器所需的配置。但是，如果您出于某种原因需要传递自己的数据，您可以通过REST API 转换器选项 完成此操作。

# 其他

• 默认情况下，生成的 Word 文件使用 UTF-8 编码。

# 已知问题

目前，并非所有 CKEditor 5 插件和功能都与导出到 Word 兼容。如果您对其中任何一项功能特别感兴趣，请随时联系我们。以下是已知问题的列表

# 使用分页功能自动分页符

浏览器引擎和 Microsoft Word 存在显著差异。因此，分页功能 在导出到 Word 中提供的分页符自动预测存在问题且容易出错。我们建议您在导出过程中查看文档结构，并手动应用分页符以保持首选结构。如果您仍然想要强制分页符，请在“导出到 Word”配置中设置 auto_pagination: true 选项。您还可以使用导出到 PDF，其中预测分页符更加直接且工作更加一致。

# 不支持的插件

• 媒体嵌入 – 嵌入式媒体将不会包含在导出的文档中。
• MathType – 部分支持。插件解析数据但不解释格式，导致一些数学运算符丢失，并且在有效文件中没有复制可用的等式。

# 不支持的功能

• 内联和块格式建议 – 这些建议不包含在导出的文档中。
• 应用于整个小部件（如表格）的评论 – 这些评论不包含在导出的文档中。

# 相关功能

• 补充的分页功能 提供文档分页符的实时预览，确保输出文档的外观正确。
• 如果您希望将您的内容导出为便携式、通用格式，则使用导出到 PDF 功能将允许您从编辑器创建的内容中生成 PDF 文件。

# 通用 API

ExportWord 插件注册

• 'exportWord' 按钮。

• 由ExportWordCommand 实现的 'exportWord' 命令。

  您可以使用editor.execute() 方法执行该命令。但是，如果您想直接使用该命令（而不是通过工具栏按钮），您需要指定选项 或从配置中收集这些选项。否则，该命令将无法正常执行。

  直接使用该命令的示例代码如下所示

  // Start generating a Word file based on the editor content and the plugin configuration.
  const config = editor.config.get( 'exportWord' );
  editor.execute( 'exportWord', config );