CKEditor 4 Notification 插件无工具栏场景手动测试指南(notoolbarnotifications)
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>
这样做的目的有两个:
- 制造长页面滚动:通知定位算法需要考虑视口滚动位置,长页面才能验证滚动时通知位置的正确性;
- 验证"滚动到页面中央"的测试前提:测试文档第一步就是"如果你看不到编辑器,请将页面滚动到中央"(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 条,是测试通过的判据:
- 看不到编辑器时,将页面滚动到中央——由于 3000px 的内边距,页面加载后编辑器不在视口内;
- 使用按钮操作通知——分别点击 4 个按钮,观察 warning / success / info / progress 四种通知是否正确显示;
- 滚动页面,检查通知位置是否正确——通知应始终贴靠在编辑区内部(顶部或底部),不会脱离编辑区;
- 重点验证自动关闭:
Note:
infoandsuccessnotifications should close automatically after 5 sec or onESCkey 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 为空,代码会跳过工具栏相关分支,直接走以下无工具栏分支之一:
contentsRect.top > 0→setTopStandard():编辑区顶部在视口内时,通知绝对定位在编辑区顶部;- 编辑区顶部被滚出视口、但底部仍可见 →
setTopFixed():通知固定定位在视口顶部(position: fixed; top: 0); - 编辑区整体滚出视口 →
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 测试体系。本地验证方式:
- 确保仓库已按 bender.js 与 bender.ci.js 配置初始化 Bender 测试框架;
- 启动 Bender 服务器后,在浏览器中打开手动测试页面 notoolbarnotifications.html(手动测试页面由
@bender-ui: collapsed标记,通过 Bender 的 manual tests 入口运行); - 按第三节的验收步骤操作并核对结果。
对于自动化回归,则运行 notoolbarlayout.js 对应的 bender 测试组,无需人工干预即可验证无工具栏场景下的通知定位正确性。
总结
notoolbarnotifications.md 虽短,却精准刻画了 Notification 插件一个关键能力:在不加载 toolbar 插件的情况下完整工作。从手动测试的验收判据出发,本文还原了其页面构建技巧(超大 padding 制造滚动、removePlugins 移除工具栏、按钮驱动演示)、Notification API 的完整用法(四种类型、progress 更新、important 重显)、以及源码中 Area 布局算法对无工具栏场景的专门处理。将手动测试文档与 plugins/notification/plugin.js、tests/plugins/notification 下的自动化测试对照阅读,即可对该功能的实现与验收形成闭环理解。