CKEditor 4 粘贴通知(Paste Notification)机制深度解析:从手工测试到源码实现

原创2026-10-15 13:50:551,410 阅读
文章标签:前端UI组件

CKEditor 4 粘贴通知(Paste Notification)机制深度解析:从手工测试到源码实现

导读

在 CKEditor 4 中,当浏览器安全策略禁止编辑器通过工具栏按钮或右键菜单直接访问剪贴板时,粘贴操作会被拦截,此时编辑器会向用户弹出一条引导提示——"请按下某个快捷键完成粘贴"。这条提示就是 Paste Notification(粘贴通知)。本文以仓库中的手工测试用例 pastenotification.md 为起点,完整还原该功能的预期行为、各浏览器下的快捷键差异,并深入 clipboard、pastetext、pastefromword 三个插件源码,讲清通知的触发链路、消息模板、时长配置与关闭方式。读完本文,你将能独立复现该测试、理解通知背后的命令执行流程,并能在自己的集成项目中定制这一交互细节。

一、功能背景:为什么需要粘贴通知

浏览器出于安全考虑,普遍禁止网页脚本"自动"执行粘贴:document.execCommand( 'paste' ) 在大多数浏览器中要么抛出异常,要么静默失败。CKEditor 4 的 clipboard 插件在点击工具栏 Paste 按钮、Paste from Word 按钮或执行 Paste as plain text 命令时,会尝试通过 execCommand 触发系统粘贴;一旦失败,编辑器的兜底策略就是弹出通知,告诉用户"请改用键盘快捷键粘贴"。

这正是 tests/plugins/clipboard/manual/pastenotification.md 这个手工测试所验证的核心行为。

测试环境声明

该测试文档的头部声明了运行所需的 Bender 配置:

@bender-tags: bug, 4.7.0, tp2098, 4.9.0, 1363
@bender-ui: collapsed
@bender-ckeditor-plugins: wysiwygarea, toolbar, clipboard, pastefromword, pastetext
  • 4.7.0 / 4.9.0:标记该功能及测试引入的版本节点(通知机制在 4.7.0 加入,addPasteButton 等移动端适配在 4.9.0 完善);
  • 加载的插件集合 wysiwygarea, toolbar, clipboard, pastefromword, pastetext 正好覆盖"普通粘贴 + 从 Word 粘贴 + 纯文本粘贴"三种入口;
  • 对应的测试页面 pastenotification.html 在移动端直接 bender.ignore() 跳过——因为该测试只针对桌面端浏览器。

二、复现测试:三步验证粘贴通知

按文档中的步骤操作,即可在桌面浏览器中复现:

  1. 点击工具栏上的 Paste 按钮;
  2. 依次再点击 Paste from Word 与 Paste as plain text 两个按钮。

预期结果

  • 对每一个按钮,编辑器都会弹出通知,文案为:

    Press keystroke to paste. Your browser doesn't support pasting with the toolbar button or context menu option.

    其中 keystroke 会以 <kbd> 标签形式渲染成对应的快捷键组合。

  • 对 Paste 与 Paste from Word,通知中的快捷键为 Cmd/Ctrl+V;

  • 对 Paste as plain text,通知中的快捷键依浏览器而异:

    • Safari:Cmd+Alt+Shift+V;
    • Edge 和 IE:Ctrl+V;
    • 其他浏览器(Firefox、Chrome、Opera):Cmd/Ctrl+Shift+V。

IE 特例

文档末尾特别注明:在 IE 中,如果用户在弹出的安全对话框中允许了直接访问剪贴板,则不会再显示任何通知。

这一点与源码逻辑完全吻合:getClipboardDataDirectly() 在 IE 中若成功取到剪贴板数据,callback 会带着数据被调用,通知分支被跳过(详见下文第三、四节)。

三、通知消息从哪来:命令执行与消息模板

1. 统一的命令入口:paste 命令

三个按钮最终都会收敛到 clipboard 插件注册的 paste 命令(plugins/clipboard/plugin.js)。该命令的 exec 方法负责拼装通知消息:

exec: function( editor, data ) {
    data = typeof data !== 'undefined' && data !== null ? data : {};

    var cmd = this,
        notification = typeof data.notification !== 'undefined' ? data.notification : true,
        forcedType = data.type,
        keystroke = CKEDITOR.tools.keystrokeToString( editor.lang.common.keyboard,
            editor.getCommandKeystroke( this ) ),
        msg = typeof notification === 'string' ? notification : editor.lang.clipboard.pasteNotification
            .replace( /%1/, '<kbd aria-label="' + keystroke.aria + '">' + keystroke.display + '</kbd>' ),
        ...

关键点拆解:

  • data.notification 支持三种取值:

    • true(默认):使用 editor.lang.clipboard.pasteNotification 模板;
    • 字符串:直接作为自定义通知文案;
    • false:完全不显示通知。
  • 消息模板 pasteNotification 中只有一个占位符 %1,会被替换为 <kbd> 包裹的快捷键。英文原文(plugins/clipboard/lang/en.js):

    pasteNotification: 'Press %1 to paste. Your browser doesn't support pasting with the toolbar button or context menu option.'
    

    简体中文(plugins/clipboard/lang/zh-cn.js)为:

    pasteNotification: '您的浏览器不支持通过工具栏或右键菜单进行粘贴,请按 %1 进行粘贴。'
    
  • 快捷键通过 editor.getCommandKeystroke( this ) 取得,再经 CKEDITOR.tools.keystrokeToString 转换成可读的 display 文本与无障碍用的 aria 文本。

2. 通知的展示与失败判定

命令执行后,若剪贴板数据获取失败,才走通知分支:

function callback( data, withBeforePaste ) {
    ...
    if ( data ) {
        data.method = 'paste';
        ...
        firePasteEvents( editor, data, withBeforePaste );
    } else if ( notification && !editor._.forcePasteDialog ) {
        editor.showNotification( msg, 'info', editor.config.clipboard_notificationDuration );
    }
    ...
}

这里有两个值得注意的细节:

  • 只要 data 为空(拿不到剪贴板内容),且通知未禁用、且不是移动端强制粘贴对话框模式(editor._.forcePasteDialog),就调用 editor.showNotification( msg, 'info', duration ) 展示通知;
  • data 为空但用户其实有内容可粘贴的场景,正是"浏览器禁止脚本直接访问剪贴板"的典型情况,所以通知文案才强调"请按快捷键粘贴"。

3. 通知时长配置:clipboard_notificationDuration

通知展示时长由配置项控制(plugins/clipboard/plugin.js):

/**
 * Duration of the notification displayed after pasting was blocked by the browser.
 *
 * @since 4.7.0
 * @cfg {Number} [clipboard_notificationDuration=10000]
 * @member CKEDITOR.config
 */
CKEDITOR.config.clipboard_notificationDuration = 10000;
  • 默认值为 10000 毫秒(10 秒);

  • 在初始化编辑器时可覆盖,例如:

    CKEDITOR.replace( 'editor1', {
        clipboard_notificationDuration: 5000
    } );
    

    该值同时被用于剪贴板中"不支持的文件类型"通知(displayUnsupportedFileTypesNotification,见 plugins/clipboard/plugin.js),属于 clipboard 插件的通用通知时长。

四、三个按钮的差异化实现:快捷键如何"因浏览器而异"

1. Paste from Word:透传默认快捷键

pastefromword 插件注册 pastefromword 命令,执行时直接以 type: 'html' 转调 paste 命令,并透传 notification 选项:

exec: function( editor, data ) {
    forceFromWord = 1;
    editor.execCommand( 'paste', {
        type: 'html',
        notification: data && typeof data.notification !== 'undefined' ? data.notification : true
    } );
}

因为最终落到 paste 命令,而 paste 命令的 fakeKeystroke 是 CKEDITOR.CTRL + 86 /*V*/(即 Cmd/Ctrl+V),所以 Paste from Word 的通知快捷键与普通 Paste 完全一致,都是 Cmd/Ctrl+V。

工具栏按钮通过 CKEDITOR.plugins.clipboard.addPasteButton( editor, 'PasteFromWord', ... ) 注册,位于 clipboard,50 分组。

2. Paste as plain text:按浏览器选取快捷键

pastetext 插件是差异化最明显的一处。它的命令 exec 在拼通知消息时,会根据浏览器选择要展示的快捷键:

exec: function( editor, data ) {
    var lang = editor.lang,
        // In IE we must display keystroke for `paste` command as blocked `pastetext`
        // can fallback only to native paste.
        keyInfo = CKEDITOR.tools.keystrokeToString( lang.common.keyboard,
            editor.getCommandKeystroke( CKEDITOR.env.ie ? editor.commands.paste : this ) ),
        notification = ( data && typeof data.notification !== 'undefined' ) ? data.notification :
            !data || !data.from || ( data.from === 'keystrokeHandler' && CKEDITOR.env.ie ),
        msg = ( notification && typeof notification === 'string' ) ? notification : lang.pastetext.pasteNotification
            .replace( /%1/, '<kbd aria-label="' + keyInfo.aria + '">' + keyInfo.display + '</kbd>' );

    editor.execCommand( 'paste', {
        type: 'text',
        notification: notification ? msg : false
    } );
}

这里的 CKEDITOR.env.ie ? editor.commands.paste : this 是一个关键判断:

  • 在 IE 中,pastetext 命令本身被浏览器安全策略拦截后只能回退到原生粘贴,因此展示的是 paste 命令的快捷键 Ctrl+V(这正是测试文档中"Edge 和 IE 显示 Ctrl+V"的由来);
  • 在其他浏览器,展示的是 pastetext 命令自身的快捷键。

而 pastetext 命令的快捷键在插件 init 中注册(plugins/pastetext/plugin.js):

var commandName = 'pastetext',
    pasteKeystroke = !CKEDITOR.env.safari ? CKEDITOR.CTRL + CKEDITOR.SHIFT + 86 : // Ctrl + Shift + V
        CKEDITOR.CTRL + CKEDITOR.ALT + CKEDITOR.SHIFT + 86; // Ctrl + Shift + Alt + V

editor.addCommand( commandName, pasteTextCmd );
editor.setKeystroke( pasteKeystroke, commandName );

由此得到测试文档中那张"因浏览器而异"的快捷键对照表:

浏览器 通知中展示的快捷键 源码依据
Safari Cmd+Alt+Shift+V CKEDITOR.CTRL + CKEDITOR.ALT + CKEDITOR.SHIFT + 86
Edge / IE Ctrl+V CKEDITOR.env.ie 时改用 editor.commands.paste 的 keystroke
Firefox / Chrome / Opera 等 Cmd/Ctrl+Shift+V CKEDITOR.CTRL + CKEDITOR.SHIFT + 86

补充说明:Ctrl+Shift+V 这类"纯文本粘贴"快捷键并非浏览器原生能力,而是 CKEditor 自己通过 setKeystroke 注册的编辑器级快捷键;Safari 之所以用 Cmd+Alt+Shift+V,是为了避开 Safari 自身对 Cmd+Shift+V 的既有占用。该命令的按钮同样经 addPasteButton 注册(clipboard,40 分组)。

3. IE 安全对话框:允许后不再通知

测试文档末尾的 IE 特例,对应 paste 命令 exec 中的 getClipboardData 流程(plugins/clipboard/plugin.js):

if ( getClipboardDataDirectly() === false ) {
    // Direct access to the clipboard wasn't successful so remove listener.
    ...
} // else: 直接访问成功,onPaste 回调会拿到数据并调用 callback( evt.data )
  • IE 是唯一允许脚本通过安全对话框获得剪贴板直接访问权的浏览器;
  • 用户允许后,getClipboardDataDirectly() 成功,onPaste 回调把真实剪贴板数据交给 callback( data ),于是走 firePasteEvents 分支,通知自然不再出现;
  • 用户拒绝(或非 IE 浏览器)时,getClipboardDataDirectly() 返回 false,才会落入 else if ( notification && !editor._.forcePasteDialog ) 的通知分支。

五、通知在整条粘贴链路中的位置

从 plugins/clipboard/plugin.js 文件头部的执行流程注释可以看到,通知只是"粘贴被阻断"场景下的兜底反馈,完整的粘贴链路大致如下:

-- Paste command
    * fire 'paste' on editable ('beforepaste' for IE)
    * !canceled && execCommand 'paste'   <-- 浏览器可能在此拦截
    * 若拿不到数据 -> 弹出 Paste Notification
-- Paste from native context menu & menubar
    * listen 'onpaste'
    * cancel native event
    * fire 'beforePaste' on editor
    * getClipboardDataByPastebin / execIECommand( 'paste' )

而 paste 事件本身还会经过多级预处理(过滤、类型嗅探、文本标记统一等),最终由优先级 1000 的监听器调用 editor.insertHtml 插入内容。这些环节不受通知影响——通知只在"数据获取失败"这一条支路上出现。

六、如何在自己的集成中配置与关闭粘贴通知

1. 自定义文案

notification 选项支持直接传字符串。例如在调用命令时覆盖:

editor.execCommand( 'paste', {
    notification: '当前浏览器不允许自动粘贴,请使用键盘 Ctrl+V 完成粘贴。'
} );

2. 完全关闭通知

editor.execCommand( 'paste', {
    notification: false
} );

3. 调整展示时长

CKEDITOR.replace( 'editor1', {
    clipboard_notificationDuration: 8000
} );

4. 兜底配置:forcePasteAsPlainText

若希望"所有粘贴一律按纯文本处理",可设置(plugins/pastetext/plugin.js):

config.forcePasteAsPlainText = true;          // 全部按纯文本粘贴
config.forcePasteAsPlainText = 'allow-word';  // 仅 Word 内容保留格式,其余按纯文本

该配置会由 clipboard 插件在初始化时读取(filterType = 'plain-text'),并在 beforePaste 阶段把 data.type 改为 'text'。值得注意的是,测试文档 pastecommands.md 还验证了"先点 Paste as plain text 再点 Paste,之后用 Ctrl+V 应粘贴 HTML 而非纯文本"——即 editor._.nextPasteType 只在"下一次粘贴"生效,命令之间互不污染。

七、小结

Paste Notification 是 CKEditor 4 在浏览器安全限制下保持良好粘贴体验的关键设计:

  • 统一入口:Paste / Paste from Word / Paste as plain text 三个按钮最终都收敛到 paste 命令,由它统一负责通知的文案拼装与展示;
  • 差异快捷键:普通粘贴与 Word 粘贴展示 Cmd/Ctrl+V,纯文本粘贴则由 pastetext 插件按浏览器分别注册 Cmd/Ctrl+Shift+V(Safari 为 Cmd+Alt+Shift+V,IE/Edge 回退为 Ctrl+V);
  • 可配置性:文案(notification 字符串)、开关(notification: false)、时长(clipboard_notificationDuration,默认 10000ms)均可按需定制;
  • IE 特例:用户允许安全对话框后直接取到剪贴板数据,通知不出现。

如需在实际编辑器上体验完整行为,可直接在仓库的 Bender 测试环境运行 tests/plugins/clipboard/manual/pastenotification.html(配合 wysiwygarea, toolbar, clipboard, pastefromword, pastetext 插件组合),并在 Chrome、Firefox、Safari、Edge/IE 上分别核对第三节中的快捷键对照表。

登录后查看全文
ckeditor4