CKEditor 4 底部工具栏模式下的 Notification 定位:toolbarbottom 手动测试用例与源码机制解析

原创2026-10-15 19:35:201,391 阅读
文章标签:前端UI组件

CKEditor 4 底部工具栏模式下的 Notification 定位:toolbarbottom 手动测试用例与源码机制解析

CKEditor 4 的 Notification 插件用于在编辑器内短暂展示提示信息(如文件上传结果、内容变更提醒),而它的定位逻辑与工具栏的位置(top 或 bottom)直接相关。本文以仓库中的手动测试用例 toolbarbottom.md 为主线,完整解读其 Bender 测试标签、配套测试页面配置、操作验证步骤,并结合 plugins/notification/plugin.js 的 _layout 源码与 layout.js 自动化测试,讲清 Notification 在底部工具栏场景下如何选择定位模式、为什么会出现历史 Bug(#624)以及如何验证修复效果。读完本文,你将能理解并手动复现该测试场景,也能掌握 Notification 插件布局算法的核心分支逻辑。

测试用例背景:一个针对 #624 Bug 的回归验证

该手动测试用例在 Bender 测试标签中明确标记了来源与类型:

@bender-tags: 4.14.1, bug, 624
@bender-ui: collapsed
@bender-ckeditor-plugins: wysiwygarea, toolbar, undo, basicstyles, notification, floatingspace
@bender-include: _helpers/manualplayground.js
  • 4.14.1 表示该用例随 4.14.1 版本引入,用于回归验证;
  • bug, 624 指向 CHANGES.md 中记录的修复项:"Fixed: Notification does not work with the bottom toolbar location"(对应 GitHub issue #624);
  • 加载的插件组合为 wysiwygarea, toolbar, undo, basicstyles, notification, floatingspace,其中 notification 是核心被测插件,toolbar 与 floatingspace 负责渲染工具栏,wysiwygarea 提供经典(iframe)编辑区;
  • @bender-include 引入了共享辅助脚本 _helpers/manualplayground.js,为页面提供"显示各类通知"的按钮与事件日志能力。

在 CKEditor 4.14.1 之前,当 config.toolbarLocation 设为 'bottom' 时,Notification 的定位逻辑存在缺陷,通知条可能出现在错误位置甚至不可见。该手动用例的作用,就是在真实浏览器中滚动页面、反复触发通知,确认修复后的定位行为在所有视口滚动状态下都正确。

测试页面配置:如何复现底部工具栏 + 通知场景

配套的 toolbarbottom.html 完整演示了该场景的搭建方式,核心配置如下:

var editor = CKEDITOR.replace( 'editor', {
	toolbarLocation: 'bottom',      // 工具栏渲染到编辑区底部
	extraPlugins: 'notification',   // 加载 Notification 插件
	width: 650,                     // 编辑器宽度
	toolbar: [ [ 'Undo', 'Redo' ], [ 'Bold', 'Italic', 'Underline' ] ]
} );

manualPlayground.init();
window.scrollTo( 2950, 2950 );      // 页面被大量 padding 撑高后定位到中部

页面结构上有一个值得注意的细节:编辑器被包裹在一个 padding: 3000px 3000px 3000px 3000px 的容器内,并且脚本执行了 window.scrollTo( 2950, 2950 )。这是为了模拟"编辑器位于长页面中部、用户已向下滚动"的真实浏览环境——这正是 Notification 定位最容易出问题的场景:页面滚动后,position: absolute 与 position: fixed 的计算基准不同,通知条必须根据滚动位置动态切换定位模式。

toolbarLocation: 'bottom' 这一配置项的定义在 plugins/toolbar/plugin.js 中,默认值为 'top',注释明确说明它只适用于经典(iframe 型)编辑器;对于内联编辑器,工具栏位置会依据可编辑元素在屏幕上的位置动态决定。

手动验证步骤与预期结果

该用例文档的操作说明虽然精炼,但每一步都对应明确的预期行为:

  1. "If you don't see the editor, scroll the page to the center."——由于页面被 3000px 的 padding 撑开,进入页面后必须先滚动到中部才能看到编辑器,这本身就是对"滚动后定位"的第一步验证。
  2. "Play with notification using buttons."——点击页面上的四个按钮分别触发 warning、success、info 和模拟的 progress 通知。这四个按钮由 manualplayground.js 提供:
    • showWarning() 调用 editor.showNotification( '...', 'warning' );
    • showSuccess() 调用 editor.showNotification( 'Success!', 'success' );
    • showInfo() 调用 editor.showNotification( '...', 'info' );
    • emulateProgress() 以 300ms 为间隔,用 notification.update() 依次推进 5%、10%……直到 95% 的进度条,最后更新为 { type: 'success', message: 'File image.png uploaded.', important: true } 完成一次完整的"上传进度 → 成功"模拟。
  3. "Using scroll, check if position of notification is correct."——在页面上下滚动的同时反复触发通知,观察通知条是否始终贴合编辑器内容区,而不是脱离编辑器、固定在视口顶部或底部。
  4. "Note: info and success notifications should close automatically after 5 sec or on ESC key if editor is focused."——这是对自动关闭与键盘关闭两条行为的验证:
    • 自动关闭:info 和 success 类型默认在 5 秒(5000ms)后自动隐藏,可由 config.notification_duration 覆盖;而 warning 与 progress 永远不会自动关闭(源码见 plugins/notification/plugin.js 的 _hideAfterTimeout,对应配置项定义见同文件 plugin.js);
    • ESC 关闭:编辑器获得焦点时按 ESC 会关闭最后一条通知,同时通过一个带 aria-live="assertive" 的临时元素向屏幕阅读器播报关闭信息(源码见 plugin.js)。

源码级原理:底部工具栏下的四种垂直定位模式

要理解这个用例为什么能验证 #624 的修复,需要看 plugins/notification/plugin.js 中 Area.prototype._layout 的垂直定位分支。每次通知显示、窗口滚动/缩放、编辑器内容变化或失焦时,_layout 都会基于编辑区矩形、工具栏矩形、滚动位置和视口尺寸重新计算位置,并按以下顺序决策:

  1. setBelowToolbar(fixed):当工具栏可见,且工具栏底边位于编辑区顶部之下、编辑区底部减去通知高度之上时,通知以 position: fixed 固定渲染在工具栏正下方。对应 toolbarLocation: 'top' 且工具栏未滚出视口的常见情况。
  2. setTopStandard(absolute):编辑区顶部仍在视口内(contentsRect.top > 0)时,通知以 position: absolute 定位在编辑区内容顶部,随页面滚动自然移动。
  3. setTopFixed(fixed):编辑区顶部已滚出视口、但编辑区底部仍可能在视口内时,通知改为 position: fixed; top: 0 固定在视口顶端,保证用户在滚动阅读时始终能看到通知。
  4. setBottom(absolute):其余情况下,通知以 position: absolute 定位在编辑区内容底部(contentsPos.y + contentsRect.height - areaRect.height)。

此外还有一个关键细节:当存在工具栏时,代码通过 editor.ui.space( editor.config.toolbarLocation ) 获取工具栏所在的空间(plugin.js)。这里直接读取的是 toolbarLocation 配置值本身——在 4.14.1 之前的实现中,该处对底部工具栏的处理不完善,导致 toolbarLocation: 'bottom' 时通知条布局异常,这正是 #624 的根因所在。修复后,_layout 在工具栏位于底部时也能正确进入 setTopStandard / setTopFixed / setBottom 等分支,使通知始终保持在编辑区可视范围内。

水平方向同样有 setLeft、setLeftFixed、setCenter、setRight、setRightFixed 五种模式(plugin.js),根据内容宽度与通知宽度的相对关系、左右视口边界自动居中或对齐,保证通知条不会超出视口。

自动化测试佐证:layout.js 中的底部工具栏回归用例

手动用例之外,仓库还提供了纯自动化的布局回归测试 tests/plugins/notification/layout.js。该文件专门注册了两个编辑器实例,其中一个显式配置 toolbarLocation: 'bottom':

bender.editors = {
	top: {},
	bottom: {
		config: {
			toolbarLocation: 'bottom'
		}
	}
};

随后用 createLayoutTest 通过 sinon 打桩模拟工具栏矩形、内容区矩形、滚动位置与视口尺寸,并针对 #624 添加了三个底部工具栏场景的断言(文件中的 // (#624) 注释标明了归属):

  • "test horizontal bottom toolbar with viewport at the top":视口位于页面顶端时,期望 position: absolute; top: 752px;
  • "test horizontal bottom toolbar with viewport in the middle":视口位于页面中部时,期望 position: fixed; top: 0px;
  • "test horizontal bottom toolbar with viewport below":视口位于页面底部时,期望 position: absolute; top: 1014px。

这三个用例与手动用例文档中的"滚动页面检查定位"步骤一一对应,分别覆盖了滚动前、滚动中、滚动到底三种视口状态,形成"手动验证 + 自动断言"的双重回归保障。测试文件头部注释也说明了设计动机:这类测试的输入输出基于人工核对过的真实定位数据,主要用于确保 _layout 逻辑在所有浏览器上行为一致、无语法错误,且未来不会意外改变。

相关测试资产与延伸阅读

小结

toolbarbottom 手动测试用例虽然只有寥寥数行文档,但它承载的是一个真实且典型的回归验证场景:经典编辑器 + 底部工具栏 + 长页面滚动。通过理解 Bender 标签的含义、页面配置中 toolbarLocation: 'bottom' 的作用、_layout 源码中的四种垂直定位分支,以及 layout.js 中三组针对 #624 的自动化断言,你可以完整掌握 Notification 插件定位算法的行为边界,并将其迁移到自己的项目中:凡是使用底部工具栏的自定义配置,都应参照该用例验证通知条在滚动前、滚动中、滚动到底三种状态下均能正确定位。

登录后查看全文
ckeditor4