CKEditor 4 粘贴后输入丢失 change 事件(554)修复与回归测试解析:手动测试到源码原理

原创2026-10-16 13:11:132,297 阅读
文章标签:前端UI组件

CKEditor 4 粘贴后输入丢失 change 事件(#554)修复与回归测试解析:手动测试到源码原理

本篇指南围绕 CKEditor 4 仓库中的一条手动回归测试用例 tests/plugins/undo/manual/changeevent.md 展开,完整还原"先粘贴、再输入一个字符"场景下 change 事件应恰好触发两次的验证步骤,并深入 undo 插件源码剖析该 bug(ticket #554)的成因、修复方案与自动化测试佐证。读完你将掌握 CKEditor 4 中 change 事件的触发链路、undo 快照机制对事件分发的影响,以及如何用 Bender 手动/自动化测试验证编辑器行为。

一、测试用例定位:它是谁、验证什么

changeevent.md 是 CKEditor 4 测试套件中一条手动测试(manual test),位于 tests/plugins/undo/manual/ 目录下,与同目录的 changeevent.html 页面配套使用。文件头部以 Bender 约定格式声明了测试元信息:

@bender-tags: 554, 4.7.3, bug
@bender-ui: collapsed
@bender-ckeditor-plugins: undo,clipboard,basicstyles,toolbar,wysiwygarea
  • @bender-tags:关联到缺陷单 #554,该缺陷在 4.7.3 版本修复,类型为 bug;
  • @bender-ckeditor-plugins:测试页面需要加载的插件集合——undo(快照与撤销核心)、clipboard(粘贴事件链)、basicstyles、toolbar、wysiwygarea。这条依赖清单本身就是复现缺陷的最小环境,缺少 undo 插件时 change 事件的驱动逻辑根本不会挂载。

它的复现步骤与预期结果在原文档中非常简短,却是整个回归测试的灵魂:

  1. 向编辑器粘贴一段文本(Paste some text into the editor)。
  2. 粘贴之后,再键入一个字符(Type a single character after pasting)。

预期结果(Expected): 编辑器下方应恰好显示两个 change 事件(There should be exactly two change events shown below the editor)。

二、事件展示页面:如何"数" change 事件

配套页面 tests/plugins/undo/manual/changeevent.html 用最朴素的方式把 change 事件可视化——监听编辑器的 change 事件,每触发一次就往页面追加一行文本:

<div id="editor1">
	<p>Paste something here:</p>
</div>
<div id="changes"></div>

<script>
	var i = 1;
	var changes = document.getElementById( 'changes' );
	CKEDITOR.replace( 'editor1' ).on( "change", function () {
		var elem = document.createElement( 'div' );
		elem.innerText = 'changes ' + i++;
		changes.appendChild( elem );
	});
</script>

这段页面逻辑值得注意的两点:

  1. 它用 CKEDITOR.replace( 'editor1' ) 创建经典(iframe)编辑器,因此测试元信息中的 wysiwygarea 插件是必需的;
  2. change 事件是 CKEDITOR.editor 级别的事件(而非 DOM 事件),通过 editor.on( 'change', ... ) 订阅。测试时人工数出页面中 "changes N" 行数,即可判断事件是否多触发或漏触发。

三、缺陷根源:paste 后输入事件被永久"忽略"

要理解"粘贴 + 一个字符为什么必须恰好产生两个 change 事件",需要进入 undo 插件的 NativeEditingHandler。在 plugins/undo/plugin.js 中,undo 管理器通过"监听 editable 的原生事件"来判断何时应当为输入创建撤销快照:

// On paste and drop we need to ignore input event.
// It would result with calling undoManager.type() on any following key.
editable.attachListener( editable, 'paste', that.ignoreInputEventListener, that, null, 999 );
editable.attachListener( editable, 'drop', that.ignoreInputEventListener, that, null, 999 );

// After paste we need to re-enable input event listener (#554).
editor.on( 'afterPaste', that.activateInputEventListener, that, null, 999 );

机制如下(可对照 plugin.js 中的两个方法):

  • ignoreInputEventListener():把 ignoreInputEvent 置为 true。因为在 paste / drop 之后,浏览器还会派发一个 input 事件;若不做拦截,undo 管理器会误判为一次键盘输入,从而在 onInput() 里错误调用 undoManager.type(),把"粘贴"和"下一次击键"合并成同一条记录;
  • onInput()(plugin.js):当 ignoreInputEvent 为 true 时直接返回,并只复位这一次的忽略标记;
  • activateInputEventListener():把 ignoreInputEvent 复位为 false。

bug #554 的成因就在这两者之间:4.7.3 之前,粘贴后没有 afterPaste 重新激活输入监听的逻辑,ignoreInputEvent 一旦被置位就再也不复位。结果是:粘贴本身触发了一次 change(来自快照保存),但粘贴后键入的第一个字符,其 input 事件被永久忽略,onKeyup 中因 totalInputs > 0 而调用的 undoManager.type() 对应的那次 change 被吞掉——用户只看到一次 change 事件。

修复方案正是上文中带 (#554) 注释的那一行:在 afterPaste 事件上重新激活输入事件监听器,保证"粘贴之后的下一次击键"仍能正常计入并触发 change。

四、change 事件在 undo 管理器中的三条触发路径

为什么"粘贴"与"键入"各算一次 change?这要从 UndoManager 的源码确认。change 事件并非由 editable 或输入框直接派发,而是由 undo 管理器在以下三处 editor.fire( 'change' ) 触发(详见 plugins/undo/plugin.js):

触发点 源码位置 场景
type() plugin.js 键盘输入未超过快照合并上限时,每次 keyup 且确有输入计数时触发
save() plugin.js 保存快照时若内容与当前快照不同,触发一次 change
restoreImage() plugin.js 执行 undo / redo 恢复历史状态后触发一次 change

对应到本测试场景:

  • 粘贴:clipboard 插件把数据写入编辑器后(paste 事件处理器中 editor.insertHtml(...),见 plugins/clipboard/plugin.js),undo 管理器随后保存快照,内容与之前不同,save() 在 plugin.js 中触发 change —— 这是第一个事件;
  • 键入一个字符:input 事件计数 → keyup 中 totalInputs > 0 → undoManager.type( keyCode ) → 未达到 strokesLimit(默认 25 字符,见 plugin.js),走 plugin.js 的 else 分支触发 change —— 这是第二个事件。

两个事件恰好对应"粘贴内容变化"与"后续键入变化"两个独立的内容变更动作,这正是手动测试期望两个事件的根本原因。

五、自动化测试佐证:同一场景的断言版本

手动测试验证同一行为,仓库中还有对应的自动化测试:tests/plugins/undo/change.js 中的 test change event fired on type after paste,测试头部的注释直接标注了缺陷编号 // #554(见 tests/plugins/undo/change.js):

// #554
'test change event fired on type after paste': function() {
	this.editorBot.setHtmlWithSelection( '<p>foo^</p>' );

	var that = this,
		keys = this.keyTools.keyCodesEnum;

	bender.tools.emulatePaste( this.editor, 'PASTE' );

	this.editor.once( 'afterPaste', function() {
		resume( function() {
			changeCounter = 0;
			that.checkChange( function() {
				that.keyTools.keyEvent( keys.KEY_G );
			} );
		} );
	} );

	wait();
}

测试逻辑与手动步骤一一对应:

  1. emulatePaste( this.editor, 'PASTE' ) 模拟一次粘贴;
  2. 等待 afterPaste 事件(即 bug 修复后重新激活输入监听的时点);
  3. 清空计数器后模拟按下 G 键——这正是"粘贴后键入单个字符";
  4. checkChange 断言 changeCounter 恰为 1(本次击键恰好触发一次 change)。

若 4.7.3 的修复被回退(afterPaste 不重新激活监听),此测试会因 changeCounter === 0 而失败。同文件中其他用例(如 test no change event during navigation 断言方向键/ Tab 不触发 change,test change event not fired after navigation key 引用 ticket 12300)共同勾勒出 change 事件的完整边界:内容变化触发、纯导航不触发、粘贴后的首次输入必须触发。

六、如何运行这套测试

CKEditor 4 的测试统一由 Bender 驱动(配置见 bender.js 与 bender-runner.config.json)。手动测试与自动化测试的运行方式不同:

  • 自动化测试(tests/plugins/undo/change.js):通过 Bender 的 YUI 框架执行,随常规测试套件一起跑,测试页面由 tests/plugins/undo/undo.html 等宿主页面承载;
  • 手动测试(changeevent.md + changeevent.html):需要人工在浏览器中操作,Bender 配置中由 manualBrowsers 指定允许执行手动测试的浏览器,并可通过 manualTestTimeout 控制超时判定(bender.js 有相关参数说明)。运行后按上文第二节的步骤操作并目测计数即可。

七、使用 change 事件的注意事项(源自源码文档)

在 plugins/undo/plugin.js 末尾,CKEditor 4 对 change 事件给出了官方使用约束,实测接入时务必遵守:

  • 仅 wysiwyg 模式触发:change 只在所见即所得编辑模式派发;source 模式下需自行监听 key 事件或原生 input 事件;
  • 不做内容真伪校验:出于性能考虑,编辑器"watch 若干通常导致变化的编辑动作"而非逐字比对,因此 change 事件可能在不变化时误触发,也可能一次操作触发两次;
  • 若要求精确:应在监听器内部自行比对前后内容,但不建议在每次 change 上都做重比较。

本文的手动测试之所以期望"恰好两个"事件,正是基于对以上机制的精确把握——粘贴与键入是两个独立动作,各自驱动一次内容变更;而 #554 的缺陷曾让第二个动作的事件被吞掉,手动与自动化双测试共同锁死了这条回归防线。

登录后查看全文
ckeditor4