从 Word 导入

从 Word 导入功能允许您将 .docx（Word 文档）或 .dotx（Word 模板）文件导入编辑器。此过程保留格式和富媒体，以及 评论 和 跟踪更改（如果启用了这些功能）。

# 演示

下面的演示允许您将 Word 文件导入编辑器。要测试该功能，请下载 示例 Word 文档。使用从 Word 工具栏按钮 并选择下载的文件。该文件的内容将出现在编辑器中。

# 其他功能信息

从 Word 导入功能将选定的 Word 文件发送到 CKEditor 云服务 DOCX 到 HTML 转换器服务。该服务返回从上传的文件生成的 HTML 代码，然后将其插入编辑器内容，以替换文档选择。

即使 CKEditor 5 提供了专门的 分页插件，但它不能用于反映从 Word 导入的内容中的原始页面划分。这是一个仅限导出的功能。

# 导入样式

CKEditor 5 支持两种从 Word 导入样式的策略

1. 使用 CKEditor 5 中定义的样式。
2. 使用 Word 中定义的样式。

使用哪种方法取决于您的使用案例。能够选择保留还是丢弃 Word 本地样式为您提供了极大的灵活性。它还允许您根据您的特定需求调整服务。

# 使用 CKEditor 中定义的样式

从 Word 导入功能预先配置为保留在 CKEditor 5 的实现中定义的样式或由最终用户直接应用的样式。这意味着它将保留基本文本样式（如粗体或斜体）、标题、图像、表格和整体文档结构。同时，它将允许编辑器将 CKEditor 5 使用的样式应用于导入的内容，以便进行更通用的格式设置，例如字体系列、字体大小、段落间距等，如果未设置。

这样，您就可以将文件内容导入编辑器，并且它在视觉上与已经存在的内容没有区别。当格式需要遵循公司准则或品牌手册时，这很有用。通过这种方法，导入可以将语义上接近的格式保持到现有内容。

# 使用 Microsoft Word 中定义的样式

转换器有一个选项可以启用导入整个 Word 文档样式。在这种方法中，为整个文档设置的 Word 默认内容格式都包含在导入中，并尽可能保留（在 CKEditor 5 功能插件的支持范围内）。Word 以特定方式应用样式，用户可以选择保留这些样式。

要使转换器以这种方式工作，您应该将 default_styles 选项设置为 true。当用户只需要在浏览器中编辑 Word 文档，并且需要跨平台互操作性时，这最有用。您可以将其称为“完整的 Word 编辑体验”。但是，集成者仍然可以通过适当的 CKEditor 5 配置来决定保留哪些样式。

# 从 Office 粘贴与从 Word 导入

“从 Office 粘贴” 功能允许您将内容从 Microsoft Word 粘贴到 CKEditor 5 的 WYSIWYG 编辑器中，并保留原始的结构和格式。在 Microsoft Word 中创建文档后，您可以将其复制到 CKEditor 5 中，并保留基本的文本样式、标题级别、链接、列表、表格和图像（如果这些功能受已安装的 CKEditor 5 插件支持）。例如，如果编辑器实例中没有明确开启字体颜色，它们将被删除。此操作快速简便，但只能手动完成。

然而，“从 Word 导入” 功能更为高级。首先，您可以将其自动化，并且不需要 CKEditor 5 编辑器或人工监督来转换文件。您可以在服务中提供文件，并在更大的流程中自动转换它们。

虽然“从 Office 粘贴” 功能只能保留编辑器实例支持的格式，但此限制并不影响“从 Word 导入” 服务。您可以在“专用比较指南” 中阅读有关差异和特定支持功能的更多信息。

# 自动内容过滤

由于 CKEditor 5 的 自定义数据模型，编辑器只会保留其插件处理的内容。这保证了 CKEditor 5 提供的输出将是干净且语义化的。

但是，这也意味着您可能需要在富文本编辑器中启用一些额外的插件，以防止剥离内容或格式（例如，字体系列和字体大小 功能用于处理字体格式）。

# base64 图片和内容安全策略

如果您使用“从 Word 导入” 插件，但没有自定义上传器，则内容安全策略 (CSP) 可能出于安全原因阻止导入 base64 图片。这将导致控制台中出现类似于以下错误：

Refused to connect to `data:image/jpeg:base64,/xxxxx utills.js:43 xxxxx` because it violates the documents Content Security Policy.

在这种情况下，您应该尝试使用现成的上传解决方案，例如 CKBox 或 Easy Image。您也可以考虑更改 CSP 指令。

# 评论和修订

“从 Word 导入” 功能支持包含评论和修订的 Word 文件。只要您的 CKEditor 5 预设包含“评论” 和“修订” 功能，这些内容就会被导入。

从 Word 文件导入的所有评论和建议将使用 Word 文件中的相同作者姓名。它们还将包含一个特殊的标签，告知特定项目来自外部来源。

在“评论演练” 指南中阅读有关“从 Word 导入” 功能与“评论” 功能之间集成的更多信息。

如果您的 CKEditor 5 预设不包含“修订” 功能，内容将被导入，就像所有修订都被接受一样（与显示模式中的“无标记” 相同）。

# 开始之前

您可以在预览模式下尝试“从 Word 导入” 功能，而无需有效的许可证。它将导入一部分文档，并将其余内容替换为“Lorem ipsum” 文本占位符。

购买许可证后，请按照“从 Word 导入快速入门指南” 中所述的步骤操作。

• 登录 CKEditor 生态系统客户仪表板。.
• 创建授权所需的令牌端点。.

# 安装

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

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

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ ImportWord, /* ... */ ],
        toolbar: [ 'importWord', /* ... */ ], // Depending on your preference.
        importWord: {
            // Import from Word configuration.
            // ...
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 配置

您可以通过“config.importWord” 对象配置该功能。

# 提供令牌 URL

“从 Word 导入” 功能需要在“config.importWord.tokenUrl” 键中配置令牌端点 URL。如果未明确提供，则使用“config.cloudServices.tokenUrl” 中的令牌 URL。如果两者都提供，则“config.importWord.tokenUrl” 中定义的令牌 URL 优先于“config.cloudServices.tokenUrl”。

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

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ ImportWord, /* ... */ ],
        toolbar: [ 'importWord', /* ... */ ],
        importWord: {
            tokenUrl: 'https://example.com/cs-token-endpoint'
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 配置转换器服务 URL

如果服务托管在您自己的环境中，您应该通过“config.importWord.converterUrl” 选项配置转换器服务 URL。

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

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ ImportWord, /* ... */ ],
        toolbar: [ 'importWord', /* ... */ ],
        importWord: {
            converterUrl: 'https://example.com/converter'
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 默认样式

默认情况下，转换器服务将转换明确应用于内容的样式。您可以通过传递“config.importWord.formatting” 对象来更改此行为。

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

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ ImportWord, /* ... */ ],
        toolbar: [ 'importWord', /* ... */ ],
        importWord: {
            formatting: {
                resets: 'none',
                defaults: 'none',
                styles: 'inline'
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 评论样式

如果导入的文档包含评论，则默认情况下只会保留其基本样式。但是，您可以通过传递“config.importWord.formatting.comments” 选项来更改此行为。

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

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ ImportWord, /* ... */ ],
        toolbar: [ 'importWord', /* ... */ ],
        importWord: {
            formatting: {
                comments: 'none'
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

此配置选项可以采用以下值：

• 'basic' – 仅保留基本样式（粗体、斜体、下划线、删除线和链接）。
• 'none' – 导入评论文本时不使用任何样式。
• 'full' – 保留所有样式（不建议）。

# 已知限制

• CKEditor 5 不支持跳过中间级别的列表。
• 由于 CKEditor 5 中的列表合并，自定义起始值有时会被编辑器丢弃。
• CKEditor 5 可能会用其内置样式覆盖一些表格边框。
• 目前不支持文档页眉和页脚。
• 有关修订和评论，请查看“功能比较指南” 了解当前开发情况。
• 该功能不支持 .doc 文件。

# 相关功能

• “从 Word 粘贴” 功能允许您从 Microsoft Word 粘贴内容并保留原始的结构和格式。
• “导出到 Word” 功能允许您从编辑器创建的内容中生成可编辑的 .docx 文件。
• “导出到 PDF” 功能允许您从编辑器创建的内容中生成便携式 PDF 文件。

# 通用 API

“ImportWord” 插件注册

• 'importWord' UI 按钮组件，用于打开本机文件浏览器，让您可以直接从磁盘导入 Word 文件。
• 由“ImportWordCommand” 实现的 'importWord' 命令，该命令接受要导入的文件。

# dataInsert 事件

“dataInsert” 事件由“ImportWordCommand” 触发。它允许在将 HTML 内容插入编辑器之前修改内容。

editor.commands.get( 'importWord' ).on( 'dataInsert', ( event, data ) => {
    // The `data.html` property contains the HTML returned by the converter service.
    // Updating its value modifies the content that will be inserted into the editor.
    data.html = '<p>An example paragraph.</p>';
} );

此外，您可以通过调用“event.stop()” 函数来阻止事件进一步处理，并停止导入。

editor.commands.get( 'importWord' ).on( 'dataInsert', ( event, data ) => {
    // Example: Do not insert the HTML if it contains a table.
    if ( data.html.includes( '<table' ) ) {
        event.stop();
    }
} );

# 协作功能集成

如果您的编辑器设置中启用了“评论” 和“修订” 功能，则“从 Word 导入” 功能会自动与这些功能集成。

启用协作功能后，“dataInsert” 事件中的“data” 参数可能会包含“comment_threads” 和“suggestions” 字段，这些字段将包含从导入的 Word 文件中提取的数据。