CKEditor 4 Auto Embed 粘贴自动嵌入的通知机制:手动测试用例与源码级解析
CKEditor 4 Auto Embed 粘贴自动嵌入的通知机制:手动测试用例与源码级解析
本篇技术指南以 CKEditor 4 官方仓库中的手动测试文档 notifications.md 为主体,深入剖析 Auto Embed(自动媒体嵌入)插件在粘贴链接时的通知(Notification)机制:从测试用例的搭建、操作步骤,到源码中"嵌入进行中"与"嵌入失败"两类通知的产生、显示与销毁链路。读完本文,你将能独立复现该手动测试,并掌握 autoembed、embedbase、notification 等插件在异步嵌入场景下的协作原理与可配置项。
一、测试文档定位:一张专注"通知行为"的手动用例
该文档位于 tests/plugins/autoembed/manual/notifications.md,是 CKEditor 4 官方测试体系(Bender)中的一份**手动测试(manual test)**用例,其文件头部的元信息定义了测试的属性与运行环境:
@bender-tags: bug, 4.5.2, 4.11.0, trac13566, 2340
@bender-ui: collapsed
@bender-include: ../../embedbase/_helpers/tools.js
@bender-ckeditor-plugins: wysiwygarea,sourcearea,htmlwriter,entities,toolbar,elementspath,undo,clipboard,autolink,autoembed,link
@bender-tags:标注该用例与历史缺陷相关(bug),关联到 4.5.2、4.11.0 两个版本节点以及 trac13566、2340 两个 issue 编号,说明通知机制的修复与回归背景。@bender-ui: collapsed:手动测试页面默认折叠 UI,便于聚焦编辑器本身。@bender-include:引入测试辅助工具,按文档相对路径解析即 tests/plugins/embedbase/_helpers/tools.js,其中定义了embedTools.delayJsonp()、embedTools.mockJsonp()等工具,用于模拟/延迟 oEmbed 的 JSONP 请求(详见第四节)。@bender-ckeditor-plugins:测试页加载的插件集合。核心是autolink(把粘贴的裸 URL 自动转成<a>标签)与autoembed(负责把链接升级为嵌入内容),并辅以undo、clipboard、link等保证完整编辑链路。
二、测试页面搭建:不可嵌入与可嵌入的链接样本
与 md 文档配套的同名 HTML 文件 notifications.html 提供了完整的可运行测试页,它把链接明确分为两类:
不可嵌入的 URL(会被 oEmbed 服务拒绝或无法解析):
<ul>
<li><input type="text" value="http://ckeditor.test/"></li>
<li><input type="text" value="http://foo/bar/"></li>
</ul>
可嵌入的 URL(能被 oEmbed 提供商返回有效内容):
<ul>
<li><input type="text" value="https://placekitten.com/g/200/300"></li>
<li><input type="text" value="https://twitter.com/reinmarpl/status/573118615274315776"></li>
</ul>
页面主体是一个 <textarea id="editor1">,随后初始化编辑器:
<script>
embedTools.delayJsonp();
CKEDITOR.replace( 'editor1', {
extraPlugins: 'embed',
height: 500,
width: 600,
embed_provider: '//ckeditor.iframe.ly/api/oembed?url={url}&callback={callback}'
} );
</script>
这里的两个配置点是理解测试的关键:
embed_provider:oEmbed 内容提供商(provider)的 URL 模板。它支持两个占位符:{url}(要嵌入的媒体地址)与{callback}(JSONP 回调名)。模板默认值在 4.7.0 之前指向//ckeditor.iframe.ly/api/oembed,之后默认为空字符串'',需要显式配置,详见 plugins/embed/plugin.js 中embed_provider配置项的注释说明。embedTools.delayJsonp():来自 tests/plugins/embedbase/_helpers/tools.js。它把CKEDITOR.plugins.embedBase._jsonp.sendRequest包装为延迟1000 + Math.random() * 1000毫秒(约 1~2 秒)后真正发送请求,并返回带cancel()方法的请求对象。这个延迟是手动观察通知"先出现、后消失"的关键前提——如果请求瞬间完成,用户很难看到"嵌入进行中"的通知。
三、手动测试步骤:四步验证通知流程
原文档给出了完整且简明的操作序列,以下按步骤拆解,并结合界面反馈说明每一步的预期:
- 粘贴一个不可嵌入的链接(例如
http://ckeditor.test/,可从页面顶部的输入框中复制)。 - 等待两条通知依次出现:
- 第一条通知告知"嵌入过程正在进行"(Embedding in progress);
- 第二条通知告知"嵌入失败"(Embedding failure)。
原文档特别注明:IE8 不会显示第二条通知,原因是该浏览器存在上游缺陷,导致错误处理无法执行(对应 GitHub issue #2553,该问题同样被
@bender-tags中的 2340 追踪)。
- 粘贴一个可嵌入的链接(例如 placekitten 图片或 Twitter 状态链接)。
- 检查通知是否正确显示、嵌入是否最终成功完成——此时"进行中"通知应消失,链接被替换为真正的嵌入内容(图片、富媒体等)。
这两类场景分别对应源码中通知机制的两条分支:callback(成功)与 errorCallback(失败),下面进入源码层面解析。
四、源码解析:两条通知从何而来、去向何处
4.1 粘贴识别:什么链接才会触发自动嵌入
autoembed 插件的核心逻辑位于 plugins/autoembed/plugin.js。它首先用一条正则校验粘贴内容:
var validLinkRegExp = /^<a[^>]+href="([^"]+)"[^>]*>([^<]+)<\/a>$/i;
在 paste 事件(优先级 20,晚于 autolink 执行,确保裸 URL 已被转为 <a>)中,插件检查粘贴的数据是否满足"恰好一个 <a> 标签铺满整个粘贴内容,且 href 与链接文本相同"(decodeURI( match[ 1 ] ) == decodeURI( match[ 2 ] ))。满足条件时,会给该 <a> 打上 data-cke-autoembed 递增序号标记:
if ( embedCandidatePasted ) {
evt.data.dataValue = '<a data-cke-autoembed="' + ( ++currentId ) + '"' + evt.data.dataValue.substr( 2 );
}
随后在 afterPaste 事件中调用 autoEmbedLink( editor, currentId ) 启动异步嵌入流程。autoEmbedLink 首先查找带标记的锚点,通过 CKEDITOR.plugins.autoEmbed.getWidgetDefinition( editor, href ) 决定使用哪个 widget(由 autoEmbed_widget 配置项控制,默认 'embed,embedSemantic',即按注册顺序取第一个可用的嵌入 widget)。
4.2 第一条通知:嵌入进行中
在 widget 实例化成功之后、发起网络请求之前,插件调用了 editor.showNotification:
notification = editor.showNotification( lang.embeddingInProgress, 'info' );
instance.loadContent( href, {
noNotifications: true,
callback: function() { /* ... */ },
errorCallback: function() { /* ... */ }
} );
-
消息文本来自语言包 plugins/autoembed/lang/en.js:
embeddingInProgress: 'Trying to embed pasted URL...', embeddingFailed: 'This URL could not be automatically embedded.'简体中文版本见 plugins/autoembed/lang/zh-cn.js:
正在尝试嵌入粘贴的 URL 里的媒体内容...与此 URL 无法自动嵌入媒体内容。 -
类型为
info。loadContent显式传入noNotifications: true,是为了避免与embedbase内部基于 NotificationAggregator 的"正在抓取 oEmbed 响应"聚合通知叠加,保证手动测试中观察到的正是autoembed自己这一条"进行中"通知。
4.3 第二条通知:嵌入失败
loadContent 的 errorCallback 分支完整实现了"失败时收起第一条、再弹出第二条"的行为:
errorCallback: function() {
notification.hide();
editor.widgets.destroy( instance, true );
editor.showNotification( lang.embeddingFailed, 'info' );
}
即:先隐藏"进行中"通知 → 销毁临时创建的 widget 实例(此时链接在内容中保留为普通 <a>,不会留下残缺的嵌入占位)→ 显示"嵌入失败"通知。这也是手动测试步骤 2 期待"两条通知"的直接来源。
而成功分支的 callback 中会先把链接替换为嵌入内容(editable.insertElement( wrapper, insertRange ),并处理选区书签与 undo 快照,参见 plugins/autoembed/plugin.js 中对 trac13429 的注释),最后同样 notification.hide() 收起第一条通知——对应手动测试步骤 4 的预期。
4.4 通知底层:notification 插件与时长配置
editor.showNotification 由 plugins/notification/plugin.js 提供(init 中覆写),支持四种类型:info(默认,用于提示)、warning(警告/错误)、success(操作成功)、progress(操作进度)。通知默认停留时长由 notification_duration 配置控制:
} else if ( this.type == 'info' || this.type == 'success' ) {
duration = ( typeof this.editor.config.notification_duration == 'number' ) ?
this.editor.config.notification_duration :
5000;
即 info/success 类型默认 5 秒后自动隐藏(plugins/notification/plugin.js 中 notification_duration 默认值为 5000)。这解释了手动测试中"进行中"通知为何在请求未完成前一直驻留、并在结束后消失。
4.5 网络层:embedbase 的 JSONP 请求与错误回调
真正发起请求的是 embedbase 插件(autoembed 所依赖的 embed / embedsemantic 插件均 requires: 'embedbase')。见 plugins/embedbase/plugin.js:
- 请求通过
CKEDITOR.plugins.embedBase._jsonp.sendRequest( urlTemplate, urlParams, callback, errorCallback )完成,动态创建<script>标签、注册全局 JSONP 回调(CKEDITOR._.jsonpCallbacks),并返回带cancel()的请求对象。 - 当脚本加载失败(如网络错误)时,
errorCallback以'fetchingFailed'作为错误类型被触发;loadContent内部还会通过_handleError在非noNotifications场景下弹出warning类型通知(消息来自 plugins/embedbase/lang/en.js 的fetchingFailed: 'Failed to fetch content for {url}.')。这正是测试页中noNotifications: true的意义所在:手动测试观察到的失败通知,是autoembed层自己的embeddingFailed(info类型),而非 embedbase 聚合层通知。 - 成功响应会经
handleResponse事件与_responseToHtml转换为可嵌入 HTML,支持 oEmbed 的photo、video、rich三种类型;响应还会被缓存(_cache),再次嵌入同一 URL 时直接命中缓存(仍保持异步)。
五、自动化测试佐证:通知次数与类型可被断言
除了手动测试,仓库还提供了对应的自动化测试 tests/plugins/autoembed/autoembednotifications.js,它用 sinon.spy 监听 editor.showNotification,并用 embedTools.mockJsonp 模拟请求,精确验证了手动测试期望的行为:
- 成功场景(
test notifications showed when embedding is finished correctly):断言showNotification只被调用一次,且返回的通知类型为info。 - 失败场景(
test notifications showed when embedding is finished with error):让errorCallback()触发,断言showNotification被调用两次,且两次返回类型均为info——与手动测试"先进行中、后失败"两条通知一一对应。
另可参阅 tests/plugins/autoembed/autoembed.js 中的 test embedding when request failed:请求失败后链接原样保留为 <a>、widget 实例被销毁(instanceDestroyed 事件触发),与 4.3 节的源码逻辑相互印证。注意这些自动化测试在 IE 下会 assert.ignore(),原因与手动测试文档中关于 IE 的提示一致。
六、如何运行这份手动测试
该用例属于 Bender 手动测试(manual test),运行方式受仓库根目录 bender.js(以及 bender-runner.config.json)配置约束:
- 在仓库根目录安装依赖并启动 Bender 测试服务器(Bender 是 CKEditor 4 官方测试运行器,
tests配置段定义了各测试分组,framework: 'yui')。 - 在浏览器中打开该手动测试页面(即 notifications.html 对应的 Bender 测试地址)。
- 按第三节的四步操作逐一验证;由于测试页使用了
embedTools.delayJsonp()引入 1~2 秒随机延迟,请给通知留出足够观察时间。 - 若需修改提供商或可嵌入链接样本,直接调整页面中
embed_provider配置与 URL 列表即可(页面本身即独立 HTML,可脱离测试框架单独打开观察编辑器行为)。
小结
通过这份手动测试用例,可以完整验证 CKEditor 4 autoembed 插件的通知契约:任何满足"整段粘贴内容恰为单个同文本链接"的 URL 都会触发异步嵌入,并先显示一条 info 类型的"嵌入进行中"通知;请求成功则隐藏该通知并替换为嵌入内容,请求失败则隐藏该通知并追加一条"嵌入失败"通知(IE8 除外)。通知的文本、类型、时长均可在语言包与 notification_duration、embed_provider、autoEmbed_widget 等配置项下自定义,整个流程在 autoembednotifications.js 中亦有自动化断言兜底,适合作为理解 CKEditor 4 异步编辑反馈机制的入门案例。