1. PDF能力全景：先看清鸿蒙给了我们什么
做鸿蒙端的PDF功能，一开始我是拒绝的。我看了不少技术社区的帖子，发现很多开发者在拿到PDF相关的需求时，第一反应就是“能不能用WebView套一个浏览器插件”，结果要么交互体验割裂，要么在低端设备上卡得没法看。直到我真正把鸿蒙自身的PDF组件、文本提取接口和渲染管线摸了一遍，才意识到原生方案虽然要写更多代码，但性能和可控性完全是另一个档次。
这次要分享的内容，核心是围绕PDF页面、文本、图片和批注四条线展开的实战记录。我接到的需求在某办公类项目里非常典型：用户要打开一份PDF，既能看到页面内容，又能选中文字复制，还要能对重点内容做高亮或批注，甚至要能导出带批注的新PDF。这个需求链条几乎覆盖了鸿蒙PDF能力的全部关键词：页面渲染、文本定位与提取、图片资源解析、批注数据模型与持久化。
在动手之前，我建议先搞清楚一个概念：鸿蒙的PDF能力不是一个单独的“PDFView控件”那么简单的存在，它其实分了三层。底层是基础文档解析能力，负责打开PDF、解析页面和资源对象；中间层是渲染能力，负责把页面内容绘制到画布上；上层才是我们直接面向用户的功能组件，比如滚动容器、手势缩放等。很多新手容易犯的错误，是一上来就想找个“万能组件”把PDF整个塞进去，结果发现自定义批注、局部刷新、文本选中这些需求根本没法实现，最后还是要回到手动搭建的方式。
其实鸿蒙官方已经提供了PDF文档创建、解析、合并、拆分等能力，但真正适合业务落地的，是用自定义组件配合底层绘制接口自己搭一套“PDF阅读框架”。我推荐的做法分四步走：第一步，用文档对象打开PDF并获取页面信息；第二步，用渲染接口把页面绘制到可交互的画布上；第三步，叠加批注层，把用户手势转换成批注数据；第四步，将批注数据序列化存储或合并回PDF。这套流程的优点是每一层都可控，排查问题时可以精准定位是渲染、解析还是手势处理出了问题。
还需要明确的一点是鸿蒙开发中使用的是TypeScript语法风格的ArkTS语言，它和标准TS有一些约束差异，比如不能使用any类型、不能解构赋值，这些细节在写PDF工具类的时候容易被编译器卡住，我后面会专门讲到。总而言之，这篇文章的受众是那些不想只做“能打开PDF”的开发者，而是想做得更深入的人，比如要实现阅读器App、文档批注工具、教育答题器之类产品的同学。
2. 文本提取：让PDF内容真正变得可用
2.1 文本提取的几条路径与选型逻辑
我们常见的业务场景里，文本提取分两种需求。第一种，用户只是想在UI上展示某些页面的文字内容，比如阅读器里的“目录解析”“关键词高亮”；第二种，用户要拿到文本的精确坐标，用来做点击区域、批注关联等交互操作。这两种需求对API的要求完全不同。
鸿蒙提供的PDF组件中，文档对象能直接支持按页获取文本内容，也可以获取文本所在的坐标信息。我用过两种实现方式：一种是通过PDF页面对象的文本内容接口直接读取当前页的文本块，再遍历文本块的字符数据；另一种是通过自动测试框架的控件树，把PDF页面里已经渲染出来的Text控件全部抓出来。第二种方式其实不推荐在正式产品里用，因为它依赖渲染进程的反馈，拿到的是控件节点而不是纯数据，遇到加密PDF或者超大文档时容易丢失信息。
我最终采用的是文档对象+页面对象的方式。它的好处是解析速度快，不受UI渲染状态影响，而且能拿到精确的字符级坐标数据。说白了，这套接口做的是“从数据到数据”的解析，不经过UI层，可靠性和性能都有保障。
具体步骤大致是这样：先用文档对象打开文件，传入文件路径或文件描述符；然后遍历页索引，对每一页调用页面对象的文本读取接口，拿到一个文本块列表；每个文本块又包含若干字符，每个字符带字体信息和坐标参数。有了这些数据，我才能实现“按区域选词”“高亮某个关键词”“批注锚定到具体字符”这些高级功能。
实际开发中有个细节值得注意：PDF文本提取本质上走的是字体文件的编码映射逻辑，如果PDF里内嵌的字体没有提供ToUnicode映射表，那提取出的字符可能是乱码或者占位符。这属于PDF文件本身的问题，代码层面很难彻底修复，只能做兜底处理，比如检测到提取置信度低时提示用户“当前文档不支持复制”。
2.2 文本坐标：把文字和界面关联起来的关键
只有文字内容没有坐标，很多交互功能就做不了。比如用户点击页面上的某个词，我要知道这个词在哪个文本块里、覆盖了多大区域，才能正确弹出批注输入框。这就需要在初始化文档时同步建一个“文本坐标索引”。
我习惯的数据结构是这样的：以页码为一级键，存储该页所有的文本项数组，每一项包含文本内容、文本块的矩形区域、字符数组以及每个字符的坐标。这个结构相当于给PDF的每一页做了“可检索层”，后续做点击检测、关键词高亮、批注锚定都直接查这个索引，不用重复解析页面。
创建索引时注意三点：第一，PDF的坐标系原点在页面左下角，而屏幕坐标原点在左上角，拿到坐标后需要做Y轴翻转换算；第二，页面可能有旋转属性，旋转角度不为零时坐标换算还要考虑旋转矩阵，否则文字位置对不上；第三，中文PDF里经常出现一个文本块包含多个半角空格的情况，过滤这些占位字符能避免点击区域误差。
我做过一个实验，用一份100页的PDF测试，索引构建的时间大约占总文档打开时间的30%左右，其实可以接受。但我建议不要在主线程同步构建，应该丢到子线程里分批处理，构建完一个页面就通知UI层刷新，这样用户看到的是页面逐渐变得“可选”而不是转圈等待。
2.3 踩坑记录：文本缺失与乱码的排查思路
文本提取过程中，我遇到过几次比较典型的异常情况，在这里记录一下排查思路。
第一种，某页文本完全提取不到。这种情况优先级最高的是确认这一页是普通文本层还是扫描图片层。很多PDF文档是扫描件，所谓“文字”其实是一张整页图片，没有任何文本对象可以提取。这种文档要想让用户能复制文字，必须走OCR路线，但这就超出PDF组件本身的范畴了。我当时的处理是在界面里判断该页文本项数量为0，就提示“本页为扫描件，暂不支持文本选择”。
第二种，文本能提取到但坐标明显偏移。偏移产生的原因大概率是坐标系换算出了问题。我排查过一次，发现是页面对象返回的是页面空间坐标，而我在绘制时做了缩放操作，忘了同步换算系数。用真实设备一测，文字和点击区域差了几十像素，肉眼看上去非常奇怪。后来我统一封装了一个“页面坐标转屏幕坐标”的工具函数，所有交互入口都必须经过这个函数，偏移问题才彻底消失。
第三种，提取出的字符串里混入重复内容。这种情况其实出现在某些通过第三方工具导出的PDF中，内部结构冗余导致的。我的兜底做法是对提取结果做清洗，比如去除连续重复的空白字符、剔除不可见控制符，虽然不能解决所有问题，但能把展示层的影响降到最低。
3. 图片能力：从渲染到提取的完整链路
3.1 页面渲染：把PDF变成可交互的画布
PDF页面本身不是一张图片，它是一组绘制指令的集合，所以在屏幕上显示PDF本质上是实时执行这些绘制指令，把结果输出到画布上。鸿蒙的PDF渲染能力支持将指定页面绘制到一个Canvas画布，这个过程中可以设置缩放比例、绘制区域和背景色，所以我完全可以在自定义组件里画出一个支持缩放的PDF阅读视图。
我实际构建阅读器时的做法是：自定义一个组件继承自基础容器，内部持有一个Canvas作为渲染目标；初始化时读取当前页的像素宽高，计算适合屏幕的缩放基准值；每次手势缩放结束后，把目标缩放率应用到Canvas的绘制参数里重新渲染。
这里有几个性能关键点要提前规划。渲染PDF页面是比较重的操作，如果每次手势变化都触发全页重绘，中低端设备必然卡顿。我的做法是采样率控制：手势过程中只显示上次渲染的位图拉伸结果，手势结束后才触发一次高质量重绘。这种先“低清晰度预览”、后“高清晰度确认”的方式，在阅读类App里非常常见，用起来也确实舒服。
另外，PDF页面里有大量矢量图形和嵌入字体，渲染一次可能耗时几百毫秒，所以页面缓存绝不能少。我用的是双缓存策略：内存缓存最新N页的渲染结果，本地磁盘缓存被回收的页面渲染图。用户来回翻页时，通常能命中内存缓存或磁盘缓存，基本感觉不到重新渲染的等待。
3.2 图片提取：从PDF里抠出可复用资源
除了整页渲染，有些业务场景需要单独提取页面里的某张图片，比如用户想保存PDF中的插图，或者课件类App要把PDF里的图表原样复用到其他课件里。这个需求也可以用PDF解析能力实现，遍历页面资源对象，筛选出图像类型对象，再解码成位图数据。
实际提取中最麻烦的问题是图片滤镜和色彩空间。有些PDF为了压缩体积，内嵌图片用的是JPEG2000或CCITT压缩，这些算法在移动端未必有现成解码器。鸿蒙的底层图像框架支持常见的JPEG、PNG、WEBP格式，遇到不支持的压缩类型时，就需要把图像数据解码成原始像素缓冲，再手动进行色彩空间转换。这块代码我不建议自己完全从零写，可以先判断图片是否能直接解码，不行就调用更高层的图像转换接口做兜底。
提取图片时的尺寸参数也要注意设置。你直接拿原图分辨率，一张高清PDF里的插图可能是4032x3024的，内存直接翻车。我一般会按用途区分：缩略图场景限制最长边为360像素，导出原图场景则使用原始分辨率，但要放在子线程解码，并串行处理避免同时解压多张大图。这个策略在实际使用中简单有效，至今没出现内存峰值问题。
3.3 渲染性能：大头针测试与预加载策略
性能测试这件事，我建议不要只在小屏手机上测，一定要模拟不同性能档位。我用的方法很简单：把典型的大文件PDF（比如100MB、带大量高清插图的画册）放到三档性能水平的设备上测试，记录首屏渲染时间、连续翻页帧率、内存峰值这三个指标。
从实测数据看，最影响体验的是“首屏时间”。首屏如果超过两秒，用户大概率会直接关掉页面。所以我把首屏渲染拆成两个阶段：先显示封面页的基础内容，两三百毫秒内快速绘制出第一帧，等用户交互时再补充细节渲染。这种“渐进加载”思路在超大PDF上效果特别明显，体感从“卡死”变成了“秒开”。
预加载策略方面，我采用“当前页前后各一页”的机制，只用内存缓存2到3页的渲染位图。这个预算在多数设备上是安全的。唯一需要注意的是，缓存里的位图要复用Bitmap对象，分配新内存和释放旧内存的频次越低，GC压力越小。
4. 批注功能：用户真正关心的能力
4.1 批注的数据模型：先定清楚再动手
批注是所有PDF阅读器里开发成本最高的功能，因为“批注”这个词覆盖了太多不同形态：高亮是批注，下划线是批注，手写笔迹是批注，便签是批注，甚至图形的圈选也算批注。如果每个类型都单独设计一套存储逻辑，后面会非常痛苦。
我推荐的做法是先定义一整套统一的批注数据模型，关键字段包含：批注类型、页码、位置区域、归一化坐标、创建时间、修改时间、所属用户标识、自定义扩展字段。其中“归一化坐标”的意思是，无论你屏幕怎么缩放，批注的相对位置都保持不变，这样下次打开文档时，批注还能精准地落在原来的位置附近。
位置区域根据类型不同有区别，比如高亮批注存的是字符矩形集合，手写批注存的是笔迹点序列，便签批注存的是锚点坐标。我的惯例是统一用“区域数组 + 附加数据”的组合，每种类型在渲染时再去解释对应字段。这样做的好处是数据模型只有一张表，增删字段的扩展成本低，也不会因为新类型打乱已有的存储结构。
批注数据还要带上写入和修改的时间戳，在支持多人协作的文档系统里，时间戳和用户标识是冲突解决的基础。虽然本地单机App暂时用不到协作，但字段先留着，后期和云服务对接时能省下不少事。
4.2 两类批注实现：内置能力与自绘方案
批注的实现方案，大致分成两条路径：一条是直接使用鸿蒙PDF能力中可能提供的注释接口，另一条是自己维护批注图层，叠加在PDF页面上实现渲染、命中检测和编辑功能。两条路我都测过，这里分享一些对比结果。
内置注释接口的好处是生成的批注数据可以直接写入PDF文件，导出的文档在任何标准PDF阅读器里都能识别。它在处理高亮、下划线这类规范注释类型时表现很好，代码量也少。但对自定义类型的支持有限，比如手写笔迹的粗细变化、笔锋效果、便签的样式皮肤，都没法完全控制。
自绘方案的灵活性就完全不同了。批注数据不写入PDF文件，而是维护在应用自己的数据层里，渲染时通过Canvas绘制在页面之上。这带来一个现象级的好处：批注完全独立于PDF内容，你可以随时修改颜色、透明度、笔迹粗细，甚至做像素级自由绘制。我最终的生产方案选择的就是“自绘为主、内置为辅”，内置能力只用来做导出时的兼容，应用内交互全部走自定义图层。
自绘方案的核心是一个“HitTest机制”——也就是命中检测。用户的手指落在屏幕某个点，我要判断这个点命中了哪个批注。做法是把批注的区域数据做一个空间索引，手势事件产生时，遍历索引得到候选批注，再近一步做精确判断。因为PDF页面可以缩放，命中检测时的坐标也要从屏幕坐标反算回页面坐标，统一使用归一化坐标计算就不容易出错。
4.3 批注持久化：保存、加载与版本兼容
批注数据存在内存里只是暂时的，产品经理一定会要求“用户退出后再次进来，批注还在”。这里我采用的是纯JSON格式做本地持久化，文件名关联PDF文件的哈希值，这样同一份文档的不同版本不会互串批注。
保存时要注意几个细节：大字段比如手写笔迹点序列，保存之前要做一次简化，把相邻且距离小于阈值的点合并，减小文件体积；坐标精度统一保留四位小数，避免精度不足导致位置漂移；如果有图片类型的批注，比如“贴图备注”，图片资源要单独保存文件，JSON里只存相对路径。
加载批注时最麻烦的是版本兼容问题。我在JSON结构里加了版本号字段，每次解析先检查版本号，对不同版本的数据做字段迁移。曾经有次上线后收到反馈说批注丢了，排查半天发现是旧版本把批注页码存成了字符串，新版本解析时用数值比较，直接全部过滤掉了。加了兼容层之后，这类问题基本没再出现过。
如果你打算支持“导出带批注的PDF”，就要把自定义批注数据转换为标准注释对象再写入文档。这一步我强烈建议用前面说的内置注释能力去生成，因为标准注释的格式约束比较多，手工拼接PDF内部结构非常容易把文件搞坏。我测试过转换链路，只要定位准确，导出的PDF在主流阅读器里都能正常打开，批注位置基本无偏移。
5. 常见问题与排查技巧实录
5.1 高频问题速查表
开发过程中我整理过一份问题速查表，这里挑最典型的几个，按“问题-原因-解法”的格式列出来，方便直接对照排查。
| 问题 | 常见原因 | 解决思路 |
|---|---|---|
| 文本提取为乱码 | 字体缺少编码映射表 | 做置信度检测，提示不支持复制，或引入OCR兜底 |
| 批注位置漂移 | 页面坐标未换算或未归一化存储 | 统一使用归一化坐标，渲染时再换算回屏幕坐标 |
| 渲染大页面白屏 | 内存不足或异步任务未同步完毕 | 完稿重试机制，把首帧渲染放到子线程，逐步提交Canvas绘制 |
| 翻页闪烁/延迟 | 页面缓存未命中或预加载范围过小 | 扩大到前后两页，缓存命中率明显提升 |
| 批注导出失败 | 自定义批注无法映射为标准注释类型 | 检查映射表，把不支持类型降级为“便签注释” |
| 图片提取内存暴涨 | 同时解码多张大图 | 串行解码，单张临时缓存，用完立即释放 |
排查问题时，我的建议是先把问题拆分到最小复现路径。比如“批注位置漂移”，就先测固定页面坐标转屏幕坐标的逻辑，再用单条批注验证保存后加载的坐标一致性。把复杂问题拆开测，很快就能定位到具体环节。
5.2 关于内存与性能的实战建议
PDF处理在移动端有一个天然的矛盾：文件解析需要占用内存，渲染位图也要占用内存，而应用的可用内存就那么大。我实际见过不少开发者一上来就加载整份文档，结果在低端设备上直接被系统杀进程。这里我强烈建议做“懒加载模型”：仅当用户翻到某一页时才真正解析该页的内容和资源，不要试图一次性解析全部页面。
我还养成了一个习惯：每次打开大型PDF、做翻页压测时，都手动观察内存曲线和线程占用。一旦发现某页解析有异常增长，就在代码里打印对应页面的对象数量，方便定位是图片缓存还是字体资源没释放。另外，ArkTS写起来虽然类似TS，但它在运行时对对象生命周期管理有自己的规则，避免在渲染循环里创建大量临时对象，能明显减轻内存抖动。
还有一点很多人忽略：Canvas的绘制频次。PDF页面绘制完成后，批注层的每次手势更新都会触发一层重绘。这时候可以开启“脏矩形”优化，只更新批注变化的区域，而不是整个页面重绘。实测下来，只需要刷新几十像素宽的小范围，CPU占用和延迟数据都会好看很多。
6. 再来聊聊：这套方案的扩展方向
PDF的完整能力不止文本、图片和批注，我之前做的那套框架还预留了几个扩展点，这里挑两个我认为价值最大的方向说说。
第一个是PDF大纲目录。解析文档的书签结构，构建左侧的层级目录列表，点击目录跳转到对应页面。实现逻辑上，还是走文档对象的大纲读取接口，把书签树转化为树形控件数据即可。做课件类产品时，这个功能几乎是刚需。
第二个是PDF表单填写。部分PDF文件是带表单的，比如申报表、问卷表，用户希望在App里直接输入内容再导出。表格字段的识别和填充同样可以通过解析表单字段对象来实现，虽然字段类型多（文本框、复选框、单选按钮），但只要对数据模型设计得当，还是可以全部覆盖。
我个人体会是，PDF功能在鸿蒙生态里远没有被充分挖掘，很多团队习惯用Web方案把一个阅读器塞进WebView里，体验上做不出桌面级产品的手感。如果你愿意把页面、文本、图片、批注这四条链路逐一吃透，你的App在文档处理这块会拉出一大截差距。最后提醒一句：开发过程中时刻关注官方组件版本和接口变更，因为PDF能力模块还在快速迭代中，尽早建立自己的抽象层，能让你在日后升级时不至于重写整个模块。
