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

指南源代码编辑

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

# 演示

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

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

目录

  1. 唱歌的加拿大人
  2. 太空飞行
  3. 参考文献
  4. 太空怪人

唱歌的加拿大人

克里斯·哈德菲尔德在国际空间站，照片由美国宇航局提供。

克里斯·奥斯汀·哈德菲尔德 于 1959 年 8 月 29 日出生于加拿大。在孩提时代，他观看了阿波罗 11 号登月，这激励他成为一名宇航员。当时，加拿大没有太空计划，因此哈德菲尔德加入了 加拿大皇家空军，并担任了 25 年的战斗机飞行员。

1992 年，哈德菲尔德被 加拿大航天局 录取到加拿大宇航员计划。他于 1995 年乘坐 亚特兰蒂斯 号航天飞机执行了他的第一次任务，前往俄罗斯的 和平号 空间站。六年后，他乘坐 奋进号 航天飞机前往 国际空间站。他于 2012 年再次乘坐俄罗斯 联盟号 飞船访问 国际空间站，并在 远征 34/35 期间担任空间站指挥官。

哈德菲尔德因他在 国际空间站 上录制的大卫·鲍伊的著名歌曲 太空怪人 的演绎而被大众广泛认可。他还为学校录制了大量教育材料，这些材料是在他绕轨道工作期间录制的。从宇航员岗位退休后，他根据自己的经历撰写了三本书。

太空飞行

哈德菲尔德已经三次飞往太空。他还执行了两次 EVA（舱外活动，太空行走），总共持续了 14 小时 53 分钟 38 秒。

飞行 日期 航天器 职能 徽章
STS-74 12-20.11.1995 亚特兰蒂斯 任务专家
STS-100 19.04.2001-01.05.2001 奋进号 任务专家
远征 34/35 19.12.2012-14.05.2013 联盟号 TMA-07M 国际空间站指挥官

参考文献

  • 宇航员地球生活指南：太空之旅教会我的关于独创性、决心和为任何事做好准备。小布朗公司，2013
  • 你在哪里：92 分钟环游世界：国际空间站拍摄的照片。小布朗公司，2014
  • 最黑暗的黑暗。由特里和埃里克·范插图。小布朗公司，2016
  • 阿波罗谋杀案 兰登书屋，2021

太空怪人

克里斯·哈德菲尔德在 2013 年拍摄的《太空怪人》的演绎是有史以来第一个在太空中拍摄的音乐视频。

克里斯·哈德菲尔德不是地球上最酷的人的唯一原因是他不在地球上。

August Vctjuh 在 YouTube 上的评论。

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

# 安装

⚠️ 新的导入路径

从 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 等效项。此类功能将在下面的源代码视图中被剥离。

Markdown 输出 🛫

CKEditor 5 可以配置为输出 Markdown 而不是 HTML。Markdown 是一种轻量级标记语言，您可以使用它为纯文本文档添加格式。使用“源代码”按钮检查和编辑此内容的 Markdown 源代码。

编辑器生成的 Markdown 输出支持大多数基本功能，例如 链接、不同种类的强调、内联代码格式或代码块

p {
    text-align: center;
    color: red;
}

Markdown 输入 🛬

借助 自动格式化功能，您可以在写作时使用 Markdown 语法。试试看 - 在编辑器中使用这些（或任何其他）Markdown 快捷键，以动态地格式化内容 🚀！

内联格式 快捷键
粗体 在文本周围输入 ** 或 __。
斜体 在文本周围输入 * 或 _。
代码 在文本周围输入 ˋ。
删除线 在文本周围输入 ~~。

嘘！🤫 Markdown 对表格的支持非常基本。此演示中禁用了某些高级表格相关功能，例如表格或单元格样式。

块级格式

您还可以使用 Markdown 创建各种文本块，例如

  • 块引用 - 以 ﹥ 后跟一个空格开始一行。
  • 标题
    1. 标题 1 - 以 # 后跟一个空格开始一行。
    2. 标题 2 - 以 ## 后跟一个空格开始一行。
    3. 标题 3 - 以 ### 后跟一个空格开始一行。
  • 列表，包括嵌套列表
    • 编号列表 - 以 1. 或 1) 后跟一个空格开始一行。
    • 项目符号列表 - 以 * 或 - 后跟一个空格开始一行。
    • 待办事项列表 - 以 [ ] 或 [x] 后跟一个空格开始一行，以插入未选中或已选中的列表项。
  • 代码块 - 以 ˋˋˋ 开始一行。
  • 水平线 - 以 --- 开始一行。

您可能希望检查其他与源代码相关的 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。