CKEditor 4 Autocomplete 键盘导航:手动测试用例解读与源码实现剖析

原创2026-10-14 19:43:131,617 阅读
文章标签:前端UI组件

CKEditor 4 Autocomplete 键盘导航:手动测试用例解读与源码实现剖析

CKEditor 4 的 autocomplete 插件允许在输入特定触发字符(如 @)后弹出建议面板。本篇以仓库中的手动测试用例 navigation.md 为骨架,完整讲解其测试步骤与预期行为,并深入 autocomplete 插件源码 剖析方向键导航、循环选择、提交键处理与源码模式(source mode)切换后导航失效(bug #3938、#4107)的底层原理,帮助开发者理解该功能的实现机制、无障碍(ARIA)设计以及如何在本地复现与验证这些场景。

手动测试用例定位:一份针对键盘导航回归的验收脚本

navigation.md 是 CKEditor 4 测试体系中典型的 manual test(手动测试) 用例,位于 tests/plugins/autocomplete/manual/navigation.md。它以 @bender-tags 元数据明确标注了该用例的验收目标:

@bender-tags: 4.14.1, bug, 3938
@bender-ui: collapsed
@bender-ckeditor-plugins: wysiwygarea, toolbar, basicstyles, autocomplete, textmatch, sourcearea
@bender-include: _helpers/utils.js

其中各字段的含义如下:

元数据字段 值 含义
@bender-tags 4.14.1, bug, 3938 该用例针对 4.14.1 版本中的 bug 编号 3938 编写,用于回归验证
@bender-ui collapsed 测试界面以折叠模式呈现,专注编辑器本身
@bender-ckeditor-plugins wysiwygarea, toolbar, basicstyles, autocomplete, textmatch, sourcearea 测试页需要加载的插件集合,其中 autocomplete 是被测对象,textmatch 提供文本匹配能力,sourcearea 用于验证源码模式切换场景
@bender-include _helpers/utils.js 引入共享测试辅助工具(数据源与回调工厂)

这份用例要验证的核心结论是:在内容编辑(WYSIWYG)模式下,autocomplete 建议面板必须能够完全通过键盘(方向键)进行导航,并且在切换到源码模式再切回之后,键盘导航功能依然可用——这正是 bug #3938 的回归点。

测试步骤逐步拆解

原文档给出了 5 个操作步骤,完整继承如下并逐条解释其验证意图:

  1. 聚焦编辑器(Focus the editor):将光标放入内容区,确保键盘事件落在 editable 元素上。
  2. 输入 @:@ 是测试数据源约定的触发字符,输入后 autocomplete 面板应弹出并展示匹配项。
  3. 使用方向键导航到最新补全项(Navigate to the latest completion item using arrow keys):反复按 ↓ / ↑ 移动选中项。
    • 预期(Expected):你可以使用键盘导航补全面板。
  4. 切换到源码区再切回内容编辑模式(Switch to source area and back to content editing mode):通过工具栏源码按钮完成模式切换。
  5. 重复步骤 1-3:再次验证键盘导航仍生效。

第 4、5 步是整个用例的"灵魂"——它专门针对"源码模式切换后键盘导航失效"这一回归缺陷。若第 5 步中方向键无法再移动选中项,则说明 bug 重新出现,测试失败。

测试页面的工程构成

用例对应的可运行页面是 navigation.html。它创建了一个预置三段 Lorem ipsum 文本的 <textarea id="editor">,并通过以下配置实例化编辑器:

CKEDITOR.replace( 'editor', {
	width: 600,
	extraPlugins: 'textmatch',
	on: {
		instanceReady: function( evt ) {
			new CKEDITOR.plugins.autocomplete( evt.editor, {
				textTestCallback: autocompleteUtils.getTextTestCallback(),
				dataCallback: autocompleteUtils.getDataCallback()
			} );
		}
	}
} );

注意页面开头的两段环境守卫:

bender.tools.ignoreUnsupportedEnvironment( 'autocomplete' );

if ( bender.tools.env.mobile ) {
	bender.ignore();
}

即:在不支持 autocomplete 的环境下跳过测试,且在移动端(无实体键盘)直接忽略该用例——因为本用例依赖方向键导航。

共享辅助工具:测试数据源与回调工厂

_helpers/utils.js(tests/plugins/autocomplete/manual/_helpers/utils.js)提供了两个可复用工厂:

  • getTextTestCallback( config ):返回用于 textTestCallback 的函数,内部调用 CKEDITOR.plugins.textMatch.match( range, matchCallback )。matchCallback 对光标左侧文本执行 config.regex || '@\\w*$' 正则匹配,命中则返回 { start: match.index, end: offset },从而定位触发词范围。
  • getDataCallback( config ):返回用于 dataCallback 的函数,内置 5 条示例数据 @john、@thomas、@anna、@cris、@julia,按 item.name.indexOf( matchInfo.query.toLowerCase() ) == 0 前缀过滤,并支持 config.async 模拟异步延迟返回。

这套辅助工具同时被 optionselection.md、itemslimit.md、outputtemplate.md 等多个 autocomplete 手动测试复用,保证了数据与匹配逻辑在各用例间的一致性。

键盘导航的源码实现:onKeyDown 事件处理

方向键导航的核心实现在 plugins/autocomplete/plugin.js 的 onKeyDown 方法(L579-L612)。当面板处于激活状态(this.model.isActive)时,它对三类按键做出响应:

按键 keyCode 处理逻辑 源码位置
Esc 27 关闭面板并 textWatcher.unmatch() L588-L591
↓ 下箭头 40 this.model.selectNext() L593-L595
↑ 上箭头 38 this.model.selectPrevious() L597-L599
Tab / Enter(提交键) 9 / 13 this.commit() 并 unmatch() L601-L605

任一按键被处理(handled === true)后,代码会执行:

evt.cancel();
evt.data.preventDefault();
this.textWatcher.consumeNext();

cancel() 与 preventDefault() 阻止浏览器默认行为(如方向键移动光标、Enter 换行),而 textWatcher.consumeNext()(plugins/textwatcher/plugin.js 的 consumeNext,L264-L267)会设置 ignoreNext = true,忽略因按键引发的下一次文本检查,避免导航过程中面板被意外重新匹配或关闭。

键盘事件如何被捕获:registerPanelNavigation

onKeyDown 通过 registerPanelNavigation(L324-L333)绑定到 editable 元素:

this._listeners.push( editable.attachListener( editable, 'keydown', function( evt ) {
	this.onKeyDown( evt );
}, this, null, 5 ) );

关键点是监听优先级设为 5,注释明确说明"Priority 5 to get before the enterkey",即 autocomplete 的按键处理先于 enterkey 插件执行,确保方向键和提交键不会被换行、移动光标等行为抢占。同时,源码中特别备注:CKEditor 事件系统不允许同一函数作为同一事件的监听器被注册多次,因此这里使用包装函数,并在每次 contentDom(编辑器内容重新挂载)时重新调用 registerPanelNavigation——这正是修复源码模式切换后导航失效的关键(详见下文 #4107)。

循环选择模型:selectNext / selectPrevious

方向键导航实际作用于 model 层,实现在 L1367-L1401:

  • selectNext():若当前无选中项,则选中第一项(selectFirst);若已选中最后一项(index + 1 == this.data.length),则回绕到第一项,否则选中下一项。
  • selectPrevious():若当前无选中项,则选中最后一项(selectLast);若已选中第一项(index <= 0),则回绕到最后一项,否则选中上一项。

即导航是首尾循环的:↓ 在末尾会跳回首项,↑ 在首项会跳回末项。这也解释了测试步骤中"navigate to the latest completion item"的语义——在 5 条数据上不断按 ↓ 即可循环遍历全部建议项。

选中变化通过 select( itemId ) 触发 change-selectedItemId 事件,进而由 onSelectedItemId(L620-L628)同步高亮视图项并更新 aria-activedescendant。此外,面板打开时 model 会默认调用 selectFirst(),保证首个建议项默认被选中(对应 optionselection.md 用例中"First autocomplete option is selected"的预期)。

提交键配置:autocomplete_commitKeystrokes

方向键只负责移动选中项,真正"确定选择"依赖提交键。默认提交键在 L1500-L1522 定义:

CKEDITOR.config.autocomplete_commitKeystrokes = [ 9, 13 ];  // 9 = Tab, 13 = Enter
  • 可通过 config.autocomplete_commitKeystrokes 全局覆盖,例如仅保留 Enter:config.autocomplete_commitKeystrokes = [ 13 ];
  • 可设为空数组 [] 完全禁用提交快捷键;
  • 也可在实例层面通过 Autocomplete#commitKeystrokes 属性单独调整(L160-L219)。

onKeyDown 中使用 CKEDITOR.tools.indexOf( this.commitKeystrokes, keyCode ) 判断当前按键是否为提交键,命中后调用 commit() 将选中项 HTML 插入编辑器并替换查询文本。

回归背景:bug #3938 与源码模式切换问题 #4107

#3938:4.14.1 修复的键盘导航回归

navigation.md 的 @bender-tags: 4.14.1, bug, 3938 表明该用例正是为了验收 4.14.1 版本对 #3938 的修复。结合测试步骤可以推断:该 bug 的表现是 autocomplete 建议面板无法用键盘导航(可能方向键事件未被正确捕获或选择状态未同步),修复后补充了此手动用例用于持续回归。仓库中与 #3938 同期的 optionselection.md(@bender-tags: 4.10.0, bug, tp3558)则验证了"面板打开后首项即被选中"的配套行为。

#4107:源码模式切换后导航失效

与 navigation.md 配套的姊妹用例 sourcemode.md(@bender-tags: 4.15.0, bug, 4107)更进一步,明确描述了该场景的预期与异常:

  • 预期:在 @ 与 # 两个触发词下,切换源码模式后,两个补全面板都能继续用方向键导航。
  • 异常:切换源码模式后,方向键导航对其中一个或全部面板失效。

对应修复在 plugins/autocomplete/plugin.js 的 attach() 中(L315-L321):每次编辑器触发 contentDom(从源码模式切回 WYSIWYG 模式会重建可编辑内容)时,都重新执行 registerPanelNavigation() 与 addAriaAttributesToEditable()。这是 navigation.md 第 4、5 步"切到源码区再切回、重复方向键导航"之所以存在的底层原因——面板的键盘监听器必须随内容 DOM 重建而重新绑定。

无障碍支持:方向键导航背后的 ARIA 实现

键盘导航并非仅服务于效率,autocomplete 面板还同步维护了完整的 ARIA 状态(L338-L400),确保屏幕阅读器用户也能感知面板状态:

ARIA 属性 作用 更新时机
aria-controls 指向面板元素 ID,声明 editable 控制该面板 初始化 / contentDom
aria-expanded 面板展开状态 true/false 面板激活状态变化
aria-activedescendant 指向当前选中项的 ID,替代真实焦点移动 每次选中项变化(onSelectedItemId)
aria-autocomplete 值为 list;销毁时置为 none 初始化 / 销毁

同时 L303-L306 对面板 mousedown 调用 preventDefault()(对应 #2107),阻止下拉元素抢走编辑器焦点——这样无论用户用鼠标还是键盘操作,焦点始终留在可编辑区域,方向键事件才能持续命中 onKeyDown。键盘导航正是依赖"焦点不离开编辑器"这一设计才得以成立。

在本地运行与复现该用例

手动测试用例无法直接双击打开,需通过 Bender 测试框架运行。仓库根目录的 bender.js、bender.ci.js 与 bender-runner.config.json 定义了测试宿主,开发者可在本地按以下方式进入手动测试列表:

# 启动 Bender 服务器后访问手动测试索引,定位 autocomplete 分组
bender server run

随后在浏览器中打开对应用例页面(如 navigation.html),按照文档 1-5 步操作即可。判定标准严格遵循文档中的 Expected 描述:键盘可导航、模式切换后仍可导航;出现文档 Unexpected(sourcemode.md 中列出的"切换后导航失效")即视为回归。相关自动化断言还可参考 tests/plugins/autocomplete 目录下的其他用例,与手动用例共同构成对该插件交互能力的完整覆盖。

登录后查看全文
ckeditor4