CKEditor 4 粘贴后输入丢失 change 事件(554)修复与回归测试解析:手动测试到源码原理
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事件的驱动逻辑根本不会挂载。
它的复现步骤与预期结果在原文档中非常简短,却是整个回归测试的灵魂:
- 向编辑器粘贴一段文本(Paste some text into the editor)。
- 粘贴之后,再键入一个字符(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>
这段页面逻辑值得注意的两点:
- 它用
CKEDITOR.replace( 'editor1' )创建经典(iframe)编辑器,因此测试元信息中的wysiwygarea插件是必需的; 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();
}
测试逻辑与手动步骤一一对应:
emulatePaste( this.editor, 'PASTE' )模拟一次粘贴;- 等待
afterPaste事件(即 bug 修复后重新激活输入监听的时点); - 清空计数器后模拟按下
G键——这正是"粘贴后键入单个字符"; 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 的缺陷曾让第二个动作的事件被吞掉,手动与自动化双测试共同锁死了这条回归防线。