CKEditor 4 Auto Embed 粘贴自动嵌入的通知机制:手动测试用例与源码级解析

原创2026-10-14 20:06:102,308 阅读
文章标签:前端UI组件

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() 方法的请求对象。这个延迟是手动观察通知"先出现、后消失"的关键前提——如果请求瞬间完成,用户很难看到"嵌入进行中"的通知。

三、手动测试步骤:四步验证通知流程

原文档给出了完整且简明的操作序列,以下按步骤拆解,并结合界面反馈说明每一步的预期:

  1. 粘贴一个不可嵌入的链接(例如 http://ckeditor.test/,可从页面顶部的输入框中复制)。
  2. 等待两条通知依次出现:
    • 第一条通知告知"嵌入过程正在进行"(Embedding in progress);
    • 第二条通知告知"嵌入失败"(Embedding failure)。 原文档特别注明:IE8 不会显示第二条通知,原因是该浏览器存在上游缺陷,导致错误处理无法执行(对应 GitHub issue #2553,该问题同样被 @bender-tags 中的 2340 追踪)。
  3. 粘贴一个可嵌入的链接(例如 placekitten 图片或 Twitter 状态链接)。
  4. 检查通知是否正确显示、嵌入是否最终成功完成——此时"进行中"通知应消失,链接被替换为真正的嵌入内容(图片、富媒体等)。

这两类场景分别对应源码中通知机制的两条分支: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)配置约束:

  1. 在仓库根目录安装依赖并启动 Bender 测试服务器(Bender 是 CKEditor 4 官方测试运行器,tests 配置段定义了各测试分组,framework: 'yui')。
  2. 在浏览器中打开该手动测试页面(即 notifications.html 对应的 Bender 测试地址)。
  3. 按第三节的四步操作逐一验证;由于测试页使用了 embedTools.delayJsonp() 引入 1~2 秒随机延迟,请给通知留出足够观察时间。
  4. 若需修改提供商或可嵌入链接样本,直接调整页面中 embed_provider 配置与 URL 列表即可(页面本身即独立 HTML,可脱离测试框架单独打开观察编辑器行为)。

小结

通过这份手动测试用例,可以完整验证 CKEditor 4 autoembed 插件的通知契约:任何满足"整段粘贴内容恰为单个同文本链接"的 URL 都会触发异步嵌入,并先显示一条 info 类型的"嵌入进行中"通知;请求成功则隐藏该通知并替换为嵌入内容,请求失败则隐藏该通知并追加一条"嵌入失败"通知(IE8 除外)。通知的文本、类型、时长均可在语言包与 notification_duration、embed_provider、autoEmbed_widget 等配置项下自定义,整个流程在 autoembednotifications.js 中亦有自动化断言兜底,适合作为理解 CKEditor 4 异步编辑反馈机制的入门案例。

登录后查看全文
ckeditor4