CKEditor 生态系统文档
Search
Contribute to this guide
首页/CKEditor 5/功能

指南源代码编辑

源代码编辑功能允许您查看和编辑文档的源代码。

# 演示

使用下面的编辑器来查看源代码编辑插件的实际效果。切换源代码编辑模式 源代码编辑 并对 HTML 代码进行一些更改（例如，添加新段落或有序列表）。然后退出源代码编辑模式，你会发现这些更改出现在文档内容中。

您也可以使用工具栏中提供的众多 CKEditor 5 功能之一，并查看它们如何在 HTML 源代码中呈现。请注意可折叠的目录，它得益于 通用 HTML 支持 功能。该功能引入了尚未被官方插件覆盖的 HTML 元素。

此演示展示了一组有限的功能。访问 功能丰富的编辑器示例，以查看更多实际效果。

# 安装

⚠️ 新的导入路径

从 42.0.0 版本 开始，我们更改了导入路径的格式。本指南使用新的、更短的格式。如果您使用的是旧版本的 CKEditor 5，请参考 旧版设置中的包 指南。

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

import { ClassicEditor, SourceEditing } from 'ckeditor5';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ SourceEditing, /* ... */ ],
        toolbar: [ 'sourceEditing', /* ... */ ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

要使用 Markdown 源代码编辑模式，只需将 Markdown 输出 插件添加到编辑器中即可。

import { ClassicEditor, SourceEditing, Markdown } from 'ckeditor5';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ SourceEditing, Markdown, /* ... */ ],
        toolbar: [ 'sourceEditing', /* ... */ ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 限制和不兼容性

源代码编辑插件是一种低级文档编辑方法，它允许您直接更改文档数据源。这会导致与某些编辑器功能不兼容，这些功能高度依赖于编辑器机制和架构。

请仔细阅读本节内容，并检查这些问题是否适用于您的编辑器配置。

# 实时协作

在实时协作期间使用源代码编辑会带来严重的数据丢失风险，用户可能难以注意到和理解。

切换到源代码编辑后，远程用户执行的传入更改不会反映在源代码中。当你切换回来（保存源代码）时，**所有在此期间由其他用户完成的更改将被覆盖**。

由于存在此风险，默认情况下不允许同时使用这些功能。当两者都添加到编辑器中时，它会抛出错误。**您必须显式启用实时协作的源代码编辑模式，并承认此风险。**

要启用这些功能，请将 sourceEditing.allowCollaborationFeatures 配置标志设置为 true。

# 评论和追踪更改

评论和追踪更改功能使用标记来标记文档中受影响的部分。

在源代码编辑模式下，用户可以修改这些标记的边界。用户可以更改注释或追踪更改的范围，或将其删除。这带来了与用户权限相关的潜在问题。

当这些插件和源代码编辑插件一起使用时，编辑器将在浏览器的控制台中显示警告。

要关闭警告，请将 sourceEditing.allowCollaborationFeatures 配置标志设置为 true。

# 支持各种 HTML 元素

只有当编辑器“理解”对文档数据源所做的更改时，它才会保存这些更改。这意味着只有当加载的插件之一识别给定语法（HTML 或 Markdown）时才会保存更改。编辑器不支持的所有语法都将被过滤掉。

例如，如果编辑器没有加载 水平线 插件，则在退出源代码编辑模式时，在文档源中添加的 <hr> 标记将被删除。

为了避免这种情况，请确保您的编辑器配置包含处理各种 HTML 标记的所有必要插件。

在许多情况下，为了通过源代码编辑启用高级修改，您可能需要启用 HTML 嵌入 功能和 通用 HTML 支持 功能，或者编写一个插件来启用给定 HTML 标记或属性的支持。

# HTML 规范化

当编辑器读取源数据时，它会将数据转换为规范化的、高级抽象数据模型结构，并在该结构上进行操作。此结构不同于 HTML 或 Markdown 代码。

请注意，可以使用各种方法通过 HTML 描述相同的文档“状态”。

例如，<strong><em>Foo</em></strong> 和 <i><b>Foo</b></i> 都产生带有粗体和斜体样式的“Foo”文本。两者在加载到内部编辑器数据模型时将以相同的方式表示。

当编辑器数据模型稍后转换回文档源数据时，无论原始输入是什么，它都将被规范化。实际上，<i><b>Foo</b></i> 最终将变为 <strong><em>Foo</em></strong>。

此限制是核心编辑器架构的直接结果，无法解决。虽然可以更改编辑器的最终输出，但输入数据将始终被规范化为该输出格式。

# 对编辑器 UI 的影响

编辑器功能依赖于高级编辑器 API，该 API 在源代码编辑处于活动状态时无法使用。因此，当您切换到源代码编辑模式时，所有工具栏按钮都将被禁用，所有对话框窗口都将关闭。

# 修订历史

保存修改后的文档源代码在内部通过用新数据替换旧数据来执行。因此，它将作为总替换更改（插入 + 删除）表示在修订历史记录中。

当修订历史记录和源代码编辑一起加载时，编辑器将在浏览器的控制台中显示警告。

要关闭警告，请将 sourceEditing.allowCollaborationFeatures 配置标志设置为 true。

# 受限编辑

在源代码编辑模式下不强制执行受限编辑。用户可以编辑文档的任何部分，以及删除标记受限区域边界的标记。

当受限编辑和源代码编辑一起加载时，编辑器将在浏览器的控制台中显示警告。

# Markdown 源代码视图

源代码编辑插件也与 Markdown 输出 插件配合良好。您不需要任何特殊配置：只需将插件添加到编辑器，源代码编辑模式将显示 Markdown 而不是 HTML。

请记住，Markdown 语法很简单，不涵盖所有富文本功能。这意味着 CKEditor 5 提供的一些功能（无论是本机功能还是 GHS 功能引入的功能）只能作为本机 HTML 表示，因为它们没有 Markdown 等效项。此类功能将在下面的源代码视图中被剥离。

您可能希望检查其他与源代码相关的 CKEditor 5 功能

  • 通用 HTML 支持 – 允许您启用其他专用 CKEditor 5 插件不支持的 HTML 功能（元素、属性、类、样式）。
  • 全页 HTML – 允许使用 CKEditor 5 编辑整个 HTML 页面，从 <html> 到 </html>，包括页面元数据。
  • HTML 嵌入 – 允许在编辑器中嵌入任意 HTML 代码片段。
  • Markdown 输出 – 允许输出 Markdown 而不是 HTML 输出。

# 通用 API

SourceEditing 插件注册

  • 'sourceEditing' UI 按钮组件。

我们建议使用官方 CKEditor 5 检查器 进行开发和调试。它将为您提供有关编辑器状态的大量有用信息，例如内部数据结构、选择、命令等等。

# 贡献

该功能的源代码在 GitHub 上提供，地址为 https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-source-editing。