eWebEditor 0.1.4部署实战：iframe与textarea同步机制及避坑指南

简介eWebEditor 在线文本编辑器 v0.1.4 for JSP 是一款面向 Java Web 开发者的富文本编辑组件由吕海鹏修改优化适用于 JSP 网站后台中的文章发布、商品描述、论坛回帖等场景解决普通 textarea 无法直观排版和插入多媒体的问题。压缩包共 264 个文件以 gif 图标186 个和 css 样式27 个为主前者用于编辑器按钮与界面元素后者负责整体外观和布局另含 htm 示例页面、jsp 集成演示、class 与 jar 后端类库、js 脚本及 xml 配置整体仅 796KB轻量易部署。目前该资源已有 170 人浏览学习。包内提供完整接入范例和目录结构开发者可对照 jsp 示例快速部署通过 API 调用实现文字格式化、图片上传、远程图片抓取、超链接插入和 HTML 源码编辑吕海鹏修改版针对上传处理类与请求封装做了调整提升了稳定性和中文兼容性方便直接集成到内容管理类 JSP 项目也适合作为二次开发基础。1. 老项目里没人维护的 eWebEditor反而值得你会部署先说个反直觉的结论eWebEditor 0.1.4 是十多年前的在线文本编辑器已经没人给它发新版本但现在依然有大量老 JSP 系统跑着它。接手这类系统第一反应是“换掉”可业务数据都在旧正文里迁移成本往往比想象高。这一版 eWebEditor For JSP 打包结构简单、依赖少你只要理解它“iframe 编辑区 隐藏 textarea 同步”这一套机制部署、调参、排错都能稳稳拿下。适合以下人群维护老后台的工程师、要把旧系统做功能增补再交付的项目组以及想低成本给内部工具补一个富文本编辑能力的新手。它不新但不代表不能用。2. 先看穿它的底细iframe 编辑区与 textarea 同步机制老一代在线编辑器有一个共同的设计编辑区不是表单里的输入框而是一个内嵌的 iframe 页面。eWebEditor 0.1.4 也是这么做的。你在页面上看到的一整块工具栏和可编辑白底区域实际是从另一个 JSP 页面加载进来的独立文档。表单里真正参与提交的是一个隐藏的 textarea。我在排查老系统问题时遇到最多的情况就是开发者只看到了 iframe忘了 textarea结果后台永远收不到正文。这一章先把这套机制讲透后面所有配置和踩坑才有落脚点。2.1 它不是一个输入框一个带工具栏的 iframe 页面eWebEditor 的页面结构可以拆成三块理解外层承载页、iframe 编辑器页、隐藏 textarea。外层承载页就是你自己的表单 JSPiframe 通过 src 指向 ewebeditor 目录下的编辑器页面并带上 id、style 等参数。textarea 放在表单里但默认隐藏它的作用有两个一是作为后台接收正文的字段容器二是在页面加载时把数据库里的旧内容灌进编辑区。编辑区内部的 HTML 操作依赖浏览器原生的 document.execCommand 方法。加粗、斜体、插入链接、设置字体大小本质都是对 iframe 内文档执行 execCommand 命令。这个机制老但兼容性思路是清楚的图片上传、文件上传这类需要服务端参与的操作编辑器页会单独发请求到上传处理接口拿到 URL 后再往编辑区里插入 img 或 a 标签。这一代的取值和赋值也很直接赋值用 setHTML取值用 getHTML。问题在于这些方法定义在 iframe 的 window 对象上你在外层页面不能直接 document.getElementById(content1).value必须跨 iframe 调用。理解了这个结构你就知道为什么网上那些“提交后内容为空”的帖子答案基本都是没同步 textarea而不是编辑器坏了。2.2 部署进 webapp解压、改名、避开 WEB-INF拿到 ewebeditor014jsp.rar 这种包第一件事不是打开源码看而是把它当作一个独立的 web 应用部署到 Tomcat 的 webapp 目录下。常见做法是先解压到临时目录确认解压出来的顶层目录名再改成一个简短、不带版本号的名字例如 ewebeditor。目录名太长后续所有引用路径都会跟着长报错时排查也麻烦。# 解压到临时目录再整体挪进 webapp mkdir -p /opt/tomcat/webapps/ewebeditor unrar x ewebeditor014jsp.rar /opt/tomcat/webapps/ewebeditor/ # 如果你只有 7z也可以这样解 # 7z x ewebeditor014jsp.rar -o/tmp/ewebeditor_tmp # mv /tmp/ewebeditor_tmp /opt/tomcat/webapps/ewebeditor解压后常见的包内结构大概是一个编辑器主 JSP 页面、包含样式和工具配置的目录、处理上传的 JSP 或 Servlet、若干 JS 和 CSS。我没法替你确认 rar 包里的具体文件名但判断方法很简单在 webapp 下访问http://localhost:8080/ewebeditor/能看到目录列表或测试页说明解压和部署基本成功。有两个位置要注意。第一整个 ewebeditor 目录必须放在 webapp 根下或平行于 WEB-INF不能塞进 WEB-INF 里面否则 Tomcat 默认不会把 WEB-INF 下的资源当作可直接访问的静态页面。第二目录名不要带点和空格也不要和工程项目同名老版本编辑器对相对路径的解析很敏感目录一复杂iframe src 很容易拼错。2.3 最小初始化一段 JSP 代码把编辑器拉起来部署完成后用一段最小的 JSP 页面验证编辑器能不能出界面。这个验证页只做三件事放一个 iframe、放一个隐藏 textarea、写一段 beforeSubmit 做提交前同步。% page contentTypetext/html;charsetUTF-8 languagejava % html head titleeWebEditor 最小部署验证/title /head body form namefrmArticle action/article/save methodpost onsubmitreturn beforeSubmit(); !-- 编辑器承载区真正的内容在这个 iframe 页面里 -- iframe ideditorFrame src%request.getContextPath()%/ewebeditor/ewebeditor.jsp?idcontent1stylecoolblue width100% height360 frameborderno scrollingno/iframe !-- 实际提交给后台的字段必须存在 -- textarea idcontent1 namecontent1 styledisplay:none;/textarea input typesubmit value保存 / /form script function beforeSubmit() { var frame document.getElementById(editorFrame); var win frame.contentWindow; // 老版本里 getHTML 可能挂在 window 上也可能挂在 window.editor 上 var html ; if (win.editor typeof win.editor.getHTML function) { html win.editor.getHTML(); } else if (typeof win.getHTML function) { html win.getHTML(); } document.getElementById(content1).value html; return true; } /script /body /html这段代码里iframe 的 src 指向编辑器主页面idcontent1 表示编辑器要把内容写入 id 为 content1 的 textareastylecoolblue 是自带的显示风格。beforeSubmit 在表单提交前触发先跨 iframe 取出 HTML 内容赋给隐藏 textarea这样后台从 request 里拿 content1 就是完整正文。参数说明iframe 的 id 只是一个 DOM 标识和编辑器 id 没有强制绑定关系真正绑定的是 iframe src 里的 id 参数与 textarea 的 id。style 参数对应编辑器内部的一套皮肤和工具栏配置不写的话会取默认值。width 和 height 建议直接用 CSS 控制老版本内部对高度的自适应不算好最稳妥是给 iframe 一个固定高度。验证这一步是否跑通打开浏览器开发者工具切到 Network 面板提交表单时看 save 请求的 Form Data 里 content1 是否有值。有值机制就通了没值回到 beforeSubmit 里看跨 iframe 的取值分支是否走对。初次接触这一代编辑器强烈建议把“iframe 内容 → textarea → 后台 request”这条链路当作第一优先级验证对象因为它决定了后面所有功能是否可信。3. 把参数配明白初始化、上传与提交写回上一章解决了“编辑器能不能出来”的问题这一章解决“编辑器按你的需求工作”的问题。老版本编辑器的配置不像现代项目有统一配置文件参数散落在几个地方初始化 URL 参数、编辑器内部配置对象、上传处理页面的常量。新人容易在这三处之间来回跳最后发现改了 A 没生效原因是 B 那边有同名参数覆盖。我的习惯是先按“初始化参数 → 上传参数 → 提交写回”这个顺序统一过一遍每改一处都在浏览器里验证一次。3.1 初始化参数怎么传id、style、basepath 三件套eWebEditor 0.1.4 的初始化参数主要通过 iframe src 的 query string 传递。最常见的三个参数是 id、style、basepath。id 决定编辑器往哪个 textarea 写内容作用等同于一个绑定标识。style 指定编辑器界面风格和工具栏布局。basepath 则告诉编辑器页面的相对路径基准是什么这参数特别容易被人忽略一旦部署目录嵌套过深编辑器内部加载 JS、CSS、图标全部会错位。参数作用典型值备注id绑定目标 textarea 的 idcontent1必须与页面里 textarea 的 id 完全一致style编辑器风格与工具栏方案coolblue / standard对应包内 style 配置目录值不存在时会回退默认basepath编辑器资源的路径基准/ewebeditor不传时按相对路径解析目录深了必出问题width编辑区宽度550px 或 100%老版本对百分比支持一般建议直接设像素height编辑区高度360px不设可能塌成一行basepath 的生产环境写法我一般直接写成绝对路径basepath%request.getContextPath()%/ewebeditor。这样无论是开发环境部署在根目录还是生产环境挂在某个子应用下编辑器内部资源都能稳定加载。另一个容易被坑的点是 style 的值要对应包内真实存在的风格目录否则编辑器页面会报一堆 JS 错误界面出不来。判断是否生效直接看 Network 面板里编辑器页面额外加载的 CSS 和 JS 是否 200。3.2 上传参数BaseDir、扩展名白名单与大小上限图片上传和附件上传是这套编辑器里最常被二次调整的部分。上传的请求和保存正文不是同一个链路它由编辑器 iframe 内部发起保存接口一般是一个独立的 JSP 或 Servlet通过 form 提交或 AJAX 发送文件然后返回一个可访问的 URL编辑器再用这段 URL 往正文里插图片标签。配置上传时重点盯三处上传根目录、允许的扩展名、文件大小上限。老版本里这些值常见写在上传处理 JSP 顶部的常量或 request 参数里。以图片上传为例常见配置结构是这样的% // 上传根目录相对于 webapp 部署根不要以 / 开头 String baseDir /upload/; // 允许的扩展名白名单注意小写 String[] allowExt {jpg, gif, png, bmp, jpeg}; // 单个文件大小上限单位字节这里是 2MB long maxSize 2 * 1024 * 1024; // 按日期分子目录方便后续管理和清理 String subDir new java.text.SimpleDateFormat(yyyyMMdd).format(new java.util.Date()); String uploadPath application.getRealPath(baseDir subDir); File dir new File(uploadPath); if (!dir.exists()) { dir.mkdirs(); } %这段代码的逻辑是在 webapp 根下建立 upload 目录再按日期分子目录把上传文件落到upload/20250101/xxx.jpg这种结构里。allowExt 做白名单校验maxSize 做大小限制。这里有三个容易忽略的细节。第一baseDir 不要以斜杠开头application.getRealPath 拼接的是相对于 webapp 根的路径写死了容易在改部署位置时找不到目录。第二扩展名校验一定要转小写用户传 .JPG 和 .jpg 在 Windows 上没问题Linux 上就会翻车。第三目录创建时机应当在接收文件前完成而不是等写入时报错再补建。上传后返回给编辑器的内容是一段可访问的图片 URL我看到的项目里有人直接返回相对路径如/upload/20250101/xxx.jpg有人返回完整 URL。这里建议统一用相对路径配合前端的域名部署迁移环境时不用改库里的正文数据。3.3 提交前写回 textarea标准写法与验证方法上一章给了最简单的 beforeSubmit 写法。实际项目里正文往往还需要做进一步加工比如清洗危险标签、压缩连续空行、给图片补样式。我的建议是不要把这些逻辑全塞进 beforeSubmit而是写一个独立的处理函数只做一件事把 iframe 里的 HTML 取出来加工后写回 textarea。function syncEditorToForm() { var frame document.getElementById(editorFrame); var win frame.contentWindow; var html getEditorHTML(win); // 常见清洗场景去掉编辑器自动加的冗余 class html html.replace(/\sclass[^]*/gi, ); // 相对图片路径补全为绝对路径避免正文单独展示时丢图 html html.replace(/src\/(upload\/)/g, src window.location.origin /$1); document.getElementById(content1).value html; } function getEditorHTML(win) { if (win.editor typeof win.editor.getHTML function) { return win.editor.getHTML(); } if (typeof win.getHTML function) { return win.getHTML(); } return ; }这个写法比直接取值的版本多做了两件事去掉无用 class避免后台管理系统里每个正文 div 都挂着编辑器生成的样式类给图片路径补全协议和域名让正文在站外展示或单独输出时不会图片全部 cracked。验证方法很直接在 Chrome 里编辑一段带图片的文字点击保存看 Network 面板里提交的 Form Data 中 content1 的值。如果 content1 里是干净的 HTML 且图片 src 完整说明同步逻辑生效。还有一类坑值得在这里提前说编辑过程中不要在外层页面用 DOM 操作直接改动 textarea 的 value。textarea 只是同步的出口不是内容的本体。你在 textarea 上赋值编辑器 iframe 里的内容并不会跟着变。反过来如果页面加载时想给编辑器预填内容要找编辑器 iframe 的 setHTML 方法而不是把内容写进 textarea。新手最容易在这两处搞反方向。4. 部署与使用避坑5 条高频排查记录这一章写的都是我在老系统排查里反复遇到的真实问题每一条都完整记录“现象 → 原因 → 解决”。如果你遇到的情况不在列表里也可以按同样的思路拆先确认是前端问题还是服务端问题再确认是取值问题还是上传问题最后再动代码。老版本编辑器报错信息普遍不友好现象和根因往往隔着两层直接看报错字符串容易带偏方向。4.1 表单提交后后台拿到空字符串现象编辑器里明明写了字点保存后台收到的正文是空串。这个问题的出现率在新手接手老系统时排第一。原因几乎都是 beforeSubmit 没写或者写了但取值方法不对。iframe 内容不会自动进表单这是设计如此不是 bug。解决在表单的 onsubmit 里调用同步函数把 getHTML 的返回值赋给 textarea。取值分支要兼容 window.editor.getHTML 和 window.getHTML 两种形态我见过同一套代码在不同机器上走不同分支的情况。4.2 图片上传成功但页面 404现象选择图片后编辑器提示上传成功但正文里插入的图片在浏览器里打不开Network 显示 404。原因通常有两个方向一是上传根目录路径配错文件没落到 webapp 可访问的目录里二是返回的 URL 是相对路径但页面部署在子应用下图片 URL 少拼了上下文路径。解决先手动在浏览器访问上传返回的 URL确认文件能不能直接打开。能打开问题在 URL 拼写打不开去检查上传根目录和 application.getRealPath 的拼接结果。我一般会在上传处理 JSP 里临时输出一段“真实保存路径 访问 URL”的日志比对一次就清楚哪一段出了问题。4.3 中文乱码三处编码不一致现象编辑器显示正常保存正文后数据库里中文全部变成问号或乱码。这个问题在这套 JSP 编辑器上尤其常见因为老版本默认按 GBK 系编码走而新项目普遍用 UTF-8。解决要查三处页面本身 charset、上传处理 JSP 的 request 编码、数据库连接串的 characterEncoding。三个地方必须一致我建议统一切到 UTF-8并显式在 filter 或每个 JSP 开头设置 request.setCharacterEncoding(UTF-8)。注意不要只改页面 charset那只能解决显示解决不了传输和入库。4.4 HTTPS 下样式丢失与弹层错位现象系统从 HTTP 迁到 HTTPS 后编辑器工具栏图标加载不出来上传图片的弹层位置偏移。原因是老版本编辑器页面上有不少写死的绝对资源路径协议是 http://在 HTTPS 页面里被浏览器拦截。解决全局搜索编辑器目录下所有包含 http:// 的硬编码改成相对路径或跟随当前协议。搜索关键词可以限定在 .jsp、.js、.css 文件里替换后用开发者工具再扫一遍 Mixed Content 报错。这类问题不算复杂但文件多的时候容易漏我的做法是先切到 Network 面板过滤 mixed-content 标签逐个击破。4.5 二次加载时编辑器内容被清空现象第一次打开编辑页有内容保存后不跳转再次点击编辑按钮打开同一篇文档编辑器内容空了。常见原因是页面加载时给编辑器赋值的时机不对。iframe 是异步加载的外层页面直接在 window.onload 里调 setHTML很可能 iframe 内部还没初始化完成方法调用了但没生效。解决不要在 onload 里直接 setHTML改为轮询 iframe 内是否暴露了 editor 对象暴露后再赋值。轮询间隔不用太短200ms 一次即可最多等 3 秒超时就提示加载失败。function fillEditor(htmlContent) { var frame document.getElementById(editorFrame); var timer setInterval(function () { var win frame.contentWindow; if (win.editor typeof win.editor.setHTML function) { win.editor.setHTML(htmlContent); clearInterval(timer); } }, 200); }这段轮询代码适合在老系统里做“编辑回显”。注意 setHTML 接收的是完整 HTML 字符串不是纯文本。如果你从数据库取出来的是转义过的字符串要先还原成 HTML 再传入否则页面上会直接显示 p 标签源码。5. 二开与替换自定义按钮和老系统改造顺序5.1 自定义一个“插入本地图片”按钮老版本编辑器的工具栏本质上是一个配置数组。二开时想加按钮常见做法是找到工具栏配置文件里按钮定义的位置追加一个对象然后在编辑器页面里实现对应的命令逻辑。命令逻辑可以是 execCommand 的封装也可以是自己写函数操作 iframe 内文档。比如插入本地图片核心思路是先调上传接口拿到 URL再用 execCommand 的 insertImage 把图片塞进正文。需要注意这个 insertImage 是在 iframe 内部的 document 上调用而不是外层页面。5.2 老项目里的改造判断顺序接手一个还在用 eWebEditor 的老系统先别急着替换。我的判断顺序是先统计编辑器出现过的页面数量、上传接口的被引用范围、数据库里既有正文的标签复杂度。数量多、库里数据杂优先保留编辑器、修复痛点只有两三个页面在用替换才划算。替换方向也不是非黑即白可以先保留老编辑器的上传接口前端换一个现代编辑器组件复用已有 JSP 接口减少服务端改动。按这个思路做完几个老项目后我的习惯是不轻易全盘替换也不硬守老代码先把“编辑链路”和“存储结构”这两个约束点摸清再决定投入方向。希望这篇笔记帮你把 eWebEditor 0.1.4 这套老系统看明白也希望你接手时少踩几个我踩过的坑。本文还有配套的精品资源点击获取