从零掌握React Native PDF开发：纯JS实现移动端PDF处理全攻略

2026-05-03 10:22:36作者：农烁颖Land

在移动应用开发中，PDF处理功能常常成为技术瓶颈——原生模块集成复杂、跨平台兼容性差、性能优化困难。本文将带你使用pdf-lib库，以纯JavaScript方式在React Native应用中实现PDF创建、编辑和展示功能，无需原生开发经验，轻松搞定移动端PDF处理全流程。

🌱 问题定位：移动端PDF处理的痛点与解决方案

移动端PDF处理一直是React Native开发中的棘手问题。传统方案主要依赖原生模块或第三方SDK，这些方案普遍存在集成复杂、体积庞大、维护成本高等问题。

主流方案对比分析

方案	实现方式	优势	劣势	适用场景
原生模块	基于Android/iOS平台的原生代码	性能优异，功能全面	开发成本高，需维护两套代码	高性能要求的专业PDF应用
WebView + PDF.js	网页技术渲染PDF	跨平台一致性好	交互体验差，性能受限	简单PDF预览场景
pdf-lib纯JS方案	纯JavaScript实现	轻量灵活，无需原生开发	复杂操作性能略低	中小型应用的PDF处理需求

pdf-lib作为纯JavaScript库，通过在JS层面实现PDF的解析与生成，完美解决了跨平台一致性问题，同时大幅降低了开发门槛。项目中的React Native示例应用已集成pdf-lib，代码位于apps/rn/目录下。

🔧 环境搭建：从零配置React Native PDF开发环境

要开始使用pdf-lib开发React Native PDF功能，需要先完成基础环境配置。

项目初始化与依赖安装

首先克隆项目仓库：

git clone https://gitcode.com/gh_mirrors/pd/pdf-lib
cd pdf-lib/apps/rn
yarn install

核心依赖已在package.json中配置：

{
  "dependencies": {
    "pdf-lib": "./../..",           // PDF处理核心库
    "react-native-pdf": "^6.1.1",   // PDF渲染组件
    "rn-fetch-blob": "0.10.15"      // 文件系统操作
  }
}

项目结构解析

React Native示例应用的主要结构：

apps/rn/
├── src/                 # 源代码目录
│   ├── components/      # React组件
│   │   ├── App.js       # 应用入口组件
│   │   ├── TestLauncher.js  # 测试启动组件
│   │   └── PDFViewer.js  # PDF预览组件
│   └── tests/           # PDF测试代码
├── index.js             # 应用入口文件
└── package.json         # 项目配置

入口文件index.js注册了主组件：

import { AppRegistry } from 'react-native';
import App from './src/components/App';
import { name as appName } from './app.json';

// 核心逻辑：注册应用主组件
AppRegistry.registerComponent(appName, () => App);

🚀 核心功能实现：React Native PDF生成与编辑全解析

创建基础PDF文档

使用pdf-lib创建PDF文档的基本流程包括初始化文档、添加页面和内容、保存输出三个步骤：

import { PDFDocument, StandardFonts, rgb } from 'pdf-lib';

async function createBasicPDF() {
  // 1. 创建新的PDF文档实例
  const pdfDoc = await PDFDocument.create();
  
  // 2. 设置文档元数据
  pdfDoc.setTitle('React Native PDF示例');
  pdfDoc.setAuthor('pdf-lib库');
  pdfDoc.setSubject('基础PDF创建示例');
  
  // 3. 添加页面（宽度550，高度800）
  const page = pdfDoc.addPage([550, 800]);
  
  // 4. 嵌入标准字体
  const helveticaFont = await pdfDoc.embedFont(StandardFonts.Helvetica);
  
  // 5. 绘制标题文本
  page.drawText('React Native PDF开发指南', {
    x: 50,          // 文本X坐标
    y: 750,         // 文本Y坐标（PDF坐标系原点在左下角）
    font: helveticaFont,  // 使用的字体
    size: 24,       // 字体大小
    color: rgb(0, 0, 0.8), // 字体颜色（蓝色）
  });
  
  // 6. 保存为Base64格式（Base64编码是一种二进制数据转文本格式的编码方式）
  const base64Pdf = await pdfDoc.saveAsBase64({ dataUri: true });
  
  return base64Pdf;
}

实践贴士：设置页面大小时，可参考常见纸张尺寸：A4(595, 842)、信纸(612, 792)、A5(420, 595)。

高级内容添加：文本、图片与图形

文本布局与格式化

pdf-lib提供了丰富的文本绘制选项，支持多行文本、自定义字体和文本样式：

// 绘制带样式的多行文本
const paragraphText = `pdf-lib是一个强大的JavaScript库，允许你在任何JavaScript环境中创建和修改PDF文档。
它完全用TypeScript编写，没有任何原生依赖，非常适合React Native项目。`;

page.drawText(paragraphText, {
  x: 50,
  y: 700,
  font: helveticaFont,
  size: 14,
  lineHeight: 20,  // 行高
  maxWidth: 450,   // 最大宽度，超过自动换行
});

图片嵌入与处理

pdf-lib支持嵌入JPG和PNG图片，包括带有透明度的图片：

// 从应用资产加载图片
import { fetchAsset } from './assets';

async function embedImages(pdfDoc, page) {
  // 嵌入JPG图片
  const catImageBytes = await fetchAsset('images/cat_riding_unicorn_resized.jpg');
  const catImage = await pdfDoc.embedJpg(catImageBytes);
  
  // 计算图片尺寸（保持原始比例缩放50%）
  const catDims = catImage.scale(0.5);
  
  // 绘制图片
  page.drawImage(catImage, {
    x: 50,
    y: 450,
    width: catDims.width,
    height: catDims.height,
  });
  
  // 嵌入带透明度的PNG图片
  const minionBytes = await fetchAsset('images/minions_banana_alpha.png');
  const minionImage = await pdfDoc.embedPng(minionBytes);
  
  // 绘制带旋转和透明度的图片
  page.drawImage(minionImage, {
    x: 320,
    y: 500,
    width: minionImage.width * 0.4,
    height: minionImage.height * 0.4,
    rotate: degrees(15),  // 旋转15度
    opacity: 0.9,         // 透明度90%
  });
}

实践贴士：移动设备内存有限，建议嵌入图片前先调整尺寸。项目中提供了已优化的图片资源，如cat_riding_unicorn_resized.jpg就是原始图片的50%缩放版本。

图形绘制与路径操作

pdf-lib提供了绘制基本图形的API，可用于创建各种形状和装饰元素：

// 绘制矩形
page.drawRectangle({
  x: 50,
  y: 350,
  width: 450,
  height: 80,
  color: rgb(0.95, 0.95, 0.95),  // 背景色
  borderWidth: 1,                // 边框宽度
  borderColor: rgb(0.5, 0.5, 0.5), // 边框颜色
});

// 绘制圆形
page.drawCircle({
  x: 100,
  y: 300,
  size: 30,
  color: rgb(1, 0.5, 0), // 橙色
});

// 绘制线条
page.drawLine({
  start: { x: 50, y: 250 },
  end: { x: 500, y: 250 },
  thickness: 2,
  color: rgb(0, 0.5, 1),  // 蓝色
  dashArray: [10, 5],     // 虚线样式
});

移动端PDF编辑：表单创建与交互

pdf-lib支持创建各种交互式表单字段，使PDF具备数据收集功能。

// 创建交互式表单
async function createInteractiveForm(pdfDoc, page, font) {
  // 获取表单实例
  const form = pdfDoc.getForm();
  
  // 创建文本字段
  const nameField = form.createTextField('full_name');
  nameField.setText('请输入您的姓名');
  nameField.addToPage(page, {
    x: 50,
    y: 180,
    width: 200,
    height: 30,
    borderWidth: 1,
    backgroundColor: rgb(1, 1, 1), // 白色背景
  });
  
  // 在文本框旁添加标签
  page.drawText('姓名:', {
    x: 50,
    y: 215,
    font: font,
    size: 12,
  });
  
  // 创建复选框
  const agreeCheckbox = form.createCheckBox('agree_terms');
  agreeCheckbox.addToPage(page, {
    x: 50,
    y: 140,
    width: 20,
    height: 20,
  });
  
  // 在复选框旁添加文本
  page.drawText('我同意隐私政策', {
    x: 80,
    y: 142,
    font: font,
    size: 12,
  });
}

💻 实战案例：完整React Native PDF生成与预览流程

下面我们将整合前面介绍的功能，实现一个完整的PDF创建与预览组件。

PDF创建与预览组件

import React, { useState } from 'react';
import { View, Button, ActivityIndicator, Alert } from 'react-native';
import PdfView from 'react-native-pdf';
import { PDFDocument, StandardFonts, rgb, degrees } from 'pdf-lib';
import { fetchAsset } from '../utils/assets';

const PDFCreator = () => {
  const [pdfData, setPdfData] = useState(null);
  const [isCreating, setIsCreating] = useState(false);

  // 核心逻辑：创建PDF并预览
  const createAndDisplayPdf = async () => {
    setIsCreating(true);
    try {
      // 1. 创建PDF文档
      const pdfDoc = await PDFDocument.create();
      
      // 2. 嵌入字体
      const font = await pdfDoc.embedFont(StandardFonts.Helvetica);
      
      // 3. 添加页面
      const page = pdfDoc.addPage([550, 800]);
      
      // 4. 添加内容
      page.drawText('React Native PDF示例文档', {
        x: 50,
        y: 750,
        font,
        size: 24,
        color: rgb(0, 0, 0.8),
      });
      
      // 添加图片
      const birdBytes = await fetchAsset('images/greyscale_bird.png');
      const birdImage = await pdfDoc.embedPng(birdBytes);
      const birdDims = birdImage.scale(0.7);
      
      page.drawImage(birdImage, {
        x: 50,
        y: 500,
        width: birdDims.width,
        height: birdDims.height,
      });
      
      // 添加表单
      const form = pdfDoc.getForm();
      const emailField = form.createTextField('email');
      emailField.addToPage(page, {
        x: 50,
        y: 450,
        width: 200,
        height: 30,
      });
      
      // 5. 保存为base64格式
      const base64Pdf = await pdfDoc.saveAsBase64({ dataUri: true });
      setPdfData(base64Pdf);
      
    } catch (error) {
      console.error('创建PDF失败:', error);
      Alert.alert('错误', 'PDF创建失败: ' + error.message);
    } finally {
      setIsCreating(false);
    }
  };

  // 加载状态显示
  if (isCreating) {
    return (
      <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
        <ActivityIndicator size="large" />
      </View>
    );
  }

  return (
    <View style={{ flex: 1 }}>
      {!pdfData ? (
        <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
          <Button title="创建PDF文档" onPress={createAndDisplayPdf} />
        </View>
      ) : (
        <PdfView
          source={{ uri: pdfData }}
          style={{ flex: 1 }}
          onLoadComplete={(numberOfPages) => {
            console.log(`PDF加载完成，共${numberOfPages}页`);
          }}
          onError={(error) => {
            console.log('PDF加载错误:', error);
            Alert.alert('错误', 'PDF加载失败');
          }}
        />
      )}
    </View>
  );
};

export default PDFCreator;

🔍 常见问题诊断：React Native PDF开发排坑指南

图片嵌入失败问题

症状：PDF中图片不显示或显示为空白

可能原因：

图片路径错误
图片格式不受支持
内存不足导致图片处理失败

解决方案：

// 改进的图片加载函数，增加错误处理
async function safeEmbedImage(pdfDoc, assetPath, type = 'png') {
  try {
    const imageBytes = await fetchAsset(assetPath);
    
    // 检查文件大小，过大的图片可能导致处理失败
    if (imageBytes.length > 5 * 1024 * 1024) { // 5MB
      throw new Error('图片文件过大，请使用压缩版本');
    }
    
    if (type === 'png') {
      return await pdfDoc.embedPng(imageBytes);
    } else {
      return await pdfDoc.embedJpg(imageBytes);
    }
  } catch (error) {
    console.error(`嵌入图片失败: ${assetPath}`, error);
    // 返回null或占位图片
    return null;
  }
}

PDF生成性能问题

症状：创建大型PDF时应用卡顿或崩溃

优化方案：

分批次处理页面
使用字体子集化
优化图片尺寸和质量

// 字体子集化示例 - 只嵌入文档中使用的字符
const customFontBytes = await fetchAsset('fonts/ubuntu/Ubuntu-R.ttf');
const customFont = await pdfDoc.embedFont(customFontBytes, { 
  subset: true, // 启用子集化
  unicode: true 
});

🌍 跨平台兼容性处理：iOS与Android平台差异适配

React Native应用需要考虑iOS和Android平台的差异，PDF处理也不例外。

文件系统路径差异

iOS和Android的文件系统结构不同，需要使用rn-fetch-blob提供的路径API：

import RNFetchBlob from 'rn-fetch-blob';

// 获取平台特定的文档目录
function getDocumentDir() {
  const { DocumentDir } = RNFetchBlob.fs.dirs;
  return DocumentDir;
}

// 保存PDF到文件系统
async function savePdfToFile(base64Pdf, fileName) {
  try {
    const pdfPath = `${getDocumentDir()}/${fileName}.pdf`;
    
    // Base64解码并保存
    await RNFetchBlob.fs.writeFile(
      pdfPath, 
      base64Pdf.replace('data:application/pdf;base64,', ''), 
      'base64'
    );
    
    return pdfPath;
  } catch (error) {
    console.error('保存PDF失败:', error);
    return null;
  }
}

平台特定渲染差异

Android和iOS对PDF的渲染存在细微差异，特别是在字体和图形渲染方面：

// 平台特定的字体调整
import { Platform } from 'react-native';

function getFontSize(size) {
  // Android上字体显示通常比iOS小，需要适当调整
  return Platform.OS === 'android' ? size * 1.1 : size;
}