CKEditor 4 源码模式切换后 Autocomplete 键盘导航失效的回归测试与修复原理
CKEditor 4 源码模式切换后 Autocomplete 键盘导航失效的回归测试与修复原理
本文以 CKEditor 4 仓库中的手动测试用例 tests/plugins/autocomplete/manual/sourcemode.md 为骨架,深入讲解 Autocomplete(自动补全)/ Mentions(提及)组件在「WYSIWYG ↔ 源码模式」切换后键盘导航失效这一经典缺陷(#3938、#4107)的复现步骤、回归测试设计,以及 autocomplete 插件 在
contentDom事件中重新注册按键监听的修复原理。读者将掌握:如何用手动测试验证该缺陷、如何用 Bender 自动化测试守护它,以及 autocomplete 的键盘交互与模式切换的底层实现机制。
一、缺陷背景:切换源码模式后补全面板「键盘失灵」
在 CKEditor 4 中,经典编辑器(classic editor)可以通过 sourcearea 插件 在「所见即所得(WYSIWYG)编辑模式」与「源码(source)编辑模式」之间切换。源码模式将可编辑区域替换为一个 <textarea>,直接展示并编辑原始 HTML。
Autocomplete(自动补全)面板的键盘导航——上下方向键切换候选、Esc 关闭面板、Tab/Enter 提交——依赖在 editable(可编辑区域)元素上注册的 keydown 监听器。当用户切换到源码模式再切回 WYSIWYG 模式时,编辑区域会被销毁并重建,之前注册的键盘监听也随之丢失。若 autocomplete 实例没有针对「可编辑区域重建」这一事件重新绑定监听,就会出现面板能打开、却无法用方向键导航的「半失灵」状态。
该缺陷在 CHANGES.md 中有明确记录,经历了两个阶段的修复:
- CKEditor 4.14.1:#3938 修复了「切换到源码模式后无法用键盘导航 Autocomplete 面板」的问题,配套手动测试见 tests/plugins/autocomplete/manual/navigation.md;
- CKEditor 4.15.0:#4107 进一步修复了「多个 Autocomplete 实例导致键盘导航问题」——即单个编辑器同时挂载两个及以上补全实例(例如同时配置
@与#两个 mentions)时,模式切换后部分甚至全部实例的键盘导航失效。
本文所述的手动测试用例 sourcemode.md 正是针对 4.15.0 的 #4107 而设计的回归验证用例。
二、手动测试用例逐条解读
sourcemode.md 是一个 Bender 手动测试(manual test)用例。文件头部通过 @bender-* 指令声明测试元数据,正文以编号步骤描述操作路径,并以 Expected / Unexpected 明确判定标准。
2.1 Bender 测试元数据
@bender-tags: 4.15.0, bug, 4107
@bender-ui: collapsed
@bender-ckeditor-plugins: wysiwygarea, toolbar, basicstyles, mentions, sourcearea
| 指令 | 含义 |
|---|---|
@bender-tags: 4.15.0, bug, 4107 |
声明该用例针对 4.15.0 版本、属于缺陷回归测试(bug)、对应 issue 编号 4107 |
@bender-ui: collapsed |
以折叠 UI 模式渲染编辑器,便于聚焦测试内容本身 |
@bender-ckeditor-plugins: wysiwygarea, toolbar, basicstyles, mentions, sourcearea |
测试页面需要加载的插件清单:WYSIWYG 编辑区、工具栏、基础样式、mentions(依赖 autocomplete 与 textmatch)、sourcearea(提供源码模式) |
其中 mentions 是本文测试的核心插件,它内部依赖 autocomplete、textmatch、ajax 三个插件(见 plugins/mentions/plugin.js 的 requires 声明);sourcearea 则是制造「模式切换」场景的前提插件。
2.2 复现步骤
原文档给出了 8 个编号步骤:
- Switch to source mode.(切换到源码模式)
- Switch back to WYSIWYG mode.(切换回 WYSIWYG 模式)
- Focus the editor.(聚焦编辑器)
- Type
@to open completion panel.(输入@打开补全面板) - Navigate through items using arrow keys.(用方向键导航候选)
- Close completion panel using
esckey.(按Esc关闭面板) - Type
#to open completion panel.(输入#打开第二个补全面板) - Navigate through items using arrow keys.(再次用方向键导航)
步骤 1–2 是本测试的核心前置条件:先在源码模式与 WYSIWYG 模式之间做一次往返切换,人为触发「可编辑区域销毁重建」的路径;步骤 4–8 则分别验证两个补全实例(@ 与 #)的键盘导航是否仍然可用。
2.3 判定标准
- Expected(预期):对于
@和#两个字符触发的补全面板,都应该能够使用方向键在候选条目间导航; - Unexpected(缺陷表现):模式切换之后,两个面板中某一个(或全部)的方向键导航失效。
这一「二选一」的判定标准精准对应 #4107 的核心症状——在引入 contentDom 重新绑定机制之前,多个实例中往往只有部分实例的监听器能在可编辑区域重建后存活,造成「部分面板可导航、部分不可导航」的割裂现象。
三、测试页面的实例配置
手动测试的执行载体是与 sourcemode.md 同目录的 sourcemode.html,它构建了双 mentions 实例的复现环境:
var feed = [
'john', 'thomas', 'anna',
'annabelle', 'cris', 'julia'
];
var editor = CKEDITOR.replace( 'editor', {
width: 600,
mentions: [
{ feed: feed, minChars: 0 }, // 默认 marker: '@'
{ feed: feed, minChars: 0, marker: '#' } // 自定义 marker: '#'
]
} );
这里用到两个 mentions 配置项(完整配置定义见 plugins/mentions/plugin.js 的 config.mentions 说明):
feed:候选数据源,可以是字符串数组(同步数据源)、后端 URL 字符串(异步 JSON 数据源,支持{encodedQuery}占位符)或自定义回调函数;marker:触发补全的标记字符,默认'@'(见 plugin.js);第二个实例显式设为'#';minChars:标记字符后需要输入的字符数才触发补全,默认 2(见 plugin.js),此处设为0使@/#一输入即可弹出面板,方便手动验证。
在插件初始化阶段,mentions 会在编辑器的 instanceReady 事件中遍历 editor.config.mentions 数组,为每个配置对象分别创建一个独立的 mentions 实例(见 plugin.js),每个实例内部再各自实例化一个 CKEDITOR.plugins.autocomplete(见 plugin.js)。这正是「单编辑器多补全实例」的场景,也是 #4107 测试的前提。
测试页面末尾的 bender.tools.ignoreUnsupportedEnvironment( 'mentions', editor ) 用于在不支持 autocomplete 的旧版 IE(IE8 及以下)环境中自动跳过测试——autocomplete 的 isSupportedEnvironment 明确排除了 IE 8 及以下版本(见 plugins/autocomplete/plugin.js)。
四、底层原理:为什么模式切换会破坏键盘导航
要理解修复方案,先要看清 autocomplete 的监听器注册时机。
4.1 监听器注册的完整链路
在 plugins/autocomplete/plugin.js 的 attach() 方法中,autocomplete 依次完成:
- 将补全面板(
ul.cke_autocomplete_panel)追加到 DOM 并绑定视图事件; - 将 text watcher 挂载到编辑器;
- 订阅模型/视图事件(
change-data、change-selectedItemId、click-item等); - 监听窗口与编辑区域的
scroll事件以实时重定位面板; - 调用
registerPanelNavigation()在 editable 上注册keydown监听; - 为可编辑区域添加 ARIA 无障碍属性。
其中键盘导航由 registerPanelNavigation() 完成(plugin.js):
registerPanelNavigation: function() {
var editable = this.editor.editable();
// Priority 5 to get before the enterkey.
this._listeners.push( editable.attachListener( editable, 'keydown', function( evt ) {
this.onKeyDown( evt );
}, this, null, 5 ) );
}
监听优先级设为 5,是为了抢在 enterkey 插件(负责在 WYSIWYG 模式处理回车换行)之前截获 Enter 键。
4.2 sourcearea 如何「摧毁」这些监听
sourcearea 插件 通过 editor.addMode( 'source', ... ) 注册源码模式(plugin.js):切换时会销毁原可编辑区域,并在内容区创建一个 <textarea class="cke_source"> 作为新的 editable;切回 WYSIWYG 时再由 wysiwygarea 插件重建 iframe 编辑区。每次切换,editable 元素都是全新的 DOM 节点,在旧节点上注册的 keydown 监听随节点销毁而失效。
更隐蔽的是监听器重复注册问题:attach() 只在实例化时执行一次,而编辑器在生命周期中会多次触发 contentDom(每次可编辑区域重建都会触发)。若把 registerPanelNavigation() 只放在 attach() 里,那么模式切换后新 editable 上就没有键盘监听;若把这段逻辑直接挂在 contentDom 上而不做幂等保护,则每次切换都会堆积重复监听器。CKEditor 事件系统本身有一条限制——同一个函数不能作为同一事件的监听器注册两次以上(源码注释在 plugin.js 有说明),这进一步加剧了多实例场景下的混乱。
五、修复实现:#4107 的 contentDom 重新绑定方案
修复的关键位于 attach() 方法的结尾(plugins/autocomplete/plugin.js),源码注释中明确标注了 issue 编号:
// Note: CKEditor's event system has a limitation that one function
// cannot be used as listener for the same event more than once. Hence, wrapper function.
// (#4107)
editor.on( 'contentDom', function() {
this.registerPanelNavigation();
this.addAriaAttributesToEditable();
}, this );
这段代码的含义:
- 订阅
contentDom事件:只要可编辑区域被(重新)创建,autocomplete 就立即重新执行registerPanelNavigation(),把keydown监听绑定到新的 editable 上; - 使用包装函数而非直接引用:由于事件系统不允许同一函数重复注册,这里用匿名包装函数包一层
registerPanelNavigation,使每次contentDom都能安全地新增一个监听器,同时配合destroy()中的removeListener清理机制避免泄漏; - 同步重挂 ARIA 属性:
addAriaAttributesToEditable()为内联编辑器的 editable 重新设置aria-controls、aria-expanded、aria-activedescendant、aria-autocomplete等无障碍属性,保证模式切换后屏幕阅读器仍能正确感知补全面板状态(相关实现见 plugin.js)。
text watcher 侧也有同样的处理:TextWatcher.attach() 同时监听 editor.on( 'contentDom' ) 并在回调里为新 editable 绑定 keyup 监听(见 plugins/textwatcher/plugin.js),确保模式切换后「输入文本触发匹配检测」这条链路同样可用。
六、键盘交互全流程:onKeyDown 的按键分发
修复后,模式切换并不改变键盘交互本身。onKeyDown(plugin.js)在面板激活(model.isActive)时处理四种按键:
| 按键 | keyCode | 行为 |
|---|---|---|
Esc |
27 | 关闭面板并调用 textWatcher.unmatch() 重置匹配状态 |
下方向键 ↓ |
40 | model.selectNext() 选中下一个候选 |
上方向键 ↑ |
38 | model.selectPrevious() 选中上一个候选 |
| 提交键 | 9 / 13(Tab / Enter) | commit() 将选中项写入编辑器 |
选中项的切换逻辑在模型层(selectNext/selectPrevious,plugin.js):无选中项时分别落到第一个/最后一个,到达边界时循环回到另一端;选中变化通过 change-selectedItemId 事件同步到视图层,由 selectItem() 更新 cke_autocomplete_selected 高亮类并滚动到可见位置。提交键通过 CKEDITOR.config.autocomplete_commitKeystrokes 配置(默认 <a href="https://link.gitcode.com/i/837b2fa48f0fe9c5fecb26b0e984960e" target="_blank"> 9, 13 ],见 [plugin.js),可改为数组或单个键值,也可置空数组完全禁用。
被处理过的按键会调用 evt.cancel() 与 evt.data.preventDefault() 阻止默认行为,并 consumeNext() 让 text watcher 忽略下一次检查,避免面板关闭瞬间的输入误触发。
七、自动化回归测试:模式切换后的按键绑定验证
除了手动测试,仓库还提供了对应的自动化回归测试,位于 tests/plugins/autocomplete/autocomplete.js,测试名称为 test navigation keybindings are registered after changing mode(标注 #3938, #4107):
var editor = this.editors.source,
bot = this.editorBots.standard,
ac1 = new CKEDITOR.plugins.autocomplete( editor, configDefinition ),
ac2 = new CKEDITOR.plugins.autocomplete( editor, configDefinition );
editor.setMode( 'source', function() {
editor.setMode( 'wysiwyg', function() {
resume( function() {
testPanelEvents( ac1, 'The first autocomplete navigation bindings should work' );
testPanelEvents( ac2, 'The second autocomplete navigation bindings should work' );
} );
} );
} );
function testPanelEvents( autocomplete, msg ) {
var spy = sinon.spy( autocomplete, 'onKeyDown' );
bot.setHtmlWithSelection( '' );
editor.editable().fire( 'keydown', new CKEDITOR.dom.event( {} ) );
spy.restore();
assert.isTrue( spy.called, msg );
}
该测试的设计要点与手动用例一一对应:
- 双实例:在同一个编辑器上创建两个 autocomplete 实例,复现 #4107 的「多个实例」前提;
- 模式往返:
setMode( 'source' )后再setMode( 'wysiwyg' ),精确模拟手动测试的步骤 1–2; - 断言目标:用
sinon.spy包裹onKeyDown,在新的 editable 上触发keydown,断言两个实例的onKeyDown均被调用——即contentDom重新绑定机制对每个实例都生效,这与手动测试 Expected 中「两个面板都能用方向键导航」的判定完全同构。
该测试文件的头部声明了 autocomplete,wysiwygarea,sourcearea 插件(autocomplete.js),source 编辑器预设(autocomplete.js)允许 setMode 调用,与手动用例的插件清单保持一致。
八、配套手动测试与进一步探索
sourcemode.md 所在的手动测试目录 tests/plugins/autocomplete/manual/ 还包含一组围绕同一组件的其他手动用例,可作为延伸阅读:
- navigation.md:针对 #3938 的原始单实例键盘导航回归测试——聚焦编辑器、输入
@、用方向键导航,然后切换源码模式再切回,重复步骤验证(可视为 sourcemode 用例的前身); - init.md:验证 autocomplete 在编辑器
instanceReady后才挂载(#2114); - template.html:手动测试的通用模板,展示了通过
CKEDITOR.plugins.autocomplete直接实例化补全组件、以及_helpers/utils.js提供的autocompleteUtils工具函数用法; - _helpers/utils.js:提供
getTextTestCallback()(基于textMatch.match的正则匹配回调)与getDataCallback()(异步数据回调)两个可复用工具。
若需深入源码,推荐按以下路径阅读:
- plugins/mentions/plugin.js:mentions 配置定义(
feed三种形态、marker、minChars、pattern、caseSensitive、cache、throttle默认 200ms)及默认匹配正则的构造(createPattern); - plugins/autocomplete/plugin.js:autocomplete 控制器(
attach、open、commit、onKeyDown)与视图/模型的完整实现,面板定位逻辑(getViewPosition/setPosition)值得重点关注; - plugins/textmatch/plugin.js:
textMatch.match如何在 DOM 相邻文本节点中搜索匹配片段并返回 range; - plugins/sourcearea/plugin.js:源码模式的注册与
source命令的切换逻辑(editor.setMode)。
九、小结:模式切换场景下补全组件的正确姿势
通过本文可以看到,sourcemode.md 虽然只是一份短小的手动测试文档,但它精准刻画了 CKEditor 4 Autocomplete 组件一个容易踩坑的边界场景——编辑器模式切换会重建可编辑区域,导致面板键盘导航监听丢失。围绕它形成的完整防护体系包括:
- 手动回归用例(
sourcemode.md):面向测试人员,用双 mentions 实例覆盖 #4107 的「多实例」症状; - 自动化回归测试(
autocomplete.js中#3938, #4107的用例):面向 CI,用setMode往返 +sinon.spy断言监听重绑; - 源码修复(autocomplete/plugin.js 的
contentDom监听):面向实现,保证每个 autocomplete 实例在新 editable 就绪后立即重挂键盘导航与 ARIA 属性。
对于在自己的项目中直接实例化 CKEDITOR.plugins.autocomplete 或集成 mentions 的开发者,这条经验同样适用:凡是需要在「编辑器模式切换后依然可用」的 UI 行为,都应挂到 contentDom(或等价的可编辑区域重建事件)上重新注册,而不是只在初始化时注册一次。