CKEditor 4 源码模式下的焦点失焦(Blur)行为:focusManager 原理与 16935 回归测试解析

原创2026-10-14 14:01:331,865 阅读
文章标签:前端UI组件

CKEditor 4 源码模式下的焦点失焦(Blur)行为:focusManager 原理与 #16935 回归测试解析

导读

本文围绕 CKEditor 4 官方回归测试文档 sourcemodeblur.md 展开,深入解析编辑器在**源码模式(Source Mode,由 sourcearea 插件提供)**下失去焦点时的内部机制,以及其背后修复的缺陷 trac #16935:Chrome 中在源码模式下失焦会抛出 Cannot read property '$' 错误。读完本文,你将掌握 CKEDITOR.focusManager 的焦点状态机、startupMode: 'source' 的配置方法,以及如何通过 Bender 手动测试与自动化测试两种途径验证该回归场景。

一、这份测试文档在验证什么:缺陷背景 trac #16935

测试文档开头的元数据揭示了它的身份与背景:

@bender-tags: bug, editor, focus, trac16935, 4.7.0
@bender-ui: collapsed
@bender-ckeditor-plugins: toolbar, sourcearea
  • bug:这是一个缺陷回归测试(regression test),而非功能演示;
  • trac16935:对应缺陷编号 #16935;
  • 4.7.0:该缺陷在 4.7.0 版本修复。

在仓库的 CHANGES.md 中可以找到 4.7.0 版本的修复记录:

#16935: [Chrome] Fixed: Blurring the editor in Source Mode throws an error.

翻译过来就是:Chrome 浏览器下,当编辑器处于源码模式时,将焦点移出编辑器(blur)会抛出异常。本文要分析的这份手动测试,正是为了验证该修复是否生效而保留的回归用例。

二、手动测试用例的完整解读

2.1 测试步骤与预期结果(原文档核心内容)

该测试的完整操作流程如下:

  1. 打开控制台(Open console);
  2. 点击编辑器内部(Click inside editor)——让编辑器获得焦点;
  3. 点击页面上的按钮(Click the button)——将焦点从编辑器移出。

预期结果(Expected):

  • 控制台没有任何错误(There is no error in the console)。

在缺陷存在时,第 3 步触发失焦会抛出类似 Cannot read property '$' of null 的异常(详见下文自动化测试的断言),修复后则一切正常。

2.2 配套测试页面的实现

测试文档对应的 sourcemodeblur.html 用 15 行代码还原了整个复现场景:

<body>
<div id="editor">
	<p>Example text</p>
</div>
<button>I'm a button!</button>

<script>
	if ( !CKEDITOR.env.chrome ) {
		bender.ignore();
	}

	CKEDITOR.replace( 'editor', {
		startupMode: 'source'
	} );
</script>
</body>

关键点有两个:

  1. bender.ignore() 的浏览器过滤:由于该缺陷仅在 Chrome 中出现,非 Chrome 环境直接跳过(ignore)本用例。bender.ignore() 是 Bender 测试框架提供的跳过当前用例的接口,在手动测试与单元测试中均可用(参见 tests/_benderjs/ckeditor/static/tools.js 中 bender.testData.manual 与 bender.ignore() 的配合使用)。

  2. startupMode: 'source':编辑器一启动就直接进入源码模式,而不是默认的 WYSIWYG 模式。这是复现该缺陷的前提条件。

2.3 Bender 元数据字段逐项说明

这类 .md 文件是 Bender 框架的手动测试(manual test)规范,三个 @bender-* 注释分别控制测试的执行方式:

元数据字段 作用
@bender-tags 标记测试类型与关联信息,bug 表示回归测试,trac16935 关联缺陷编号,4.7.0 标注修复版本
@bender-ui: collapsed 手动测试 UI 默认折叠,需要手动展开测试面板
@bender-ckeditor-plugins 指定该用例加载的插件列表,这里加载 toolbar 与 sourcearea,后者提供源码编辑模式

三、焦点管理的底层机制:focusManager

要理解"失焦报错"为何会发生,必须先理解编辑器焦点管理的核心类 CKEDITOR.focusManager(实现在 core/focusmanager.js)。

3.1 两个核心状态属性

每个编辑器实例都持有一个 focusManager(core/focusmanager.js),它维护两个关键状态:

  • hasFocus:布尔值,表示编辑器实例当前是否持有焦点;
  • currentActive:当前使编辑器获得焦点的 DOM 元素。

3.2 focus() 与 blur() 的状态转换

focus() 方法(core/focusmanager.js)的工作流程:

  1. 清除可能挂起的失焦定时器;
  2. 若编辑器尚未获得焦点,先让 CKEDITOR.currentInstance(当前持有焦点的其他编辑器)执行 blur( 1 ) 立即失焦,保证事件顺序为 focus 1 → blur 1 → focus 2;
  3. 置 hasFocus = true,给编辑器容器加上 cke_focus 类,并触发编辑器的 focus 事件。

blur() 方法(core/focusmanager.js)则更有意思,它默认是异步的:

var delay = CKEDITOR.focusManager._.blurDelay;   // 默认 200ms
if ( noDelay || !delay ) {
	doBlur.call( this );
} else {
	this._.timer = CKEDITOR.tools.setTimeout( function() {
		delete this._.timer;
		doBlur.call( this );
	}, delay, this );
}
  • 默认 blurDelay 为 200ms(定义于 core/focusmanager.js),这是为了避免"临时失焦"(例如焦点在编辑器内部 UI 元素间短暂迁移)导致编辑器被误判为失焦;
  • 传入 noDelay 参数(如 blur( 1 ))则同步立即执行失焦;
  • doBlur 内部会移除 cke_focus 类并触发编辑器的 blur 事件;
  • 若处于 lock() 锁定状态,blur() 直接返回,unlock() 后恢复自动管理(core/focusmanager.js)。

3.3 焦点事件的注册与委托

编辑器初始化时,core/editable.js 会执行 editor.focusManager.add( this ) 把可编辑区注册进焦点管理器。add() 方法(core/focusmanager.js)会在元素上挂接 focus/blur 监听器:

var listeners = {
	blur: function() {
		if ( element.equals( this.currentActive ) )
			this.blur();
	},
	focus: function() {
		this.focus( element );
	}
};

也就是说:当注册元素获得焦点时,焦点管理器把该元素记为 currentActive 并标记编辑器为聚焦;当它失去焦点时,触发带延迟的失焦流程。

此外,焦点管理器对外暴露的 focus / blur 事件在 core/focusmanager.js 有完整文档:编辑器的 blur 事件在焦点于编辑器内部迁移(如从可编辑区移到对话框)时不会触发,此时应改用 CKEDITOR.editable 上的 focus/blur 事件。

四、源码模式(Source Mode)由什么提供:sourcearea 插件

4.1 addMode('source'):textarea 即编辑器

源码编辑模式由 plugins/sourcearea/plugin.js 插件提供。其核心注册逻辑(plugins/sourcearea/plugin.js)是:

  1. 通过 editor.addMode( 'source', ... ) 注册 source 模式(addMode 定义于 core/creators/themedui.js);
  2. 在 contents 空间中动态创建一个 <textarea>,设置 width: 100%、height: 100%、resize: none 等样式,并附加 cke_source、cke_reset、cke_enable_context_menu 类;
  3. 通过 editor.editable( new sourceEditable( editor, textarea ) ) 将 textarea 包装成可编辑区——源码模式下,textarea 本身既是编辑区域,也是焦点接收元素;
  4. 用 editable.setData( editor.getData( 1 ) ) 把当前内容填入 textarea。

由此可以推断,源码模式下失焦报错的根源在于:焦点在 textarea 与编辑器外部元素(如页面按钮)之间切换时,focusManager 的失焦流程中对已销毁或已分离的 DOM 元素进行了属性访问——Cannot read property '$' 正是访问 null 元素 . $ 属性时的典型报错。

4.2 模式切换与 source 命令

source 命令(plugins/sourcearea/plugin.js)负责 WYSIWYG 与 Source 之间的双向切换,它声明了 modes: { wysiwyg: 1, source: 1 } 且 editorFocus: false(切换模式不强行夺取焦点),并通过 editor.setMode() 完成切换。setMode() 在 core/creators/themedui.js 中实现,模式切换过程会先后触发 beforeSetMode、beforeModeUnload、mode 等事件,并处理快照(snapshot)与脏标记(dirty flag)的同步。

4.3 startupMode 配置项

startupMode 是决定编辑器初始模式的核心配置(定义于 core/creators/themedui.js):

/**
 * @cfg {String} [startupMode='wysiwyg']
 */
CKEDITOR.config.startupMode = 'wysiwyg';
  • 默认值为 'wysiwyg';
  • 设置为 'source' 时,编辑器加载完成后会直接进入源码模式(见 core/creators/themedui.js 中 editor.setMode( editor.config.startupMode, ... ) 的调用);
  • 前提条件:必须同时加载 sourcearea(经典/替换式编辑器)或 sourcedialog(内联编辑器)插件,否则 source 模式不存在,setMode 会因 !modes<a href="https://link.gitcode.com/i/e7247cfb970e01ac614cf9be212f5f9f" target="_blank"> newMode ] 而直接返回([core/creators/themedui.js)。

注意:plugins/sourcearea/plugin.js 明确说明,内联(inline)编辑器不支持 sourcearea 插件,内联编辑器要使用源码模式需依赖 sourcedialog 插件。

4.4 相关配置:sourceAreaTabSize

与源码模式配套的还有 sourceAreaTabSize 配置(plugins/sourcearea/plugin.js),默认值为 4,用于控制源码 textarea 中 Tab 键的显示宽度(通过 CSS tab-size 属性实现),仅在 dataIndentationChars 设为 '\t' 时生效。

五、自动化测试对照:同一场景的双重验证

除了手动测试,仓库中还保留了对应的自动化测试:test blur editor in source mode(tests/core/focusmanager/focusmanager.js)。其思路与手动测试完全一致:

bender.editorBot.create( {
	name: 'test_editor_source',
	config: {
		plugins: 'sourcearea',
		startupMode: 'source'
	}
}, function( bot ) {
	// 1. 监听全局 error 事件,若抛出 "Cannot read property '$'" 则测试失败
	// 2. 同时设置较长定时器:若 200ms 内没有报错,则判定通过
	...
	bot.editor.focus();
	CKEDITOR.document.getById( 'focusable' ).focus();
	wait();
} );

测试细节:

  • 与手动测试一致,仅在 CKEDITOR.env.chrome 下运行,其他浏览器 assert.ignore();
  • 由于异步错误难以用常规断言捕获,测试通过 CKEDITOR.document.getWindow().once( 'error', ... ) 监听全局错误事件,若错误信息包含 Cannot read property '$' 则 assert.fail;
  • 同时用 200ms 定时器兜底:若这段时间内未抛出目标错误,则 assert.pass。

同一目录下 tests/core/focusmanager/editor.js 还覆盖了常规的焦点行为(可编辑区聚焦、工具栏聚焦、对话框打开、组合框打开等场景),并通过断言 fm.hasFocus 与容器上的 cke_focus 类来验证焦点状态。注意其中的 CKEDITOR.focusManager._.blurDelay = 0(tests/core/focusmanager/editor.js)——测试中把失焦延迟设为 0,以消除异步时序对断言的影响,这也印证了前面提到的 blurDelay 机制。

六、如何自己复现与验证

6.1 复现缺陷现场(修复前行为)

只需一个 HTML 页面、一份未修复的 4.6.x 版本 CKEditor(或修改源码移除修复),即可复现:

<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8">
	<script src="ckeditor.js"></script>
</head>
<body>
	<div id="editor"><p>Example text</p></div>
	<button id="outside">I'm a button!</button>
	<script>
		CKEDITOR.replace( 'editor', {
			plugins: 'toolbar,sourcearea',
			startupMode: 'source'
		} );
	</script>
</body>
</html>

打开控制台,执行:点击编辑器内 textarea → 点击页面按钮。在未修复版本中,控制台会抛出 Uncaught TypeError: Cannot read property '$' of null 之类的异常。

6.2 验证修复后的行为(当前仓库状态)

在当前仓库代码(4.7.0 起已修复)中重复上述操作,控制台应保持干净、无任何报错。此即手动测试 sourcemodeblur.md 的全部验证内容。

6.3 通过 Bender 运行相关测试

仓库使用 Bender 测试框架(见根目录 bender.js 与 bender.ci.js)。手动测试在 Bender 面板中以"Manual Test"形式展示,按文档步骤操作即可判定 PASS/FAIL;自动化测试则由 bender test run 之类的命令批量执行 tests/core/focusmanager/ 目录下的用例。

七、小结

sourcemodeblur.md 虽然只有寥寥数行,却浓缩了一个完整的缺陷修复验证闭环:Chrome + 源码模式 + 焦点失焦 这一组合曾是 4.7.0 之前的高危雷区。通过剖析 core/focusmanager.js 的焦点状态机(hasFocus / currentActive / 200ms 异步失焦)、plugins/sourcearea/plugin.js 的 textarea 可编辑区实现,以及 tests/core/focusmanager/focusmanager.js 中利用全局 error 事件捕获异步异常的测试技巧,可以清楚地看到:手动测试与自动化测试互为表里,共同守护编辑器焦点管理的稳定性。当你需要在业务中让编辑器默认进入源码模式并处理失焦场景时,牢记三个要点:加载 sourcearea 插件、设置 startupMode: 'source'、并通过监听编辑器 focus/blur 事件而非 DOM 事件来感知焦点状态。

登录后查看全文
ckeditor4