企业官网建设流程全解析

如何扩展InlineAttachment到任意输入组件：从零编写自定义编辑器适配器进阶教程

【免费下载链接】InlineAttachmentEasily paste and upload files/images in plain textareas项目地址: https://gitcode.com/gh_mirrors/in/InlineAttachment

InlineAttachment 是一个轻量级的图片粘贴上传插件，能让任意纯文本输入框（textarea）或代码编辑器支持"拖拽/粘贴图片即上传"的能力，效果与 GitHub 编辑框里贴图一样丝滑。它自带 input、jQuery、AngularJS、CodeMirror 四套现成编辑器适配器。本文面向新手，带你从零手写一个自定义编辑器适配器，把 InlineAttachment 接入任意输入组件，只需实现 3 个简单方法，10 分钟即可完成 🎯。

一、先搞懂原理：为什么扩展如此简单？

InlineAttachment 的核心设计是"编辑器无关"：它不关心你的输入框是什么框架，只要求传入一个实现了 3 个方法的编辑器适配器对象。整个上传流程（拦截粘贴/拖拽 → 显示占位文本 → XHR 上传 → 回填 URL）全部由核心模块完成，见 src/inline-attachment.js。

你只需要做两件事：

1. 写一个编辑器包装对象，暴露 3 个方法；
2. 写一个attach函数，把粘贴/拖拽事件转发给核心引擎。

所有已内置的适配器都是照着这个套路写的，可以直接抄作业：

二、第 1 步：实现 3 个方法的编辑器适配器

核心引擎与编辑器之间只有 3 个约定接口（可参考 src/input.inline-attachment.js）：

• getValue()：返回编辑器当前全部文本；
• insertValue(val)：把文本（占位符）插入到光标处；
• setValue(val)：整段替换编辑器内容（用于把占位符替换成上传后的真实 URL）。

以自定义富文本框为例，只需几行：

var myEditor = { getValue: function() { return myBox.value; }, insertValue: function(val) { inlineAttachment.util.insertTextAtCursor(myBox, val); }, setValue: function(val) { myBox.value = val; } };

💡 小技巧：inlineAttachment.util.insertTextAtCursor是官方提供的工具函数，自动兼容各浏览器光标插入，见 src/inline-attachment.js，建议直接复用。

三、第 2 步：写 attach 函数，绑定粘贴与拖拽事件

创建核心实例并监听 4 个事件，完整模板见 src/input.inline-attachment.js：

function attachToMyBox(input, options) { var inlineattach = new inlineAttachment(options, myEditor); input.addEventListener('paste', function(e) { inlineattach.onPaste(e); }, false); input.addEventListener('drop', function(e) { e.stopPropagation(); e.preventDefault(); inlineattach.onDrop(e); }, false); // 下面两个必须阻止默认行为，否则浏览器会直接打开文件 input.addEventListener('dragenter', function(e) { e.preventDefault(); }, false); input.addEventListener('dragover', function(e) { e.preventDefault(); }, false); }

三个要点：

• new inlineAttachment(options, editor)第二个参数就是你刚写的适配器；
• onPaste/onDrop会返回布尔值，表示事件是否被处理，未处理时会走浏览器默认行为；
• 拖拽类事件一定要preventDefault()，这是最常见的翻车点 ⚠️。

四、第 3 步：注册适配器，像内置插件一样调用

把 attach 函数挂到全局编辑器注册表inlineAttachment.editors上（注册表定义于 src/inline-attachment.js）：

inlineAttachment.editors.mybox = { attach: attachToMyBox }; // 使用方式 inlineAttachment.editors.mybox.attach(document.getElementById('mybox'), { uploadUrl: '/api/upload' });

五、常用配置项与事件速查

第二个参数options支持丰富的配置，完整清单见 docs/pages/configuration.rst：

• uploadUrl：上传接口地址（默认upload_attachment.php）；
• allowedTypes：允许的 MIME 类型，默认只放行 jpeg/png/gif；
• progressText/urlText/errorText：上传中占位符、成功后的 Markdown 图片语法、失败提示；
• 事件钩子：onFileReceived、onFileUploaded、onFileUploadError等，方便做自定义提示与埋点。

服务端返回 JSON 中的filename字段即为图片地址，参考实现可直接看 demo/upload_attachment.php。

六、如何验证适配器写对了？

项目自带拖拽上传测试页与用例：tests/page/drag-drop.html 和 tests/drag-drop.js。验证顺序建议：

1. 打开测试页，确认拖入图片后出现![Uploading file...]占位符；
2. 上传完成后占位符被替换为file；
3. 粘贴图片（Chrome 支持）走同样的流程；
4. 上传失败时占位符变为Error uploading file，说明错误分支也生效了。

七、相关文件导航

📌总结：扩展 InlineAttachment 到任意输入组件，本质上就是"实现 3 个方法 + 绑定 4 个事件"。照着src/input.inline-attachment.js的样板改造，再结合allowedTypes、urlText等配置项微调，就能让任何自研编辑器拥有 GitHub 级的贴图上传体验。

【免费下载链接】InlineAttachmentEasily paste and upload files/images in plain textareas项目地址: https://gitcode.com/gh_mirrors/in/InlineAttachment