我先说一个我真实遇到过的业务需求系统里的在线文档编辑器用的是wangEditor用户上传了一份带完整目录的PDF产品手册期待导入之后能在编辑器里保留这份目录、直接按章节编辑。大多数人面对这个需求的第一反应是“打开PDF全选复制粘贴”。结果粘进去之后问题一大堆——标题全部变成了普通段落书签目录彻底丢失页眉页脚跟着正文混进来全文变成一坨无法快速导航的文字块。这篇文章就是围绕“PDF导入、书签识别、目录结构还原”这三个点讲清楚如何在wangEditor中实现一套可落地的PDF导入方案。先说明一个容易误解的点标题里说的“识别书签和目录结构”并不是指做人脸识别或者OCR图像识别而是解析PDF文件内部已有的“大纲Outline”数据——也就是你在Adobe Acrobat或浏览器PDF阅读器左侧看到的书签树。只需要把这份大纲树读出来再映射成wangEditor里的多级标题标签导入后的文档就能在编辑器里拥有完整的目录层级。1. 这个需求到底在解决什么问题1.1 直接复制粘贴为什么行不通做过在线文档编辑功能的人应该都遇到过用户从PDF里复制内容粘到富文本编辑器里的场景。PDF复制的文本和Word复制不同它本质上是从“页面渲染层”抽取到的文字片段PDF自身不会告诉浏览器“这一段是标题、那一段是正文”。所以你粘进wangEditor之后原本是H1、H2的标题全部变成普通的p段落视觉层级消失。PDF里的书签/大纲信息完全不会被复制目录结构无从谈起。页眉、页脚、页码等重复内容会混进正文需要人工删半天。强内联样式和异常换行会把编辑器里的样式体系搅乱。这些问题的根源是因为PDF的视觉排版结构和语义结构是分离的。PDF里只管“这行字画在页面什么位置、用什么字号”并不直接说明“这是三级标题”。它唯一的语义化信息就是大纲树也就是书签。1.2 最终要做出什么样的效果我理想中的效果是这样用户选择一个PDF前端解析完成后wangEditor里自动生成一份多级目录每一级对应一层标题h1产品介绍/h1 h2产品概述/h2 p正文内容……/p h2核心功能/h2 h3在线协作/h3 p正文内容……/p这样编辑器里既有清晰的文档结构又能直接在标题块上继续编辑还能通过后续扩展在编辑器外做一个点击跳转的目录面板。更重要的是这份目录不是写死的静态代码而是真正变成了编辑器内容的一部分用户可以增删章节、改标题文字。1.3 哪些业务场景最需要这个能力我总结下来大体有这几类合同/法务文档库用户上传带目录的合同扫描PDF导入后需要快速定位条款章节。企业内部知识库把产品手册、规章制度PDF导入编辑器转为可检索可修改的在线文档。内容采编平台编辑需要把外部PDF资料里的骨架结构引用过来再替换成原创内容。公众号排版素材库把PDF画册转成图文内容保留章节结构可以省去大量手动排版工作。无论哪种场景核心诉求只有一个把PDF的“目录结构”翻译成编辑器能理解的多级标题结构而不是把PDF当成一张图片或一段纯文本塞进去。2. 技术选型为什么 pdf.js 是唯一靠谱的解析方案2.1 pdf.js 的核心能力与书签提取原理目前前端做PDF解析绕不开Mozilla维护的 pdf.js 。它基于Web Worker异步解析PDF文件会把PDF内部的目录字典读取出来通过getOutline()方法暴露给我们。这里的“Outlines”就是PDF规范里定义的大纲结构官方实现的Acrobat书签、Chrome阅读器的左侧目录底层读的都是同一份数据。有个细节值得说pdf.js的getOutline()不需要先渲染任何页面它只解析PDF交叉引用表和目录对象所以速度通常比逐页渲染要快得多。同时它返回的是一个嵌套数组节点之间的父子关系天然对应着目录层级。提取书签这件事pdf.js几乎是前端唯一能开箱即用的方案。2.2 和其他前端解析方案的对比有同事问过我“pdf-lib不是也能解析PDF吗”这里做个对比方案能不能提取书签大纲能不能渲染页面体积/复杂度适用场景pdf.js可以有getOutline()方法可以Canvas渲染效果好较大带worker浏览器端完整解析pdf-lib不行主要做生成和修改PDF不行较小创建/编辑PDF时用后端PDFBox或Java库可以功能强可以需要后端接口有服务端资源时选用所以最终我选了pdf.js。但对于超大PDF如果前端解析内存压力过大也可以把解析逻辑放到后端再把解析结果以JSON传给前端pdf.js只负责渲染预览。这是一个很好的降级方案后面我会提到。2.3 worker 配置与版本锁定的问题用pdf.js最常遇到的就是Worker配置问题。原因是pdf.js的解析逻辑放在Worker线程里浏览器需要加载对应的pdf.worker.min.js文件。除了版本要完全一致之外Vite、Webpack这类打包工具对Worker的处理策略也不一样经常会出现“版本不匹配”的报错。我的做法是显式指定import * as pdfjsLib from pdfjs-dist import pdfWorker from pdfjs-dist/build/pdf.worker.min?url pdfjsLib.GlobalWorkerOptions.workerSrc pdfWorker关键点是?url后缀打包后它会返回一个可访问的资源URL而不是把Worker代码打进主包。如果直接使用CDN版本需要确保当前pdfjs-dist的npm版本和CDN里的版本号完全一致否则一些奇怪的低级报错会让人排查到怀疑人生。3. 第一步从 PDF 中完整提取书签目录树3.1 读取文件并初始化 PDFDocument无论用户是从文件选择器还是拖拽区域拿到PDF第一步都是拿到File对象然后把它转成ArrayBuffer喂给pdf.js。需要注意兼容性现代浏览器都支持file.arrayBuffer()如果项目还要兼容老浏览器就得用FileReader。async function loadPdfFromFile(file) { const arrayBuffer await file.arrayBuffer() const loadingTask pdfjsLib.getDocument({ data: arrayBuffer }) const pdf await loadingTask.promise return pdf }getDocument返回的是一个PDFDocumentLoadingTaskloadingTask.promise返回PDFDocumentProxy。从这里就能拿到numPages、getOutline()等等方法。这里建议把文件大小限制在100MB以内太大会导致ArrayBuffer直接吃掉几百MB内存浏览器容易卡死。3.2 getOutline 拉取书签树的返回结构获取书签的方式很简单const outline await pdf.getOutline()但outline返回的并不是一个扁平数组而是一个嵌套结构。每个节点的核心字段是title书签显示的文字比如“第一章 绪论”。items子书签数组没有子节点就是空数组。dest书签跳转目标通常是一个数组表示跳转到某页具体位置。url如果书签指向外部链接这个字段会存在。看一个真实的结构[ { title: 产品介绍, dest: [{num: 1, gen: 0}, XYZ, 0, 760, null], items: [ { title: 产品概述, dest: [{num: 2, gen: 0}, XYZ, 0, 500, null], items: [] }, { title: 核心功能, dest: [{num: 3, gen: 0}, XYZ, 0, 600, null], items: [ { title: 在线协作, dest: [{num: 4, gen: 0}, XYZ, 0, 720, null], items: [] } ] } ] } ]注意items是嵌套的所以层级关系需要递归处理。dest的第一个元素是一个页码引用对象后面跟着的是定位模式这一步我们暂时用不到但后面如果要实现“点击目录跳转到PDF对应页”就很有用。3.3 递归归一化层级、空标题、特殊字符处理拿到原始outline之后不能直接拿来用。我见过不少PDF导出的书签里存在脏数据常见问题包括标题前后有大量空白、包含换行符/制表符/不可见控制字符、标题为空但还有子节点等。所以需要一个归一化函数function normalizeOutline(items, depth 0) { const result [] items.forEach((item, index) { const title cleanTitle(item.title) if (!title) return const node { id: bookmark-${depth}-${index}-${Math.random().toString(36).slice(2, 8)}, title, level: depth, children: [], } if (Array.isArray(item.items) item.items.length 0) { node.children normalizeOutline(item.items, depth 1) } result.push(node) }) return result } function cleanTitle(rawTitle) { if (typeof rawTitle ! string) return return rawTitle .replace(/[\u0000-\u001f\u007f]/g, ) .replace(/\s/g, ) .trim() }这个id是给后面做目录跳转、锚点定位用的。还有一点值得注意item.title中可能带有编号比如“1.2 系统架构”。如果原PDF的编号风格是层级式的导入编辑器后保留编号也行但要注意别和编辑器自动编号冲突。我的习惯是保留因为对用户来说原文长什么样导入之后就长什么样最不容易被抱怨。3.4 没有书签时的兜底分支有些PDF本身就没有书签比如部分扫描件或简单导出的打印档。此时pdf.getOutline()返回null。对这种PDF强行解析是没有意义的我的做法是弹出一个提示“该PDF未包含书签目录已导入纯文本内容”然后把每个页面的文本拼起来以普通段落形式导入。let outline await pdf.getOutline() if (!outline) { outline [] }这样用户在编辑器里至少能看到内容只是没有标题层级。如果想硬着头皮做“伪目录”可以根据页面文本的字号大小来猜测标题级别但这里面的误判率很高我不推荐在正式功能里用这种策略容易把一个两行正文判断成标题。4. 第二步把目录树映射成 wangEditor 的多级标题4.1 HTML 字符串生成层级映射规则归一化之后目录树就是一个带level字段的树形结构。接下来核心是把它转成HTML字符串。wangEditor对标准h1到h6标签的支持很成熟所以这里做一个直接映射const HEADING_TAGS [h1, h2, h3, h4, h5, h6] function buildHeadingHtml(outline) { return outline.map(node { const tag HEADING_TAGS[Math.min(node.level, 5)] const title escapeHtml(node.title) const childrenHtml node.children.length ? buildHeadingHtml(node.children) : return ${tag}>editor.setHtml(buildHeadingHtml(normalizedOutline))如果需要在现有文档基础上追加我会先判断编辑器是否为空不为空就用dangerouslyInsertHtml在光标处插入。有一点要提醒dangerouslyInsertHtml的“dangerously”不是开玩笑它会解析HTML字符串并转成Slate节点如果HTML里包含不受支持的复杂结构可能会有样式丢失的风险。所以务必保持生成的HTML结构简单只用标准标题标签和少量>editor.disable() // 解析并导入 await importPdfToEditor(editor, file) editor.enable()disable()会阻止内容编辑但选区和滚动这些交互还是正常的。有朋友在评论区问过“wangEditor怎么设置只读”所以在这里顺手着重点一句除了调用editor.disable()也可以通过配置editorConfig.readOnly来控制初始化时的只读状态但运行时切换必须用disable/enable这对方法。4.4 正文文本的可选导入目录结构导入后很多场景下用户还希望把正文内容也一并带上。pdf.js也提供了页面文本提取能力async function extractAllPageText(pdf) { let text for (let pageNumber 1; pageNumber pdf.numPages; pageNumber) { const page await pdf.getPage(pageNumber) const textContent await page.getTextContent() const pageText textContent.items .map(item item.str) .join( ) text p${escapeHtml(pageText.trim())}/p } return text }这里有个需要接受的事实从PDF提取的文本是按页面渲染顺序排列的比如多栏排版时会乱序段落之间的关联也不可靠。所以正文导入更适合作为“可选的纯文本草图”真正可靠的结构化信息还是书签树的标题层级。我在代码里会把正文放在目录标题的后面形式上变成“标题段落”的合格富文本文档用户在此基础上手动修正润色比从零开始建大纲要快得多。5. 实际踩到的坑与排查过程5.1 导入后标题层级高出可视化范围第一次跑通的时候我发现有些PDF书签有6层甚至7层结构而h6已经是编辑器里最小的标题字号了视觉上几乎看不出层级区别。我当时的处理方案不够好直接把超出部分全部压成h3结果整个目录层次感一团糟。后来想明白了不能简单一刀切。正确做法是给层级做“缩位映射”类似把7层结构映射到最多5层function getHeadingTag(level, minLevel) { const mappedLevel Math.max(0, Math.min(5, level - minLevel)) return HEADING_TAGS[mappedLevel] }minLevel是整棵树中根节点的最小level。比如一本书的书签第一层就是“封面”那minLevel是0有些PDF书签第一层是“1”但它的子节点从第二层开始才有意义这时把minLevel整体抬一级让编辑器里的最高层级从h2开始视觉上更平衡。5.2 书签标题里的乱码和控制字符测试样本里有一批用老式PDF工具生成的文件书签标题里带着\r\n和奇怪的Unicode控制字符。第一次导入时我在编辑器里看到一堆空白行和乱码还以为是pdf.js的问题。后来逐条打印item.title.charCodeAt()才发现是源PDF本身的数据不干净。清理逻辑我在前面已经写了cleanTitle()这里再补充一个细节有些标题包含全角空格和\u3000也需要一并替换成普通空格。清理函数里最好加一句replace(/\u3000/g, )否则在中文文档里会出现对不齐的半透明间隙。5.3 超大PDF解析时页面冻结用户上传过一个接近200MB的PDFgetDocument走完需要好几秒期间主UI完全卡死。问题的瓶颈不是CPU而是一次性把200MB数据读进ArrayBuffer占内存太多。现场排查后发现pdf.js的getDocument本身就支持只传递url而不是data让浏览器自己处理流式下载const loadingTask pdfjsLib.getDocument({ url: /api/pdf/123 })但用户上传的是本地文件不可能先传后解析。我的折中方案是第一步先读取文件基本信息文件大小、页数给用户一个进度提示同时把大于50MB的文件提示“解析时间可能较长”。实际解析加载时在异步函数里加一个loading状态配合前面的editor.disable()阻止误操作体验就会好很多。5.4 undo 历史与导入内容的黏合问题如果用户在编辑器里已经写了一部分内容再用setHtml导入PDFwangEditor的undo历史会被清空——用户一旦操作CtrlZ不仅PDF内容没了之前写的内容也可能回不去了。这是setHtml全量替换的天然副作用。我的应对是业务上明确“导入PDF”是一个新建文档的动作在导入前弹出确认让用户知道现有内容会被替换。如果需要保留旧内容就用dangerouslyInsertHtml在光标处插入不要用setHtml。另外导入后最好把editor.getHtml()主动备份到草稿箱防止用户误操作后无法恢复。6. 进阶在编辑器旁做一个可点击跳转的目录面板6.1 从编辑器内容动态提取标题导入PDF后目录已经以h1~h6的形式存在于编辑器里。此时只要监听编辑器的内容变化就能反向提取出一份侧边目录类似Notion左侧的文档大纲editor.on(change, () { const html editor.getHtml() const container document.createElement(div) container.innerHTML html const headings container.querySelectorAll(h1, h2, h3, h4, h5, h6) const toc Array.from(headings).map((h, index) ({ tag: h.tagName.toLowerCase(), text: h.textContent, id: h.getAttribute(data-bookmark-id) || heading-${index}, })) renderTocPanel(toc) })因为导入时已经给标题加了>let timer null editor.on(change, () { clearTimeout(timer) timer setTimeout(buildToc, 300) })这种“300毫秒防抖”的做法对用户来说感知不到延迟又能避免输入过程中目录面板疯狂刷新的问题。个人经验是功能上线后先在测试环境用一本200页的PDF跑一遍导入耗时、内存占用、编辑器交互三个方面没有明显问题再放给用户使用会少接到很多抱怨。如果你准备做类似的功能我建议先把PDF样本集准备好特别是“无书签”“书签层级特别深”“书签带中文乱码”这几类样本因为在真实业务里会集中暴露问题。先跑通目录结构还原再考虑正文文本导入最终扩一个侧边栏目录这套组合拳做完功能就非常完整了。