Android PDF阅读器实现：渲染引擎选型与缓存优化

简介：Android DocumentViewer(PDF阅读器)源码.rar是一份面向Android开发者的完整PDF阅读器工程源码，适合需要在应用中集成PDF查看与处理能力的中高级开发者学习、改写与二次开发。资源共包含336个文件，压缩包大小5.36MB，种类涵盖40个Java源码、69个编译后的class文件、30个png界面资源、11个xml配置、2个可安装apk示例、so动态库、dex字节码及工程配置文件等，可直观看到项目从源码到构建产物的完整体系。已有252人学习下载。通过研读这份源码，可以重点理解PDF文档的加载解析、页面渲染成位图、滑动缩放交互、书签与注释管理、文本搜索、加密文件权限处理以及预加载与异步缓存等核心模块的实现思路，为自研PDF阅读器或优化现有功能提供现成参考。同时支持通过URI、文件路径与网络链接读取PDF，适合作为实战项目深入拆解。

1. 为什么 PDF 阅读器在 Android 上这么难做

接手过一个资料归档 App，里面要内置 PDF 阅读器。当时第一反应是 Android 已经这么成熟，直接调系统组件不就行了？结果踩了一整周的坑：系统 PDF 支持从 Android 5.0 才开始，而且PdfRenderer只能逐页渲染成 Bitmap，遇到 100M 以上的大 PDF 直接 OOM；第三方 SDK 倒是能渲染，但离线授权、页面批注、搜索高亮全要自己接。这套DocumentViewer(PDF阅读器)源码.rar就是当时从零梳理出来的一个完整工程，把PdfRenderer、MuPDF抽象在同一套接口后面，用 ViewPager 配合手势缩放来呈现文档。不管你是打算给自己的 App 内嵌一个 PDF 查看页，还是想搞清移动端文档渲染这一整套原理，这份源码都值得顺着拆一遍。下面我不会贴整页代码，而是把渲染选型、页面复用、缓存预算这几个关键决策点拿出来讲透，这样你自己写也能落得下去。

2. 渲染引擎选型：PdfRenderer、MuPDF 与 PDF.js 的取舍

2.1 Android 原生 PdfRenderer 的能力边界

Android 官方提供的PdfRenderer属于android.graphics.pdf包，API 21 起可用。它最大的特点是使用简单，直接绑定ParcelFileDescriptor，然后逐页创建Page对象，调用Page.render()可以拿到这一页的 Bitmap，放到ImageView或者Canvas上就能显示。这段代码能跑通最简单场景：

ParcelFileDescriptor fd = getContentResolver().openFileDescriptor(uri, "r"); PdfRenderer renderer = new PdfRenderer(fd); PdfRenderer.Page page = renderer.openPage(0); Bitmap bitmap = Bitmap.createBitmap(page.getWidth(), page.getHeight(), Bitmap.Config.ARGB_8888); page.render(bitmap, null, null, PdfRenderer.Page.RENDER_MODE_FOR_DISPLAY);

openPage的参数是页码索引，从 0 开始；render的第三个Rect参数如果传null表示渲染整页，否则只渲染指定区域。用法简单，但能力边界很明显：不支持 PDF 内的超链接跳转，不支持表单填写，对加密 PDF 只能检测是否被加密，却不提供解密入口。更麻烦的是内存开销巨大，默认按页原始尺寸渲染，一个 A4 页面解析出来的 Bitmap 在 300dpi 下可能是 8MB 到 20MB，翻几页就内存吃紧。官方其实也承认它适合做缩略图或简单预览，不是完整阅读器该依赖的方案。

2.2 第三方引擎对比：为什么项目里混用了 MuPDF

如果只做阅读器，行业里通常有三个方向：PDF.js、MuPDF、AndroidPdfViewer这类封装库。PDF.js本质是跑在 WebView 里的 JavaScript 渲染器，交互体验好，但包体要增重 1~2MB，而且离线加载 PDF 需要自己管理 js 资源，遇到超大 PDF 时 WebView 内存回收也不可控。AndroidPdfViewer是对PdfRenderer的封装，省了手势和适配的工作量，但加密和解析错误处理还是被系统库锁死。MuPDF是 Artifex 的 C 库，通过 JNI 暴露给 Java 层，支持加密 PDF、批注、文本抽取，渲染速度也比系统库快。所以这份源码的设计就很有意思：它在业务层定义一个阅读器接口，底层分别实现了SystemPdfEngine和MuPdfEngine，根据文件类型或加密状态自动切换。

这个表格基本能解释源码里为什么把MuPDF作为默认引擎：普通文档用 PDF 官方库足够，但一旦涉及密码和搜索，没有MuPDF就只能自己造轮子了。

2.3 从源码看引擎抽象层设计

我比较认可这张图对应的抽象方式——不直接new某个渲染器，而是定义一个最小接口：

public interface IDocumentEngine { IEnginePage openPage(int index); int getPageCount(); boolean isEncrypted(); boolean unlock(String password); void close(); }

DocumentViewer里所有业务逻辑都依赖IDocumentEngine，而不关心底层是系统PdfRenderer还是MuPDF。这样做的好处是，后续要加入 EPUB 或 XPS 支持，只需新增一个实现了该接口的引擎即可，ViewPager 滑页、缩放、缓存全部复用。这也解释了为什么源码里没有在 Activity 里堆一堆渲染逻辑，而是拆出了PDFLoader、PDFRenderer、DocumentViewPager这些独立类。实际开发中，你至少要把渲染入口和 UI 层解耦，不然引擎升级时会牵一发动全身。我会保持这样一个约定：所有引擎对象只在后台线程创建和打开，UI 线程只拿结果文件描述符或 Bitmap 的引用，避免 JNI 层崩溃直接拖垮主进程。

3. DocumentViewer 的页面渲染与滑动体系

3.1 用 RecyclerView 实现文档翻页

很多 PDF Demo 会用ViewPager2来做左右翻页，但这套源码里用的是RecyclerView配合PagerSnapHelper，原因是阅读器需要同时处理横向翻页和纵向连续滚动两种模式。ViewPager2虽然支持横向，但想切换成连续滚动还需要额外改LayoutManager。用RecyclerView加自定义LayoutManager反而可以在同一个容器里控制两种模式。核心适配器大致是这样的：

public class DocumentAdapter extends RecyclerView.Adapter<PageViewHolder> { private final IDocumentEngine engine; private final SparseArray<Bitmap> cache = new SparseArray<>(); @Override public void onBindViewHolder(PageViewHolder holder, int position) { Bitmap cached = cache.get(position); if (cached != null) { holder.image.setImageBitmap(cached); } else { loadPageAsync(position, holder); } } }

SparseArray是 Android 系统提供的稀疏数组，比HashMap更省内存，适合用页码整数做 key。注意这里没有直接用getItemCount返回Integer.MAX_VALUE，而是根据engine.getPageCount()取真实页码，保证滑动到最后一页不会白屏。如果打算自己实现，建议把页面的宽高比缓存进ViewHolder，因为onBindViewHolder触发时图片还没加载完，先给ImageView设置一个按原 PDF 页面比例计算的占位尺寸，能避免图片到位后布局跳动。

3.2 手势缩放：让缩放中心对齐手指

阅读器最影响体验的是双指缩放时要让指尖下的内容保持相对位置不变，而ImageView自带的scaleX/scaleY默认以中心为基准缩放，所以需要自定Matrix。源码里DocumentViewPager的缩放逻辑是这样的：

private void handleScale(float focusX, float focusY, float scaleFactor) { matrix.postScale(scaleFactor, scaleFactor, focusX, focusY); // 限制缩放范围，避免图片被缩放到边界之外 float currentScale = getMatrixScale(); if (currentScale < minScale) { matrix.postScale(minScale / currentScale, minScale / currentScale, focusX, focusY); } else if (currentScale > maxScale) { matrix.postScale(maxScale / currentScale, maxScale / currentScale, focusX, focusY); } imageView.setImageMatrix(matrix); }

postScale的三个参数分别是 x 轴缩放、y 轴缩放和缩放中心坐标，这里直接用focusX和focusY作为基准点，双指捏合时内容不会乱跑。需要额外处理的是当缩放比例超过maxScale之后，边界判定要用当前矩阵的平移量来限制，不能让空白区域占据屏幕。还有一个细节：双击缩放时GestureDetector的onDoubleTap事件回调拿到的是屏幕坐标，要把它转换成 PDF 页面坐标，再调用handleScale，否则双击放大后焦点会偏移。

3.3 异步渲染与页面缓存

渲染 PDF 页是耗时操作，不能放到 UI 线程执行。源码里用了一个单线程的ExecutorService，每个页面渲染任务顺序执行，避免了多线程同时调用MuPDF的 JNI 层导致崩溃。缓存方面，除了内存里的 Bitmap 缓存，还引入了LruCache限制总大小。计算缓存大小的常见做法是根据设备屏幕分辨率和可用内存预估：

int cacheSize = (int) (Runtime.getRuntime().maxMemory() / 8); LruCache<Integer, Bitmap> pageCache = new LruCache<Integer, Bitmap>(cacheSize) { @Override protected int sizeOf(Integer key, Bitmap value) { return value.getByteCount(); } };

这里的Runtime.getRuntime().maxMemory()是 App 能拿到的最大堆内存，一般 64MB 到 512MB 不等，取八分之一作为缓存池，既能覆盖用户连续翻阅十几个页面的场景，又不会挤压其他业务内存。需要注意的是getByteCount()在 API 12 之前是getRowBytes() * getHeight()，现在统一用前者。源码里还做了一个很实用的策略：滑动停止后只缓存当前页和左右两页，其他页的 Bitmap 直接回收，翻页时再重新渲染，这就是为了控制总内存。

4. 从源码到工程落地：集成 PDF 阅读器的完整步骤

4.1 导入源码与 Gradle 配置

这份.rar解压后是一个完整的 Android Studio 工程，结构大概是app/src/main/java/com/example/documentviewer/，下面有loader、render、widget、model四个包。直接Open工程后要先确认gradle.properties里的android.useAndroidX是true，因为源码里的DocumentViewPager依赖了androidx.viewpager.widget.ViewPager。app/build.gradle中需要关心的是最小版本号，因为代码里同时处理了PdfRenderer和MuPDF两套引擎，minSdkVersion应设为 21，低于这个版本的设备只能走MuPDF路径。依赖项大致如下：

implementation 'androidx.appcompat:appcompat:1.6.1' implementation 'androidx.recyclerview:recyclerview:1.3.2' implementation 'com.artifex.mupdf:mupdf:1.21.0'

MuPDF的依赖从 jcenter 迁移到 Maven Central 后，版本号要写完整。如果你在公司内网环境，还需要检查maven { url 'https://repo1.maven.org/maven2/' }是否能访问，否则可以把这个库改成本地 arr 依赖。我一般会再开multidexEnabled true，因为MuPDF的 native 库和老机型上的分包冲突不是没有可能。

4.2 打开 PDF：从 Uri 到 FileDescriptor

源码里提供了一个简单的文件选择器，核心逻辑在MainActivity中通过ACTION_OPEN_DOCUMENT打开 PDF，然后把返回的Uri交给PDFLoader。从Uri转为ParcelFileDescriptor是这一步的关键，我直接把关键代码抽出来：

private fun openPdf(uri: Uri) { try { val fd = contentResolver.openFileDescriptor(uri, "r") val engine = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) { SystemPdfEngine(fd) } else { MuPdfEngine(fd) } documentPager.setEngine(engine) } catch (e: Exception) { Log.e("DocumentViewer", "open failed", e) } }

这段代码要特别说明两个问题：contentResolver.openFileDescriptor得到的ParcelFileDescriptor属于调用进程，关闭时必须在finally中处理，否则会泄漏文件句柄。另一个问题是 Android 11 开始的分区存储策略，外部存储的file://路径已经无法直接访问，必须通过FileProvider或者ContentResolver获取Uri。如果是自己 App 的私有目录，直接把File转成Uri.fromFile()是可以的，但为了兼容第三方文件管理器，还是建议用FileProvider.getUriForFile()处理。

4.3 加密 PDF 的密码回调处理

遇到加密 PDF 时，SystemPdfEngine只能通过PdfRenderer判断是否加密，但没有解锁能力。源码在MuPdfEngine里实现了真正的密码解锁：先尝试空密码打开，如果抛异常则把错误码映射为PDF_NEED_PASSWORD，这时候 UI 层弹出一个密码输入框。密码输入后调用engine.unlock(password)，成功后再重新设置页面数据。这个过程还有一个边界情况：某些 PDF 的密码是空字符串，但设置了权限限制不允许打印或复制，此时MuPDF也能正常渲染，但PdfRenderer会直接返回安全错误。所以判断加密不能只看打开是否成功，还应该主动读取页面权限位。如果unlock失败，要立即关闭当前引擎并释放文件描述符，否则后续重试时PdfRenderer的全局单例会被旧实例占用。

5. 把页面缓存和预加载调到一个合理水位

5.1 用设备内存重新计算缓存池

上一章提到了LruCache的基本用法，但实际测试会发现maxMemory() / 8在一个 512MB 堆内存的手机上会给出 64MB，足够装下 8 张高清页面；而在 128MB 内存的低端机上只有 16MB，两页就满了。更合理的做法是结合 PDF 页面的实际渲染分辨率来动态调整。先把页面渲染宽度限制在屏幕宽度的 2 倍以内，降低单页 Bitmap 的大小，再根据这个大小重新分配缓存数量：

int screenWidth = resources.getDisplayMetrics().widthPixels; int renderWidth = Math.min(page.getWidth(), screenWidth * 2); int scaledHeight = (int) (page.getHeight() * (renderWidth / (float) page.getWidth())); Bitmap.Config config = Bitmap.Config.ARGB_8888; int singlePageSize = renderWidth * scaledHeight * 4; int pageCacheCount = Math.max(3, cacheSize / singlePageSize);

ARGB_8888每个像素占 4 字节，singlePageSize就是单个页面渲染后的内存占用。算出pageCacheCount之后，传给LruCache的sizeOf依然是value.getByteCount()，但初始化时把容量从固定字节数改为singlePageSize * pageCacheCount，这样就能保证至少缓存 3 页，同时不浪费内存。我习惯把渲染分辨率上限设为 2 倍屏宽，因为超过这个值在小屏幕上缩放显示时，肉眼已经区分不出清晰度差异，却会白白多占 4 倍内存。

5.2 预加载时机的具体落点

源码里关于预加载的控制点其实是在RecyclerView.OnScrollListener中。当onScrollStateChanged收到SCROLL_STATE_IDLE时，取当前页的前后两页开始异步渲染，其余页面全部从缓存中移除。如果用户快速连续滑动，这种延迟加载策略容易造成中间白屏，所以额外加了保护：onScrolled里如果判断当前滑动速度过快，则把预加载范围扩大到前后三页。你可以在自己的实现里这样判断：

@Override public void onScrolled(@NonNull RecyclerView recyclerView, int dx, int dy) { int currentPage = layoutManager.findFirstVisibleItemPosition(); preloadRange = Math.abs(dx) + Math.abs(dy) > threshold ? 3 : 2; for (int i = currentPage - preloadRange; i <= currentPage + preloadRange; i++) { loadPageIfNotCached(i); } }

这里的threshold我一般设成屏幕宽度的一半，用来区分用户是翻页还是滑动浏览。预加载任务不要一拥而上，最好在ExecutorService里用Future的cancel取消掉已经跳过的页面任务，防止用户从第 1 页快速拖到第 30 页时，中间 60 个渲染任务全部堆积在队列里。更稳的做法是维护一个ConcurrentHashMap<String, Boolean>记录正在渲染的页码，渲染开始前先检查该页是否已经标记完成，渲染结束后再更新缓存。做完这一步，大 PDF 的浏览体验基本能接近本地阅读器的水准。

本文还有配套的精品资源，点击获取