CKEditor 4 Widget 内联可编辑区域(inline editable)加粗后切换源码模式报错:manual 测试场景与 698 修复原理解析

原创2026-10-16 17:39:451,931 阅读
文章标签:前端UI组件

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 的操作路径如下:

  1. 打开浏览器控制台(Open browser console);
  2. 在编辑区中,选中 Test 中的最后一个字母 t(Select t (the last letter) from Test);
  3. 点击工具栏上的 Bold 加粗按钮;
  4. 切换到源码模式(Switch to the source mode)。

预期结果

编辑器正常切换到源码模式,控制台无报错。

意外结果(Bug 表现)

控制台出现错误(error in the console),且编辑器没有切换到源码模式。

回归验证

  1. 切换回可视化(WYSIWYG)编辑模式;
  2. 预期编辑器正常切回编辑模式;若控制台报错且无法切回,则说明 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),运行方式如下:

  1. 在仓库根目录启动 Bender 测试服务器(仓库根目录下的 bender.js、bender.ci.js 与 bender-runner.config.json 为测试框架配置,具体启动方式参见仓库内 Bender 相关说明);
  2. 在 Bender 的测试列表中找到 plugins/widget/manual/inlineeditable 用例;
  3. 打开浏览器控制台(开发工具),按上文步骤操作:选中 Test 的最后一个字母 t → 点击 Bold → 切换到源码模式 → 再切回编辑模式;
  4. 若两个模式切换均无控制台错误,说明 #698 的修复生效;自动化回归则由 inlineeditables.js 中的 test switching to source mode after bolding text in an inline editable 用例持续守护。

说明:本文所述行为基于当前仓库代码状态。CKEDITOR.dtd.$editable.span = 1 属于测试环境的临时注册,生产环境若要允许 span 成为可编辑宿主,需在应用初始化阶段显式完成同样的 DTD 扩展,并同时配置 ACF 放行对应元素。

登录后查看全文
ckeditor4