CKEditor 5 Clipboard 剪贴板功能包深度解析复制剪切、粘贴管线与拖放机制【免费下载链接】ckeditor5Powerful rich text editor framework with a modular architecture, modern integrations, and features like collaborative editing.项目地址: https://gitcode.com/GitHub_Trending/ck/ckeditor5CKEditor 5 的剪贴板Clipboard功能包位于 packages/ckeditor5-clipboard它实现了编辑器与操作系统/浏览器原生剪贴板之间的完整对接涵盖复制copy、剪切cut、粘贴paste以及拖放drag and drop四类操作。本文以该功能包的官方 API 文档为骨架结合仓库内 deep-dive 指南、拖放特性文档、纯文本粘贴特性文档 与核心源码系统讲解其架构、输入/输出管线、默认行为与扩展方式。读完本文你将能够理解剪贴板事件在 CKEditor 5 内部的流转路径掌握安装启用方法并能够基于管线事件编写自己的粘贴/复制处理逻辑。功能包概览一个胶水插件与四个子插件Clipboard插件是整个功能包的门面它在源码中是一个glue胶水插件本身不实现具体的剪贴板逻辑而是通过static requires声明加载四个子插件见 src/clipboard.ts子插件源码文件职责ClipboardPipelinesrc/clipboardpipeline.ts输入/输出管线核心拦截paste、drop、copy、cut事件并驱动内容处理DragDropsrc/dragdrop.ts编辑器内部及内外部之间的拖放支持PastePlainTextsrc/pasteplaintext.ts检测Ctrl/Cmd Shift V以纯文本方式粘贴ClipboardMarkersUtilssrc/clipboardmarkersutils.ts在复制/剪切/粘贴过程中对模型标记markers进行收集与恢复的工具此外Clipboard插件在init()中还会把三个快捷键写入编辑器的无障碍accessibility键盘快捷键数据库便于屏幕阅读器用户发现与学习见 src/clipboard.tsCTRLC—— 复制所选内容Copy selected contentCTRLV—— 粘贴内容Paste contentCTRLSHIFTV—— 以纯文本粘贴内容Paste content as plain text与 Essentials 插件的关系Clipboard插件通常不会出现在用户手动编写的plugins配置中因为它一般由ckeditor/ckeditor5-essentials包中的Essentials插件自动启用。Essentials是一组必备功能的集合除剪贴板外还启用其他基础编辑能力。也就是说只要你的编辑器通过Essentials引导Clipboard及其全部子插件便已就绪无需重复声明。安装与启用该功能包是开源聚合包ckeditor5的组成部分官方推荐直接安装聚合包参考 docs/api/clipboard.md 与 README.mdnpm install ckeditor5安装完成后若你的编辑器未使用Essentials也可以显式将Clipboard加入插件列表。官方特性文档给出的配置示例如下以拖放和纯文本粘贴为例import { ClassicEditor, Clipboard, Bold } from ckeditor5; ClassicEditor .create( { licenseKey: YOUR_LICENSE_KEY, // 或使用 GPL。 plugins: [ Clipboard, Bold, /* ... */ ] } ) .then( /* ... */ ) .catch( /* ... */ );Clipboard启用后DragDrop与PastePlainText子插件会随之激活无需单独配置。该功能包在仓库中的版本为 48.5.0见 package.json依赖ckeditor/ckeditor5-core、ckeditor/ckeditor5-engine、ckeditor/ckeditor5-ui、ckeditor/ckeditor5-utils与ckeditor/ckeditor5-widget等核心包。核心机制拦截原生事件接管剪贴板CKEditor 5 剪贴板设计的核心原则是拦截所有原生的copy、cut、paste、drop事件并在编辑器侧自行处理绝不允许浏览器直接触碰富文本内容——否则浏览器对 HTML 的自作主张整理会导致内容结构被破坏。剪贴板内容处理有明确的两个方向输入管线input pipeline内容被粘贴paste或拖入drop编辑器时走输入管线输出管线output pipeline内容被复制copy、剪切cut或拖出drag编辑器时走输出管线。两条管线都允许各功能插件在事件链的不同阶段处理将要插入或写入剪贴板的内容也允许开发者以不同优先级监听事件来覆盖默认机制。输入管线paste 与 drop 的统一处理当用户向编辑器粘贴或拖入内容时浏览器触发原生事件剪贴板功能拦截后启动以下机制详见 deep-dive 文档 与 clipboardpipeline.ts 源码注释ClipboardObserversrc/clipboardobserver.ts把原生事件转换为合成的view.Document#paste或view.Document#drop事件由于粘贴和拖入的插入效果相似、处理逻辑应保持一致两个事件被统一转化为一个view.Document#clipboardInput事件剪贴板功能监听view.Document#clipboardInput从事件数据的dataTransfer中取出text/html或text/plain内容并进行预处理例如清理空白字符等随后将内容转换为view.DocumentFragment并触发ClipboardPipeline#inputTransformation事件再监听ClipboardPipeline#inputTransformation把视图层的view.DocumentFragment转换为模型层的model.DocumentFragment触发ClipboardPipeline#contentInsertion事件最后监听ClipboardPipeline#contentInsertion调用model.insertContent()把模型片段插入到编辑器当前选区位置并把本次所有变更所在的范围存放到事件数据的resultRange属性中。上述事件流转可以用下面的示意图概括原文档与源码注释中的 ASCII 图┌──────────────────────┐ ┌──────────────────────┐ │ view.Document │ │ view.Document │ │ paste │ │ drop │ └───────────┬──────────┘ └───────────┬──────────┘ │ │ └────────────────┌────────────────┘ │ ┌─────────V────────┐ │ view.Document │ 从 data.dataTransfer 中取出 text/html │ clipboardInput │ 处理为 view.DocumentFragment └─────────┬────────┘ │ ┌───────────V───────────┐ │ ClipboardPipeline │ 将 view.DocumentFragment 转换为 │ inputTransformation │ model.DocumentFragment └───────────┬───────────┘ │ ┌──────────V──────────┐ │ ClipboardPipeline │ 调用 model.insertContent() │ contentInsertion │ 插入编辑器 └─────────────────────┘值得注意的细节ClipboardPipeline#contentInsertion事件在**模型变更块model change block**内触发以保证其他监听器在同一变更块中运行期间不会插入中间的后置修正器post-fixer例如选区修正器执行见 clipboardpipeline.ts。输出管线copy 与 cut 的内容序列化输出管线是输入管线的镜像服务于复制与剪切操作详见 deep-dive 文档在view.Document#copy与view.Document#cut事件上默认动作是调用model.getSelectedContent()获取选中内容preventDefault()阻止原生复制/剪切默认行为然后携带一个model.DocumentFragment触发ClipboardPipeline#outputTransformation事件在ClipboardPipeline#outputTransformation事件上处理data.content模型片段将其转换为视图片段view.DocumentFragment并触发view.Document#clipboardOutput事件在view.Document#clipboardOutput事件上把内容以 HTML 形式写入剪贴板若是剪切操作同时从编辑器中删除选中内容。此动作由低优先级监听器执行因此可以被普通监听器覆盖。┌──────────────────────┐ ┌──────────────────────┐ 获取选中的 model.DocumentFragment │ view.Document │ │ view.Document │ 并触发 outputTransformation 事件 │ copy │ │ cut │ └───────────┬──────────┘ └───────────┬──────────┘ │ │ └────────────────┌────────────────┘ │ ┌─────────────V────────────┐ 处理 model.DocumentFragment │ ClipboardPipeline │ 并转换为 view.DocumentFragment │ outputTransformation │ └──────────────────────────┘ │ ┌─────────────V────────────┐ 处理 view.DocumentFragment │ view.Document │ 为 text/html 与 text/plain │ clipboardOutput │ 并存入 data.dataTransfer └──────────────────────────┘粘贴纯文本PastePlainText 插件PastePlainText是官方文档中反复强调的参考实现它以ClipboardPipeline为依赖监听其contentInsertion事件见 src/pasteplaintext.ts。其行为特性如下来自 paste-plain-text.md检测到Ctrl/Cmd Shift V组合键时触发使粘贴进来的文本继承目标位置的格式而不是保留源内容的格式因此也可称作无格式粘贴pasting without formatting粘贴的纯文本若包含双换行会被转换为段落分隔新段落单换行则转换为软换行soft break即行内br从源码看其实现会保留目标选区的格式化属性通过model.schema.getAttributeProperties( key ).isFormatting判断并将其应用到粘贴进来的内联内容上若粘贴前存在选中文本会先执行model.deleteContent()删除同时保留那些未完全选中因而存活的属性如链接linkHref它不属于格式化属性但若粘贴位置处于链接中间也应保留——这就是匹配目标格式的底层原理。官方还提示若需查看完整可运行示例可以直接阅读PastePlainText的源码实现并以 创建简单插件教程 为入门参考。拖放DragDrop 插件DragDrop插件为编辑器提供完整的拖放能力详见 drag-drop.md主要分为三类场景内容块拖放默认支持在编辑器内部拖放段落、表格、列表等内容块。你可以选中一个或多个块把它们移动到其他块之前或之后甚至把块放入表格、引用块等其他块内部。官方演示docs/_snippets/features/drag-drop.js等还展示了从编辑器外部把一个联系人列表拖入编辑器、以自定义 widgeth-card 微格式形式插入的用法文件上传拖放当集成中启用了 CKBox 文件管理器等上传能力时可以直接把文件/图片从系统拖入编辑器完成上传气球块编辑器balloon block editor中的拖动手柄编辑器左侧的盲文点面板图标drag indicator 图标同时充当拖动手柄聚焦或选中内容块后即可拖拽移动。从源码结构看拖放功能由DragDrop及其依赖的DragDropTargetsrc/dragdroptarget.ts负责高亮拖放目标位置和DragDropBlockToolbarsrc/dragdropblocktoolbar.ts实现块级工具栏的拖动手柄协同实现事件链从mousedown设置 draggable 属性开始经dragstart获取选中模型片段并转为视图片段进入拖放流程。拖放样式定制拖放时用于指示插入位置的目标线颜色由 CSS 变量--ck-clipboard-drop-target-color管理相关样式定义于 theme/clipboard.css。官方给出如下自定义示例:root { --ck-clipboard-drop-target-color: green; }基于管线事件的定制与扩展deep-dive 指南给出了三种典型的定制场景与代码示例这些 API 是集成方扩展剪贴板行为的入口。1. 覆盖view.Document#clipboardInput改变读取的数据类型默认情况下剪贴板功能读取text/html或text/plain并规范化为view.DocumentFragment。若你想在存在application/rtf时忽略 HTML 转而读取 RTF可以监听clipboardInput并改写data.contenteditor.editing.view.document.on( clipboardInput, ( evt, data ) { const dataTransfer data.dataTransfer; const rtfContent dataTransfer.getData( application/rtf ); // 若剪贴板中没有 RTF中止处理让默认机制接管输入。 if ( !rtfContent ) { return; } // 将 RTF 原始字符串转换为视图文档片段。 const viewContent convertRtfStringToView( rtfContent ); // 把视图片段交给默认的剪贴板输入处理器继续后续处理。 data.content viewContent; } );同理你也可以从dataTransfer中读取拖入/粘贴的文件如dataTransfer.files来接管文件上传——不过完整的文件上传远比读取文件列表复杂可以参考图片包中ImageUploadEditing位于 packages/ckeditor5-image/src/imageupload/imageuploadediting.ts的实现。2. 处理ClipboardPipeline#inputTransformation改写将要插入的内容该事件允许各功能插件处理即将插入编辑器的内容。例如把粘贴的单段 URL 文本自动转换为链接const writer new ViewUpcastWriter( editor.editing.view.document ); editor.plugins.get( ClipboardPipeline ).on( inputTransformation, ( evt, data ) { if ( data.content.childCount 1 isUrlText( data.content.getChild( 0 ) ) ) { const linkUrl data.content.getChild( 0 ).data; data.content writer.createDocumentFragment( [ writer.createElement( a, { href: linkUrl }, [ writer.createText( linkUrl ) ] ) ] ); } } );3. 处理ClipboardPipeline#contentInsertion内容插入后执行动作默认插入动作由低优先级监听器完成普通监听器即可覆盖它。若想在内容插入之后再执行某些动作使用lowest优先级editor.plugins.get( ClipboardPipeline ).on( contentInsertion, ( evt, data ) { console.log( Content was inserted. ); }, { priority: lowest } );优先级机制与 DOM 的evt.preventDefault()类似剪贴板功能自身使用低优先级监听clipboardInput、inputTransformation、contentInsertion等事件因此你只需注册普通监听器并调用evt.stop()即可完全覆盖默认行为。源码结构与测试验证仓库中该功能包的结构清晰便于进一步研读源码packages/ckeditor5-clipboard/src除前文提及的插件外还有三个工具模块——utils/normalizeclipboarddata.ts规范化剪贴板原始数据、utils/plaintexttohtml.ts纯文本转 HTML、utils/viewtoplaintext.ts视图转纯文本以及augmentation.ts模块类型增强与index.ts包入口测试packages/ckeditor5-clipboard/tests为每个核心模块配备了对应用例如clipboardpipeline.js、clipboardobserver.js、dragdrop.js、pasteplaintext.js、clipboardmarkersutils.js以及集成测试pasting-integration.js可用于验证管线事件流与各插件行为手工测试packages/ckeditor5-clipboard/manual提供copycut、pasting、dragdrop、dragdrop-blocks、dragdrop-balloon-block等手工验证页面适合在浏览器中直观检查复制/剪切/粘贴与拖放的真实表现。小结CKEditor 5 的 Clipboard 功能包以拦截原生剪贴板事件 双管线事件驱动为设计核心输入方向经过view.Document#paste/drop→view.Document#clipboardInput→ClipboardPipeline#inputTransformation→ClipboardPipeline#contentInsertion完成内容插入输出方向经view.Document#copy/cut→ClipboardPipeline#outputTransformation→view.Document#clipboardOutput完成内容序列化。PastePlainText与DragDrop则分别覆盖无格式粘贴与块级拖放/外部拖入两大高频场景。掌握这条事件链是集成方定制粘贴行为、实现自动链接、接入文件上传等高级能力的前提。若需更完整的实战范例可直接研读本仓库 deep-dive 指南、拖放特性文档、纯文本粘贴特性文档 及其对应源码与测试。【免费下载链接】ckeditor5Powerful rich text editor framework with a modular architecture, modern integrations, and features like collaborative editing.项目地址: https://gitcode.com/GitHub_Trending/ck/ckeditor5创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考