• 前端
• UI组件

CKEditor 4 的浮动对话框（Dialog）是其插件体系的交互核心，而键盘焦点管理直接决定了残障用户能否顺畅操作。本文将围绕仓库中的手动测试用例 tabsfocus.md 展开，深入剖析"按 Tab 键聚焦到标签页列表（Tab List）、用方向键切换标签页、再回到表单字段"这一完整焦点循环的实现原理，并结合 dialog 插件源码 还原 4.4.8 版本修复的 trac13027 缺陷。读完本文，你将掌握 CKEditor 4 对话框键盘导航的完整机制、相关配置项（如dialog_startupFocusTab），以及如何用 Bender 手动测试框架验证无障碍行为。

一、测试用例背景：trac13027 与 4.4.8 修复

tabsfocus.md 是 Bender 框架下的一个手动测试用例（Manual Test），其头部元数据直接点明了它的历史使命：

@bender-tags: 4.4.8, bug, trac13027, accessibility @bender-ui: collapsed @bender-ckeditor-plugins: wysiwygarea, toolbar, link

• 4.4.8：该用例针对 4.4.8 版本验证的回归场景；
• bug / trac13027：对应 Trac 工单 #13027——在带标签页的多页对话框中，当焦点从最后一个可聚焦字段继续按 Tab 时，焦点应正确落入标签页列表，而不是丢失或产生不可预期的跳转；
• accessibility：该问题属于无障碍（可访问性）范畴，直接影响键盘用户的导航体验；
• 插件组合：wysiwygarea（编辑区）、toolbar（工具栏）、link（链接对话框，用于提供多标签页对话框实例）。

对应的可运行页面是 tabsfocus.html：它仅创建一个带 Apollo 11 文本的编辑器实例，点击工具栏 Link 按钮即可打开带有 "Link info"、"Target" 等多个标签页的链接对话框，为测试提供真实的多 Tab 对话框环境。

二、完整复现测试步骤（原用例逐条继承）

原用例以"步骤 + Expected（期望结果）"的结构描述焦点行为，这是验证修复是否生效的关键路径。以下为完整执行步骤：

1. 点击 Link 按钮，打开链接对话框。

2. 连续按 3 次Tab键。

• Expected（期望）：焦点应落在"Link info" 标签页标题上（即进入标签页列表模式）。

3. 按一次Right（右方向键）。

• Expected：焦点应从第一个标签页移动到第二个标签页（"Target" 标签页）。

4. 按一次Tab键。

• Expected：焦点应移出标签页列表，进入当前激活标签页（"Target"）中的第一个可聚焦字段——即"Target" 字段（链接目标输入框）。

这三步共同勾勒出对话框焦点循环的完整闭环：表单字段 → 标签页列表 → 相邻标签页 → 表单字段。若任一环节焦点丢失或顺序错乱，则说明 trac13027 的回归修复失效。

三、源码级原理：焦点循环是如何实现的

要理解上述测试步骤为何这样设计，需要深入 plugins/dialog/plugin.js 的焦点管理核心。整个机制围绕三个内部状态与两个核心函数展开。

3.1 核心状态：tabBarMode 与 focusList

对话框实例在构造时初始化以下状态（见 plugin.js 第 264-293 行）：

• tabBarMode：布尔值，标记当前焦点是否位于标签页列表（Tab Bar）模式；
• focusList：按 Tab 顺序排列的所有可聚焦控件（文本框、按钮、选择框等）列表；
• currentFocusIndex：当前焦点在focusList中的索引；
• tabs/tabIdList：标签页 DOM 元素与 ID 的映射表；
• currentTabId：当前激活标签页的 ID。

焦点顺序本身由setupFocus()（plugin.js 第 432-447 行）在对话框显示时按浏览器 Tab 顺序逻辑排序：优先按tabIndex降序比较，tabIndex相同时回退到focusIndex，以弥补部分浏览器排序不稳定的问题。

3.2 changeFocus：trac13027 修复的核心

changeFocus( offset )（plugin.js 第 450-499 行）是焦点前移/后移的引擎，offset为1（前进）或-1（后退）。其关键逻辑如下：

1. 若处于tabBarMode且向后移动（offset < 0），则把起点设为 0，模拟从第一个焦点项开始回退；
2. 移动前先对当前输入元素触发blur，保证依赖 blur 的 UI 状态更新（如校验提示）能正常执行；
3. 使用取模运算( currentIndex + focusList.length ) % focusList.length在焦点列表中循环，并跳过不可聚焦（isFocusable()为假）的项。

traC13027 的修复点就藏在第 477-485 行的分支中：

if ( hasTabs && !me._.tabBarMode && ( currentIndex == focusList.length || currentIndex == -1 ) ) { // If the dialog was not in tab mode, then focus the first tab (https://dev.ckeditor.com/ticket/13027). me._.tabBarMode = true; me._.tabs[ me._.currentTabId ][ 0 ].focus(); me._.currentFocusIndex = -1; // Early return, in order to avoid accessing focusList[ -1 ]. return; }

含义拆解：

• hasTabs：pageCount > 1，即对话框确实存在多个标签页；
• !me._.tabBarMode：当前不在标签页列表模式；
• currentIndex == focusList.length || currentIndex == -1：Tab 前进已越过最后一个字段，或 Shift+Tab 后退已越过第一个字段；
• 此时不再按常规方式回绕到 focusList 的头/尾，而是把焦点交给当前激活标签页的标题元素（me._.tabs[ me._.currentTabId ][ 0 ]），置tabBarMode = true、currentFocusIndex = -1，并提前返回，避免访问focusList[-1]。

这正是手动测试第 2 步"按 3 次 Tab 后焦点应在 Link info 标签页"的底层实现。注意：me._.tabs[ id ][ 0 ]是标签页标题元素（<a class="cke_dialog_tab" role="tab">），它在 addPage 创建时 被设置了tabIndex="-1"与hidefocus="true"，目的是让鼠标点击时标签页不抢焦点，但程序化focus()依然有效——这也解释了为什么修复可以安全地把焦点程序化地交给它。

3.3 keydownHandler：键盘事件的全套路由

对话框的键盘处理统一收敛在keydownHandler（plugin.js 第 504-570 行）。它对"对话框是否为当前最顶层"（CKEDITOR.dialog._.currentTop）做了守卫，避免嵌套/多个对话框互相干扰。键盘路由规则如下：

对照手动测试第 3、4 步：在 tabBarMode 下按Right，命中第 524-536 行的方向键分支，通过selectPage( nextId )切换到 "Target" 标签页并聚焦其标题；随后按Tab，命中第 537-543 行的 Enter/Space 分支之外的第 516-519 行 Tab 分支——但此刻tabBarMode仍为true，changeFocus( 1 )会从索引-1开始计算，( -1 + 1 ) % focusList.length = 0，于是焦点落到当前页（Target）的第一个可聚焦字段，即测试期望的"Target" 字段。整个闭环由此打通。

3.4 相关辅助函数

• focusActiveTab( dialog )（plugin.js 第 72-76 行）：设置tabBarMode = true，聚焦当前标签页标题，并把currentFocusIndex置-1，是 Alt+F10 与点击标签页（第 660-672 行的 click 处理）共用的入口；
• getPreviousVisibleTab/getNextVisibleTab（第 82-106 行）：通过offsetHeight判断标签页是否可见，循环扫描tabIdList找到上一个/下一个可见标签页，天然规避被hidePage隐藏的页；
• selectPage（第 1267-1309 行）：切换标签页时同步维护aria-selected、aria-hidden与cke_dialog_tab_selected样式类，保证屏幕阅读器与视觉状态一致。

四、配置项：dialog_startupFocusTab

与标签页焦点相关的另一个常用配置是dialog_startupFocusTab。在 plugin.js 第 608-635 行的自动聚焦逻辑 中：

if ( editor.config.dialog_startupFocusTab && hasTabs ) { me._.tabBarMode = true; me._.tabs[ me._.currentTabId ][ 0 ].focus(); me._.currentFocusIndex = -1; }

当该配置为true时，打开多页对话框的瞬间焦点就直接落在标签页列表上，而不是默认的第一个输入字段（默认走changeFocus( 1 )，或由对话框定义的onFocus回调决定）。仓库中与之配套的手动测试是 startupfocustab.md 与其页面 startupfocustab.html，后者展示了配置用法：

<script> var editor = CKEDITOR.replace( 'editor1', { dialog_startupFocusTab: true } ); </script>

测试期望为："Tab list is focused (you can check this by using left/right arrows - tabs should change)"——即打开对话框后无需按 Tab，直接用左右方向键即可切换标签页，这正是该配置的可验证行为。

五、围绕同一焦点的周边测试用例

仓库在tests/plugins/dialog/manual/下围绕对话框焦点管理维护了一组成体系的手动用例，可作为理解与回归验证的完整矩阵：

• focus.md（4.13.1，bug 3474）：验证点击标签页后再次 Tab 时，焦点应从列表开头重新循环，而不是从之前停留的旧元素继续——防止"点击标签页后焦点残留"问题；
• focusdialogtabhcmoono.md（4.17.2，bug 4934）：高对比度模式（High Contrast Mode）下聚焦标签页标题时，标题应有下划线标识，保证焦点可见性；
• focushcmode.md（4.17.0，bug 4892）：高对比度模式下 OK/Cancel/Close 按钮获得焦点时应有清晰边框；
• startupfocustab.md：上文所述的启动即聚焦标签页配置。

这些用例与 tabsfocus 一起，覆盖了"字段→标签页→字段"循环、点击交互、高对比度可辨识性、启动聚焦四种场景，构成完整的无障碍键盘导航回归防线。

六、自动化测试辅助：dialogTools.changeFocus

除了手动用例，tests/plugins/dialog/_helpers/tools.js还提供了可在 Bender 自动化测试中复用的焦点驱动工具changeFocus( dialog, options )（tools.js 第 34-93 行）。它支持四种交互方式：

1. direction: 'next' | 'previous'：调用对话框的dialog.changeFocus( 1 / -1 )方法模拟 Tab 移动；
2. elementId + tab：通过getContentElement().getInputElement().focus()直接聚焦指定标签页内元素；
3. buttonName：聚焦 OK/Cancel 按钮；
4. key：在dialog._.element上触发带keyCode、shiftKey、altKey的keydown事件，完整模拟键盘输入。

该辅助函数的存在意味着：tabsfocus 描述的三步键盘路径（Tab×3 → Right → Tab）可以转化为changeFocus( dialog, { key: 9 } )与changeFocus( dialog, { key: 39 } )之类的自动化断言，为手动用例提供了可编程的对照实现。

七、如何运行这些手动测试

这些.md用例由 Bender 测试框架驱动。仓库根目录的 bender-runner.config.json 定义了运行环境：Bender 服务默认端口9001、静态服务器端口9002，Linux 下默认浏览器为 Chrome 与 Firefox。结合 package.json 中的benderjs系列开发依赖（benderjs、benderjs-coverage、benderjs-sinon等），典型验证流程为：

1. 安装依赖后启动 Bender 服务（bender server run）；
2. 在浏览器中打开 Runner 页面，过滤dialog/manual/tabsfocus；
3. 按第二节步骤操作：点击 Link → Tab×3 → Right → Tab，逐条核对 Expected；
4. 若需覆盖其他场景，可依次运行startupfocustab、focus及两个高对比度用例。

需要注意：手动测试依赖真实浏览器交互，@bender-ui: collapsed表示界面以折叠形式嵌入测试页，需人工执行键盘操作并目测焦点位置，因此它更适合作为回归验证清单，与自动化断言互补使用。

八、小结

CKEditor 4 对话框的键盘导航并非简单的"下一个控件"，而是一条贯穿字段、标签页、按钮的完整循环。理解changeFocus的边界处理与tabBarMode的状态机转换，既能帮助你排查自定义对话框的焦点异常，也能为插件开发中的无障碍设计提供可参照的范本——这正是 trac13027 修复留给开发者的核心价值。

• 前端
• UI组件