CKEditor 4 Widget 内联可编辑区域(inline editable)加粗后切换源码模式报错:manual 测试场景与 698 修复原理解析
CKEditor 4 Widget 内联可编辑区域(inline editable)加粗后切换源码模式报错:manual 测试场景与 #698 修复原理解析
本文围绕仓库中
tests/plugins/widget/manual/inlineeditable.md这一手动测试(manual test)场景展开,深入讲解 CKEditor 4 Widget 插件中「嵌套内联可编辑区域」在 WYSIWYG 与源码(source)模式间切换时的边界问题:在行内可编辑区域(本场景中为一个<span>)内对文本加粗后,切换到源码模式可能触发控制台报错、编辑器无法切换模式。通过阅读对应的 复现页面、自动化测试 以及 widget 插件源码 中的 downcast 处理逻辑,读者可以掌握该问题(编号 #698)的完整成因、修复方式,以及如何在 Bender 测试框架下复现与回归验证。
测试场景概览:一次针对 Bug 的手动回归测试
inlineeditable.md 是 CKEditor 4 测试体系中的一份 Bender 手动测试说明文档(manual test),与同目录下的 inlineeditable.html 配套使用。其文件头部的 Bender 元信息定义了该测试的属性:
@bender-tags: 4.20.2, bug, 698, widget:该测试标注了修复版本 4.20.2、类型为 bug、关联问题编号 698,归属模块 widget;@bender-ui: collapsed:手动测试运行页面的 UI 以折叠形式展示;@bender-ckeditor-plugins: wysiwygarea, toolbar, sourcearea, basicstyles, widget:运行该场景需要加载的插件集合,其中wysiwygarea提供可视化编辑区、sourcearea提供源码模式切换能力、basicstyles提供Bold(加粗)命令、widget是测试的核心插件。
该场景的测试对象是带嵌套可编辑区域的行内 widget(inline widget with nested editable):widget 内部包含一个可编辑的 <span> 子元素,用户可以像编辑普通文本一样在其内部输入与排版,但同时它又被 widget 体系托管。
复现环境:从 inlineeditable.html 理解最小化复现代码
手动测试页面 inlineeditable.html 是整个场景的「现场」。它用不到 30 行代码构造了一个最小化复现环境,其中包含三个关键技术点。
1. 将 <span> 注册为可编辑宿主
<div id="editor">
<strong><span>Test</span></strong>
</div>
在脚本开头,测试执行了这样一行关键操作:
CKEDITOR.dtd.$editable.span = 1;
CKEditor 的 DTD 定义中,$editable 是「可作为内联编辑宿主(inline editing host)」的元素白名单。从 core/dtd.js 可以看到,默认名单只包含块级元素:
$editable: {
address: 1, article: 1, aside: 1, blockquote: 1, body: 1, details: 1, div: 1, fieldset: 1,
figcaption: 1, footer: 1, form: 1, h1: 1, h2: 1, h3: 1, h4: 1, h5: 1, h6: 1, header: 1, hgroup: 1,
main: 1, nav: 1, p: 1, pre: 1, section: 1
}
<span> 默认并不在其中,因此测试必须通过修改 CKEDITOR.dtd.$editable 将其临时注册为合法的可编辑宿主,这是让 span 能够成为 widget 嵌套可编辑区域的前提。
2. 定义一个带嵌套可编辑区域的行内 widget
CKEDITOR.plugins.add( 'spanwidget', {
requires: 'widget',
init: function( editor ) {
editor.widgets.add( 'spanwidget', {
editables: {
content: {
selector: 'span'
}
},
upcast: function( element ) {
return element.name == 'span';
}
} );
}
} );
这里定义了一个名为 spanwidget 的 widget 插件:
editables.content.selector: 'span':声明 widget 内部名为content的嵌套可编辑区域,通过选择器匹配<span>元素;upcast:当 HTML 数据被解析进入编辑器时,凡名称是span的元素都会被上转(upcast)为该 widget 的实例。
3. 编辑器配置
CKEDITOR.replace( 'editor', {
extraPlugins: 'spanwidget',
extraAllowedContent: 'span'
} );
extraPlugins: 'spanwidget':加载自定义 widget 插件;extraAllowedContent: 'span':在高级内容过滤器(ACF)中放行span元素,否则 ACF 会在数据进入编辑区时将其过滤掉,widget 便无法成立。
4. 初始化检查
上述逻辑与插件源码中的嵌套可编辑区域初始化流程一一对应。plugins/widget/plugin.js 中的 initEditable 方法会先通过 editable.is( CKEDITOR.dtd.$editable ) 校验目标元素是否属于可编辑宿主白名单,再为其设置 contenteditable="true"、data-cke-widget-editable 等属性并挂载独立的内容过滤器。这也是为什么第 1 步必须先把 span 写入 $editable——否则 initEditable 会直接返回失败,嵌套可编辑区域无法建立。
同时,isWidgetInline 决定了该 widget 以行内形式还是块级形式渲染:
function isWidgetInline( widgetDef, elementName ) {
return typeof widgetDef.inline == 'boolean' ? widgetDef.inline : !!CKEDITOR.dtd.$inline[ elementName ];
}
span 属于 DTD 中的 $inline 元素,因此 spanwidget 会被自动判定为行内 widget,其外层 wrapper 使用 <span> 而非 <div> 包裹(见 plugin.js 中 wrapper 创建逻辑)。
操作步骤与预期结果(继承自 manual 文档)
按照 inlineeditable.md 的原始步骤,手动复现该 Bug 的操作路径如下:
- 打开浏览器控制台(Open browser console);
- 在编辑区中,选中
Test中的最后一个字母t(Selectt(the last letter) fromTest); - 点击工具栏上的 Bold 加粗按钮;
- 切换到源码模式(Switch to the source mode)。
预期结果
编辑器正常切换到源码模式,控制台无报错。
意外结果(Bug 表现)
控制台出现错误(error in the console),且编辑器没有切换到源码模式。
回归验证
- 切换回可视化(WYSIWYG)编辑模式;
- 预期编辑器正常切回编辑模式;若控制台报错且无法切回,则说明 Bug 仍然存在。
步骤要点分析
- 选中最后一个字母
t并加粗,意味着加粗格式恰好作用在嵌套可编辑区域content(即<span>)内部的文本边界附近; - 这一步是触发问题的关键条件。如源码注释所述,在嵌套可编辑区域边界附近应用格式时,widget 在 downcast(数据输出)过程中可能被「一分为二」产生重复副本;
- 此时再切换到源码模式,编辑器需要将整个文档(包括 widget 的 downcast 结果)序列化为 HTML,边界处的重复 widget 就会在序列化流程中引发异常,进而导致模式切换失败。
自动化回归测试:同一场景的 Bender 断言版本
该手动场景在自动化测试 tests/plugins/widget/inlineeditables.js 中有完全对应的回归用例:
'test switching to source mode after bolding text in an inline editable': function() {
var editor = this.editor, editorBot = this.editorBot;
editorBot.setData( '<strong><span>lorem</span></strong>', function() {
var textNode = editor.editable().findOne( 'span' ).getFirst().getFirst(),
rng = editor.createRange();
editor.focus();
// Select the `m`.
rng.setStart( textNode, 4 );
rng.setEnd( textNode, 5 );
editor.getSelection().selectRanges( [ rng ] );
editor.execCommand( 'bold' );
editor.setMode( 'source' );
// Just pass the test if nothing threw before.
assert.pass();
} );
} );
该测试与手动场景一一对应:setData 注入与 manual 页面相同的 <strong><span>Test</span></strong> 结构;通过 Range 精确选中 span 内文本的最后一个字符;执行 bold 命令后立即调用 editor.setMode( 'source' ) 切换模式;只要切换过程中没有抛出异常即断言通过(assert.pass())。// #698 的注释直接标明了这是对问题 698 的回归覆盖。
源码原理:#698 的成因与修复
downcast 阶段的「分身 widget」问题
问题根源位于 widget 插件对文档输出(downcast)流程的处理。在 plugins/widget/plugin.js 的 toDataFormat 相关回调中,每个 widget 会依次执行 downcast:将内部嵌套可编辑区域的内容替换为其实时数据,然后以 retElement 替换外层 wrapper:
// Replace nested editables' content with their output data.
for ( e in toBe.editables ) {
editableElement = toBe.editables[ e ];
delete editableElement.attributes.contenteditable;
editableElement.setHtml( widget.editables[ e ].getData() );
}
...
// In some edge cases (especially applying formating
// at the boundary of the inline editable) the widget
// is going to be duplicated (split in half).
// In that case there won't be a retElement
// and we can safely remove such doppelganger widget (#698).
if ( retElement ) {
toBe.wrapper.replaceWith( retElement );
} else {
toBe.wrapper.remove();
}
这段代码与注释直接说明了 #698 的修复策略:
- 成因:在行内可编辑区域边界附近应用格式(如本例中对
span内最后一个字符加粗)时,DOM 结构会被拆分,downcast 后同一个 widget 会分裂成两份副本(源码注释中称之为 doppelganger widget,即「分身 widget」); - 修复:当检测到
retElement为空(即 widget 已被拆分成副本)时,不再执行wrapper.replaceWith( retElement ),而是直接wrapper.remove()移除这个分身,避免重复的 widget 在数据序列化阶段引发异常; - 效果:加粗并切换源码模式时不再抛错,
editor.setMode( 'source' )得以正常完成。
模式切换的底层支撑
editor.setMode( 'source' ) 依赖 sourcearea 插件提供的源码编辑模式。widget 插件在编辑器 mode 事件上也挂有清理与重建逻辑(例如 widget mask 的刷新,见 plugin.js 第 3811-3815 行),并保证 mode != 'wysiwyg' 时不执行与可视化编辑相关的操作(见 plugin.js 第 2171 行)。因此一旦 downcast 阶段出现异常,整个模式切换链路都会中断——这正是 manual 文档中「控制台报错且编辑器无法切换模式」的直接表现。
自动化测试工具的辅助验证
测试辅助工具 tests/plugins/widget/_helpers/tools.js 提供了一组「switch modes」测试生成器,会在每个测试用例之后追加一轮 setMode('source') → getData() → setMode('wysiwyg') 的模式往返校验,用于批量验证任意 widget 场景在模式切换与数据往返(round-trip)后的行为一致性。inlineeditable.md 手动测试关注的正是这条链路上的极端边界情况。
与其他手动测试的关系:source/wysiwyg 模式往返是 widget 通用回归项
在 widget 模块的其他手动测试中,「在源码与 WYSIWYG 模式间多次切换」被反复列为通用回归项:
- inline.md:行内 widget 的创建、编辑、选择、拖放、复制粘贴、嵌套可编辑区域编辑、删除、撤销/重做,以及「多次在 source 与 wysiwyg 模式间切换」;
- block.md:块级 widget 的同类回归清单,同样包含「switch multiple times between source and wysiwyg mode」,并额外覆盖「将外层 widget 拖入其内部嵌套 widget」等边界用例。
inlineeditable.md 正是其中针对「行内 widget + 嵌套可编辑区域 + 边界格式化」这一特殊组合的定向回归场景——普通文本与块级 widget 均不会触发 #698,只有行内嵌套可编辑区域在边界处被格式化时才可能复现。
如何运行与验证该测试
该手动测试属于 Bender 手动测试(manual tests),运行方式如下:
- 在仓库根目录启动 Bender 测试服务器(仓库根目录下的
bender.js、bender.ci.js与bender-runner.config.json为测试框架配置,具体启动方式参见仓库内 Bender 相关说明); - 在 Bender 的测试列表中找到
plugins/widget/manual/inlineeditable用例; - 打开浏览器控制台(开发工具),按上文步骤操作:选中
Test的最后一个字母t→ 点击 Bold → 切换到源码模式 → 再切回编辑模式; - 若两个模式切换均无控制台错误,说明 #698 的修复生效;自动化回归则由
inlineeditables.js中的test switching to source mode after bolding text in an inline editable用例持续守护。
说明:本文所述行为基于当前仓库代码状态。
CKEDITOR.dtd.$editable.span = 1属于测试环境的临时注册,生产环境若要允许span成为可编辑宿主,需在应用初始化阶段显式完成同样的 DTD 扩展,并同时配置 ACF 放行对应元素。