CKEditor 4 Notification 插件无工具栏场景手动测试指南(notoolbarnotifications)

原创2026-10-15 19:30:171,898 阅读
文章标签:前端UI组件

CKEditor 4 Notification 插件无工具栏场景手动测试指南(notoolbarnotifications)

CKEditor 4 的 Notification 插件用于在编辑器内部展示短消息(上传进度、操作结果、警告信息等)。本文以仓库中 Bender 手动测试文档 notoolbarnotifications.md 为核心,讲解如何在移除 toolbar 插件(即无工具栏)的编辑器中正确运行通知功能、验证通知定位与自动关闭行为,并结合 plugins/notification/plugin.js 源码与 tests/plugins/notification 下的自动化测试,剖析其底层实现原理。读完本文,你将掌握 Notification 插件 API 的完整用法、无工具栏布局下的定位算法,以及该手动测试页面的构建与验收方法。

一、测试场景背景:通知插件不依赖工具栏(#491)

在 CKEditor 4 中,notification 插件负责在编辑器编辑区内呈现短暂消息,其设计初衷是替代 alert() 弹窗,用于异步操作结果或内容变化的提示(详见 plugins/notification/plugin.js 中 Notification 类的注释)。该类说明同时强调:通知不应在需要用户响应或与对话框(dialog)配合验证时使用。

历史上,Notification 插件曾隐式依赖 toolbar 插件,导致未启用工具栏的编辑器无法使用通知功能。仓库 CHANGES.md 中 4.7.2 版本的修复记录证实了这一点:

Fixed: Unnecessary dependency on the Editor Toolbar plugin inside the Notification plugin. (#491)

notoolbarnotifications.md 正是针对该问题的回归测试文档,其 Bender 元数据明确标注了测试对象:

@bender-tags: 4.7.2, bug, 491
@bender-ui: collapsed
@bender-ckeditor-plugins: wysiwygarea, notification
@bender-include: _helpers/manualplayground.js
  • 版本标记 4.7.2:该修复于 4.7.2 引入;
  • 标签 bug, 491:属于缺陷回归测试,对应 GitHub issue #491;
  • 插件声明:仅加载 wysiwygarea 与 notification,刻意不加载 toolbar,用于验证无工具栏环境下通知仍能正常工作;
  • 引入辅助脚本 _helpers/manualplayground.js:提供可点击触发的各类通知演示方法。

二、手动测试页面结构:如何在无工具栏编辑器里测通知

手动测试的配套页面为 notoolbarnotifications.html,其结构设计对理解测试目的至关重要。

2.1 用超大 padding 制造滚动环境

页面最外层使用了 padding: 3000px 3000px 3000px 3000px 的容器包裹整个编辑器:

<div style="padding: 3000px 3000px 3000px 3000px;">
	<textarea cols="80" id="editor1" name="editor1" rows="10">
		... 多段 Lorem ipsum 内容 ...
	</textarea>
	...
</div>

这样做的目的有两个:

  1. 制造长页面滚动:通知定位算法需要考虑视口滚动位置,长页面才能验证滚动时通知位置的正确性;
  2. 验证"滚动到页面中央"的测试前提:测试文档第一步就是"如果你看不到编辑器,请将页面滚动到中央"(If you don't see the editor, scroll the page to the center.),配合脚本末尾的 window.scrollTo( 2950, 2950 ) 将页面初始滚动到约 (2950, 2950),使编辑器处于视口中央。

2.2 无工具栏的编辑器初始化

页面脚本通过 CKEDITOR.replace 创建编辑器,并显式移除工具栏相关插件:

var editor = CKEDITOR.replace( 'editor1', {
	extraPlugins: 'notification',
	removePlugins: 'toolbar,clipboard,pastefromword,pastetext,tableselection',
	width: 650,
} );

参数说明:

参数 值 作用
extraPlugins notification 显式加载通知插件(默认构建可能未包含)
removePlugins toolbar,clipboard,pastefromword,pastetext,tableselection 移除工具栏等插件,构造"无工具栏"场景
width 650 固定编辑器宽度,便于观察通知在编辑区内的水平定位

初始化后调用 manualPlayground.init() 绑定通知事件日志,并滚动到指定位置:

manualPlayground.init();
window.scrollTo( 2950, 2950 );

2.3 通过按钮驱动通知演示

页面在编辑器下方提供了 4 个按钮,分别调用辅助脚本中的 4 个演示方法:

<input onclick="manualPlayground.showWarning();" type="button" value="Show warning notification">
<input onclick="manualPlayground.showSuccess();" type="button" value="Show success notification">
<input onclick="manualPlayground.showInfo();" type="button" value="Show info notification">
<input onclick="manualPlayground.emulateProgress();" type="button" value="Show progress notification">

对应 manualplayground.js 中的实现:

showWarning: function() {
	editor.showNotification( 'Vitae risus eget ante <a href="http://test/">mau</a> convallis.', 'warning' );
},
showSuccess: function() {
	editor.showNotification( 'Success!', 'success' );
},
showInfo: function() {
	editor.showNotification( 'Lorem ipsum dolor sit amet, consectetur adipiscing elit...', 'info' );
}

注意 showWarning 的 message 中包含 HTML 链接 <a href="http://test/">mau</a>,说明通知消息支持富文本 HTML,且 skins/moono-lisa/notification.css 中为消息内链接定义了 .cke_notification_message a { color: inherit; } 使其继承通知条配色。

2.4 进度通知的模拟场景

emulateProgress 演示了通知的典型异步场景——文件上传进度:

emulateProgress: function() {
	var notification = editor.showNotification( 'Uploading image.png', 'progress', 0 ),
		scenario = [
			{ progress: 0.05, message: 'Uploading image.png 5%...' },
			{ progress: 0.1, message: 'Uploading image.png 10%...' },
			// ... 每 5% 更新一次 ...
			{ type: 'success', message: 'File image.png uploaded.', important: true }
		];

	var interval = setInterval( function() {
		if ( !scenario.length ) {
			clearInterval( interval );
		} else {
			notification.update( scenario.shift() );
		}
	}, 300 );
}

该示例完整展示了 Notification API 的两大核心方法:

  • showNotification( message, 'progress', 0 ):以 progress 类型、初始进度 0 创建通知;
  • notification.update( { progress, message } ):每 300ms 更新进度与文案;
  • 结束时通过 update( { type: 'success', message: '...', important: true } ) 将通知类型切换为 success,并用 important: true 保证即使通知已被用户关闭也会重新显示。

三、手动测试验收步骤(原文档核心)

原文档给出的验收步骤共 4 条,是测试通过的判据:

  1. 看不到编辑器时,将页面滚动到中央——由于 3000px 的内边距,页面加载后编辑器不在视口内;
  2. 使用按钮操作通知——分别点击 4 个按钮,观察 warning / success / info / progress 四种通知是否正确显示;
  3. 滚动页面,检查通知位置是否正确——通知应始终贴靠在编辑区内部(顶部或底部),不会脱离编辑区;
  4. 重点验证自动关闭:

Note: info and success notifications should close automatically after 5 sec or on ESC key if editor is focused.

即 info 与 success 类型通知应在 5 秒后自动关闭,或在编辑器聚焦时按 ESC 键手动关闭。而 warning 和 progress 通知默认不会自动关闭(见下文源码分析)。

四、Notification API 与源码级实现解析

4.1 editor.showNotification() 的入口

插件初始化时,plugin.js 覆盖了 editor.showNotification 方法(init 函数第 22-41 行):

editor.showNotification = function( message, type, progressOrDuration ) {
	var progress, duration;

	if ( type == 'progress' ) {
		progress = progressOrDuration;
	} else {
		duration = progressOrDuration;
	}

	var notification = new CKEDITOR.plugins.notification( editor, {
		message: message,
		type: type,
		progress: progress,
		duration: duration
	} );

	notification.show();

	return notification;
};

签名 showNotification( message, type, progressOrDuration ) 的关键在于第三参数的语义由 type 决定:

  • type === 'progress' 时,第三参数是 progress(0~1 的进度值);
  • 其他类型时,第三参数是 duration(毫秒),可覆盖自动关闭时长。

该方法会返回 notification 实例,方便后续调用 update() / hide()。

4.2 四种通知类型与时长规则

Notification 类的文档注释定义了四种类型(plugin.js 中 @property {String} type):

类型 用途 自动关闭
info(默认) 信息提示,如"文件正在上传""ACF 修改了内容" 默认 5000ms,可用 config.notification_duration 覆盖
warning 警告或错误,如"不支持该文件类型" 不自动关闭(duration 默认 0)
success 操作成功提示,如"文件已上传" 默认 5000ms
progress 操作进度,完成后应切换为 success 不自动关闭

duration 为 0 表示永不自动关闭、需用户手动关闭。_hideAfterTimeout 私有方法(plugin.js 第 409-430 行)实现了关闭逻辑:

if ( typeof this.duration == 'number' ) {
	duration = this.duration;
} else if ( this.type == 'info' || this.type == 'success' ) {
	duration = ( typeof this.editor.config.notification_duration == 'number' ) ?
		this.editor.config.notification_duration :
		5000;
}

可以看到默认 5000 毫秒的回退值,正对应手动测试文档中"5 sec 自动关闭"的验收判据。同时每次 show() / update() 都会先 clearTimeout 再重新计时,保证更新后计时重置。

4.3 ESC 键关闭与无障碍提示

插件在 init 中注册了 editor.on( 'key', ... ) 监听,捕获 ESC(keyCode 27)并关闭最后一条通知(plugin.js 第 44-64 行):

if ( evt.data.keyCode == 27 ) { /* ESC */
	var notifications = editor._.notificationArea.notifications;
	if ( !notifications.length ) {
		return;
	}
	say( editor.lang.notification.closed );
	notifications[ notifications.length - 1 ].hide();
	evt.cancel();
}

say() 辅助函数通过创建一个 aria-live="assertive"、aria-atomic="true" 的临时隐藏 div 向屏幕阅读器播报"通知已关闭",并在 100ms 后移除该元素。这也是手动测试中"editor is focused 时按 ESC"的前提——键盘事件必须由编辑器触发。

4.4 通知 DOM 结构

每个通知对应一个 div.cke_notification 元素,内部结构(见 skins/moono-lisa/notification.css 头部注释)为:

  • div.cke_notification.cke_notification_<type>:外层容器,带 role="alert" 与 aria-label(无障碍);
  • span.cke_notification_progress:仅 progress 类型存在,宽度按进度百分比设置;
  • p.cke_notification_message:消息文本;
  • a.cke_notification_close:右上角关闭按钮(X),点击后先 editor.focus() 再 hide()(对应手动测试 focus.md 中"点击 X 后编辑器应获得焦点"的验收项)。

进度条宽度通过 _getPercentageProgress() 计算:Math.round( ( this.progress || 0 ) * 100 ) + '%'(如 0.3 → 30%)。

4.5 通知区域 Area 与动态布局算法

所有通知集中在 CKEDITOR.plugins.notification.area(Area 类,plugin.js 第 444 行起),它被挂在 editor._.notificationArea 上:

  • 第一个通知加入时,area 元素(div.cke_notifications_area,z-index 为 config.baseFloatZIndex - 2,默认 10000 - 2 = 9998,参见 core/config.js 中 baseFloatZIndex: 10000)才挂载到文档 body,并绑定滚动/缩放/change 等监听;
  • 最后一个通知移除时,area 从文档脱离并解绑监听;
  • 性能优化:UI 事件通过 CKEDITOR.tools.eventsBuffer( 10, ... ) 缓冲,editor change 通过 eventsBuffer( 500, ... ) 缓冲。

_layout() 是定位核心(plugin.js 第 612-865 行)。其水平定位分支与本文主题直接相关——它会检查工具栏是否存在:

// Check if toolbar exist and if so, then assign values to it (#491).
if ( editor.toolbar ) {
	top = editor.ui.space( editor.config.toolbarLocation );
	topRect = top.getClientRect();
}

由于 notoolbarnotifications.html 移除了 toolbar 插件,editor.toolbar 为空,代码会跳过工具栏相关分支,直接走以下无工具栏分支之一:

  1. contentsRect.top > 0 → setTopStandard():编辑区顶部在视口内时,通知绝对定位在编辑区顶部;
  2. 编辑区顶部被滚出视口、但底部仍可见 → setTopFixed():通知固定定位在视口顶部(position: fixed; top: 0);
  3. 编辑区整体滚出视口 → setBottom():通知绝对定位在编辑区底部。

垂直方向则根据编辑区与通知条宽度、滚动位置,在 setLeft / setLeftFixed / setCenter / setRight / setRightFixed 之间选择,保证通知始终完整落在编辑区内。这一整套分支正是手动测试第 3 步"滚动页面检查通知位置"所要验证的算法行为。

五、配套自动化测试佐证

除手动测试外,仓库提供了多组自动化测试交叉验证同一功能:

  • tests/plugins/notification/notoolbarlayout.js:与手动测试同名的自动化版本,只加载 notification 插件(无 toolbar)。其中 "test for appearing in editable area" 断言通知的 getClientRect() 矩形完全落在 editor.ui.contentsElement 矩形范围内,即通知不会溢出编辑区;
  • tests/plugins/notification/notification.js:覆盖 showNotification 各类型、isVisible、超时自动关闭(用 sinon.useFakeTimers 精确验证 5000ms 默认值、notification_duration: 100 配置值)、ESC 关闭及事件取消行为;
  • tests/plugins/notification/area.js:验证 area 的 add/remove 生命周期与 editor 销毁时的清理;
  • tests/plugins/notification/layout.js:以真实测量数据为基准,mock 编辑区/工具栏/视口矩形,覆盖工具栏顶部、底部以及窄内容/宽内容的各种定位组合(对应代码中 #491、#624 等修复)。

这些测试文件与 notoolbarnotifications.md 共同构成了对通知布局功能的"自动化 + 手动"双重保障。

六、相关手动测试变体

同一目录下还有多份与本次主题密切相关的兄弟测试,可组合使用以覆盖更完整的场景:

手动测试文档 场景差异
notoolbarnotificationsinline.md 同样的无工具栏场景,但编辑器为 CKEDITOR.inline 内联模式,且编辑区仅 250px 宽(验证窄编辑区定位)
toolbarbottom.md 工具栏置于底部(toolbarLocation: 'bottom')时的通知定位
classic.md 经典带工具栏场景,验证常规定位
bodypossition.html 验证 body 为 position: relative 与 static 两种情况下通知的水平偏移计算(配合 _assets 下的两个 HTML 页面)

七、配置项速查

配置项 默认值 说明 源码位置
config.notification_duration 5000 info/success 通知自动关闭毫秒数;0 表示不自动关闭;warning/progress 不受影响 plugins/notification/plugin.js _hideAfterTimeout
config.baseFloatZIndex 10000 通知区域 z-index 在此基础上减 2 core/config.js
config.toolbarLocation 'top' 工具栏位置,影响通知"工具栏下方"定位分支 plugins/notification/plugin.js _layout

八、如何运行手动测试

该手动测试属于 CKEditor 4 的 Bender 测试体系。本地验证方式:

  1. 确保仓库已按 bender.js 与 bender.ci.js 配置初始化 Bender 测试框架;
  2. 启动 Bender 服务器后,在浏览器中打开手动测试页面 notoolbarnotifications.html(手动测试页面由 @bender-ui: collapsed 标记,通过 Bender 的 manual tests 入口运行);
  3. 按第三节的验收步骤操作并核对结果。

对于自动化回归,则运行 notoolbarlayout.js 对应的 bender 测试组,无需人工干预即可验证无工具栏场景下的通知定位正确性。

总结

notoolbarnotifications.md 虽短,却精准刻画了 Notification 插件一个关键能力:在不加载 toolbar 插件的情况下完整工作。从手动测试的验收判据出发,本文还原了其页面构建技巧(超大 padding 制造滚动、removePlugins 移除工具栏、按钮驱动演示)、Notification API 的完整用法(四种类型、progress 更新、important 重显)、以及源码中 Area 布局算法对无工具栏场景的专门处理。将手动测试文档与 plugins/notification/plugin.js、tests/plugins/notification 下的自动化测试对照阅读,即可对该功能的实现与验收形成闭环理解。

登录后查看全文
ckeditor4