项目背景
本项目是Vue 3 项目，需要使用文件预览组件（pdfjs 当前是作为sdk二次封装引入），但是二次封装时通过 npm 安装的 PDF.js 默认只包含核心功能库（pdfjs-dist），主要包括 PDF 文档的解析、渲染等基础功能，而不包含完整的查看器 UI（如目录/书签导航、缩略图、搜索等高级功能）。
一、方案一：数据透传 + 外部开发模式
▎核心思路
- 将PDF.js生成的原始目录数据通过事件透传给父组件，在业务层Vue环境中实现完整目录功能。
▎优势
开发体验友好
可在熟悉的Vue环境中使用v-for等指令渲染树形结构
直接接入项目现有的状态管理（如Vuex/Pinia）样式控制绝对自主权
完全匹配项目设计规范
支持动态主题切换等业务特性功能扩展便利性
轻松添加目录搜索、书签等衍生功能
与业务逻辑深度集成（如目录标注）
▎痛点
dest兼容性泥潭(dest定位的
可靠性处理)
大多数PDF存在非常规dest结构（不可控的dest数据结构）
需要处理/GoTo、/Named等多种Action类型版本耦合风险
PDF.js版本升级可能改变getOutline()返回结构
需要为每个版本维护适配层
PDF.js 中的 dest 数据结构 是用于实现 PDF
文档内部导航的核心机制，特别是在处理目录（书签/大纲）跳转时起到关键作用。它的本质是 目标位置描述符，定义了如何精确跳转到文档中的特定位置（页面、坐标、缩放比例等）。
▎适用场景
企业内部文档系统（dest 数据结构可控）
需要与业务系统深度交互的定制化需求
二、方案二：内置组件 + 黑盒模式
▎设计本质
将目录功能完全封装在PDF二次开发预览组件内部，通过配置接口对外暴露必要控制能力。
▎优势
架构整洁性
符合单一职责原则
避免目录相关代码污染外层业务逻辑一致性保障
所有PDF处理逻辑保持统一风格
版本升级只需更新单个组件
▎方案一 vs 方案二的本质相同点
- ❝两者都需要自主处理dest解析❞
都面临PDF规范多样性问题
都需要实现resolveDest的健壮性逻辑
▎方案一 vs 方案二的唯一区别
❝UI渲染的物理位置不同❞
方案一将目录树渲染暴露到业务层，方案二封装在二次开发的组件内部
但两者共享相同的dest解析风险
三、方案三：激活官方实现 + 可控定制
▎动因
基于PDF.js内置的PDFOutlineViewer进行二次开发，保留核心解析引擎，替换UI层。
▎关键
解析可靠性
官方已处理200+种边缘case
自动兼容PDF 1.3-2.0规范差异维护成本
版本升级时目录解析逻辑自动同步更新
无需额外测试dest解析异常场景定制可行性
可通过CSS覆盖修改视觉表现
通过事件劫持可修改交互行为（如点击阻止默认跳转）包体积影响
需额外引入pdf_outline_viewer.js
▎技术决策平衡点
- 保留官方核心价值：dest解析、文档兼容性处理
- 置换可视化部分：字体/颜色/间距等视觉层
- 扩展有限接口：通过事件总线暴露关键交互节点
▎方案三的破局点
❝将最不稳定的部分外包给PDF.js❞：官方解析器已处理这些常见case
通过PDFLinkService统一管理跳转逻辑，避免重复造轮子
总结
最终选择方案三的核心逻辑
风险对冲
将最容易出错的解析逻辑交给PDF.js维护，同时通过样式覆盖保留UI控制权，实现"核心稳定+外观可控"的平衡。演进可能性
保留逐步替换的可能性：初期使用官方解析器，后期可针对高频文档类型开发优化版解析器，形成混合架构。
虽然初期只实现目录，但后期增加缩略图也可以依赖于pdfjs demo 提供的能力。
如果 核心需求只是展示目录树 UI（不需要交互跳转功能），那么方案一和方案二更简单。
这篇文章呈现了真实项目中的技术权衡过程，突出了每种方案在实际验证中暴露的优缺点，而非理论上的特性对比。这种基于实证的决策方法能有效避免架构设计中的理想化陷阱。