1. 需求梳理与整体方案选型先明确这个功能到底在解决什么问题。xhEditor本身是一款轻量的HTML富文本编辑器常用于后台CMS、OA、在线表单这类场景。它本身没有PDF导入能力也没办法对导入后的内容做标注。但实际业务中经常出现这样的场景运营人员手里有一份PDF上面已经有了一些重点标记和批注需要把这份PDF的内容连同这些标注一起整理进网页表单提交到后台。通常的做法是把PDF手动转成Word或图片再逐段复制粘贴高亮和注释全部丢失只能重做一遍。如果PDF很大这件事就变成纯粹的体力劳动。所以这个功能的核心价值在于用程序代替人工完成“PDF内容提取 高亮标注重建 注释关联”三段式流水线让最终用户可以像使用PDF阅读器一样在浏览器里完成对导入内容的二次编辑。选型上我推荐前端解析加后端存储的混合架构。前端负责PDF解析、渲染、高亮交互、注释绑定后端只做两件事接收上传的PDF原文件和接收最终标注数据JSON。这样的好处是交互层完全在浏览器内完成不需要页面跳转体验接近桌面软件。同时标注数据是结构化JSON方便回读恢复和二次编辑。如果你问为什么不在后端用Python或者Java把PDF转成HTML再塞回编辑器我实测下来不太推荐。原因是PDF转HTML的过程会丢失大量排版细节尤其是多栏排版、表格、带边框的段落转出来的HTML结构几乎不可控而且文本和原位置的对应关系会失真想做精准的文本高亮几乎没有抓手。留一个渲染层在前端所有坐标和文本都被保留标注逻辑做起来才有基础。1.1 整体流程拆解整个功能可以拆成五个环节用户在xhEditor工具栏点击“PDF导入”按钮。弹窗内上传PDF文件前端利用pdf.js进行解析并渲染出带文本层的预览页面。用户在预览页中选择文字进行高亮标记对指定文本添加注释内容。点击“确定导入”前端将当前页面的文本内容和标注数据合并成HTML插入xhEditor编辑区域。标注数据同时以JSON格式附加到编辑内容中下次打开编辑器时可根据JSON重建高亮和注释位置。这个流程的好处是每一步的产物都很明确PDF原文件和标注JSON可以分离存储前端不是一次性把PDF内容“压平”成草稿而是保留了一层可编程的中间状态。这样后续想做批注导出、标注统计、PDF对比都有基础。1.2 技术栈准备核心库只需要一个pdf.jsMozilla出的PDF解析渲染引擎兼容性很好支持到IE11其实都还能跑不过现在不用考虑那么古老的浏览器了现代项目直接用最新版没有问题。另外建议准备一个工具库用来操作文本选区和Range对象我自己习惯直接用原生API加部分polyfill因为PDF文本层的高亮渲染不是普通的DOM选择需要精确控制范围。当然如果你熟悉rangy这类库用它简化跨浏览器选区操作也可以代码会更稳妥。这一层如果不打扎实后面所有标注逻辑都会出问题。不要在这个环节偷懒一定要把PDF解析结果的结构彻底摸清楚再进行设计和开发。2. 核心难点一PDF文本层的可靠提取PDF理论上是一种“打印描述语言”它记录的是文字应该在哪个坐标画出来而不是像HTML那样有段落分块的结构。所以第一步就是要让PDF里的文本变成可供浏览器操作的真实文本节点。pdf.js内部已经帮我们做了解析工作通过pdfjsLib.getDocument()拿到PDFDocument对象然后逐页调用page.getTextContent()即可获取该页的文本内容。返回的TextContent.items数组里每一项包含str当前文本片段的内容transform6元数组描述当前文本块的变换矩阵width、height当前文本块的宽高fontName字体名称str内容很多时候不是一个完整的行而是被PDF内部绘制指令切成了多个小块。举个例子一句话“请认真阅读以下条款”在PDF里可能被拆成“请认真阅”“读以下条”“款”三段因为PDF排版引擎在计算换行的位置时可能以字间距为依据。所以要实现高亮和注释绝对不能直接用items数组的原始顺序来拼文本必须做一步后处理把同一行内相邻的文本块按y坐标和水平间距合并成“行单元”。这里有一个核心的对比表格情况PDF内拆分方式直接使用后果同一行文本被拆分多个item同y坐标注释选中文字时跨item无法精准映射字体嵌入了子集item内容有乱码或偏移高亮匹配失败多栏结构左右两栏y坐标交叉按顺序拼接会串行文本旋转transform中包含旋转角忽略transform会导致坐标错乱大面积空白item坐标间距异常大合并时把不同块误拼成一行把items按行合并成line对象数组之后每个line对象大致包含这样的信息{ text: 完整的一行文本, x: 12.3, y: 45.6, width: 123.4, height: 12, pageIndex: 0, items: [/* 原始item引用用于精确坐标计算 */], lineIndex: 2 }这个行级结构是后面做文本高亮的基石。xa0注意在合并时要用transform[4]和transform[5]作为x和y坐标不要自己去猜坐标轴的偏移。在实际写代码时我按y坐标将items分桶再按x坐标排序对水平方向相邻且间距不超过一个字符宽度的碎片执行拼接。为了避免多栏版式导致串行我还会检查x坐标之间的间距当某一批item的x坐标明显分成几个簇时按簇拆开处理。文本提取还有一个容易被忽视的点很多PDF文件里的空格字符不是普通空格可能是non-breaking space\u00A0、细空格\u2009等变体。如果直接拼接后在页面上做匹配处理匹配逻辑很容易因为空格类型不一致而失败所以我在处理text层的时候会把所有Unicode空格统一替换为普通空格并额外记录原始坐标数据保证后续搜索时不受空格变体干扰。3. 核心难点二注释对象的数据建模与渲染高亮和注释不是简单选中一段文字涂个色它们会随着文本位置的变化而迁移用户希望再次打开时标注还在原来的位置上这是这个功能是否能实际落地使用的唯一标准。3.1 注释数据的存储结构设计我设计了一套扁平但完整的JSON结构每条标注包含以下字段{ type: highlight, // 固定类型 id: node-3f2a1b, // 全局唯一ID pageIndex: 0, start: { lineIndex: 2, offset: 0, nodeId: line-2-3 }, end: { lineIndex: 3, offset: 15, nodeId: line-3-2 }, color: #ffeb3b, comment: 这里需要财务确认, createTime: 1700000000000, anchorText: 请认真阅读以下条款并确认 }字段看起来简单但每一个都有讲究。lineIndex和offset的组合能唯一定位某一段原文anchorText是冗余字段用于校验和还原时的二次确认。nodeId字段用于精确找到DOM节点避免后端渲染时重新遍历查找。color可以灵活扩展比如可以支持红黄绿三种经典色。为什么不用全局字符串偏移量因为PDF解析出来的文本在合并成行之后我们不一定能保证所有字符都按自然阅读顺序排列表格、页眉页脚、上标下标都会造成顺序错乱。用全局偏移量一旦出现微小偏差后面全部错位。而用行索引加行内偏移量即使前面的行偏移了也只会影响到这一条标注本身。3.2 高亮渲染的两种思路对比高亮渲染有两种主流方案Box覆盖层方案和Inline包装方案。Box覆盖层方案是指维护一个独立的绝对定位透明层在用户选中一段文字后通过Range.getBoundingClientRect()获取选中区域的位置信息然后在覆盖层绘制与文字重合的半透明色块。这种方案对原始DOM的侵入性小撤销高亮很干净但难点在于如果被选中的文字跨行了需要自己把矩形拆成多个小矩形分别绘制。Inline包装方案是直接获取选中Range的surroundContents或手动拆分文本节点然后给目标文本包一层带背景色的span元素。这样DOM结构就真实变成了带样式的内容可以随文本流自然换行不需要维护坐标系统。缺点是需要仔细操作文本节点树否则很容易拆坏原有节点结构。我实际生产环境中用的是混合方案预览阶段用Box覆盖层方案因为用户在交互过程中要反复调整选区、增删标注覆盖层方案性能好、无副作用。等到点击“确定导入”时一次性把选中的标注内容转换为Inline包装方案对应的HTML插入xhEditor。这样既保证了交互阶段的流畅性也保证了最终编辑内容的结构完整。至于为什么最终要用Inline方案因为xhEditor在编辑状态下会持续修改DOM覆盖层一旦脱离文本框流式排版就很容易错位而Inline标签随文字走怎么编辑都不怕。3.3 文本选中与锚定匹配的处理用户操作场景大致是在PDF预览区拖拽选中文案点击“添加高亮”后输入注释文字。但实际操作中经常出现这样的问题你以为你选中了一段文字但Range对象拿到的文本和行文本并不完全一致。比如预览文本层渲染时span节点可能会被浏览器的自动断行逻辑打断。用户选中“重要通知”这四个字可能跨了两个span。这时候如果你直接用range.toString()去匹配行文本结果是匹配不上的。我采用的办法是在鼠标按下时记录当前鼠标坐标对应的文本节点在鼠标松开时用document.caretRangeFromPoint获取起止位置然后通过自定义的选区归一化函数把所有部分选中的文本节点按字符粒度拆分重建成一个干净的选区。这个函数也负责处理零宽字符和空白节点。归一化之后把选中的字符串和当前页面的行文本做一次模糊匹配确认所选内容确实存在于行列表中然后顺便计算出起止的行索引和行内偏移量。整个过程实现了“选中即定位”用户完全无感知。匹配需要注意一个容易踩坑的点PDF中OCR识别的文本扫描件经常有识别错误l和1、O和0混淆是家常便饭。如果产品做的是扫描件PDF标注建议准确率优先于召回率匹配不上就提示用户手动修正不要自动就近匹配否则很容易“高亮到隔壁老王头上去了”。4. 实战把标注功能集成进xhEditorxhEditor是个老牌编辑器它的交互框架比现代前端框架要“传统”得多。集成的时候对新的Vue/React项目没什么问题直接把编辑器实例当作一个黑盒调用即可。这里我以最常见的jQuery版本接入示例因为实际工作中还有大量老项目在用jQuery版本。4.1 在工具栏注册PDF导入按钮xhEditor的按钮是通过xheditor.settings里的tools属性注册的。在初始化编辑器时加入一段自定义按钮定义按钮类型利用btn触发点击事件$(#content).xheditor({ tools: full, skin: default, upImgUrl: /upload/image, upImgExt: jpg,jpeg,gif,png, onInit: function() { // 注册一个自定义事件 var editor this; editor.addCustomBtn(pdfImport, PDF导入, function() { openPdfImportDialog(editor); }); } });注意xhEditor的版本差异比较大老版本文档里是addCustomBtn新版改成了addShortcuts加按钮的方式。根据你的版本灵活处理核心作用是注册一个打开弹窗的入口。4.2 PDF弹窗内部布局弹窗我直接用一层半透明的遮罩层加一个居中的容器实现不依赖编辑器自带dialog组件因为自带dialog高度和宽度限制比较多PDF预览需要比较大的空间。弹窗内部包含顶部操作栏上传按钮、分页导航、页码输入框、高亮颜色选择、注释输入框左侧主区域Canvas或DOM方式渲染的PDF页面右侧浮动面板当前页已添加标注的列表可以点击定位、删除上传PDF后使用FileReader读取文件为ArrayBuffer然后交给pdf.js加载。const file document.getElementById(pdfUpload).files[0]; const reader new FileReader(); reader.onload function(e) { const pdfData new Uint8Array(e.target.result); loadPdf(pdfData); }; reader.readAsArrayBuffer(file);PDF加载完成后第一页就渲染在页面上。渲染有两种方式Canvas渲染和DOM文本层渲染。Canvas只负责显示背景页面的文字轮廓文本层才是真正承载选中交互的透明层。我采用的方式是Canvas放在最底层文本层放在Canvas上方绝对定位层文本层里的每个span设置了与Canvas文字一致的坐标、字体大小、字重、颜色透明。这样用户看到的视觉效果是Canvas呈现的文字而鼠标点击、拖拽、实际选中的是上方的透明文本层交互逻辑和视觉完全解耦。文本层每个span元素需要带上我们前面提到的行索引信息我直接用自定义属性标记span classpdf-text-line >导出的HTML结构p classpdf-import-block>通过editor.setContent()或exec(inserthtml, html)把内容插入编辑器editor.exec(inserthtml, generatedHtml);注意使用inserthtml会保留当前光标位置后续还能继续编辑用setContent会整体替换内容适合从空白状态开始导入的场景二者按需选择。4.4 持久化与回显机制标注数据的保存我单独维护了一份JSON结构包含了原始的PDF来源信息、标注坐标、注释内容等。在实际项目里这份JSON对应一套独立的存储字段跟xhEditor的HTML内容字段同表。当用户重新打开一个已经导入过PDF标注的编辑页面时初始化的逻辑是先正常加载xhEditor内容然后通过一段脚本扫描HTML中的.pdf-annotate-segment节点读取其>