React Native Guides How to use compdfkit react native sdk with expo

如何在 Expo 中使用 ComPDF React Native SDK

本指南介绍如何在 Expo 项目中集成 @compdfkit_pdf_sdk/react_native。

ComPDFKit 依赖原生 iOS 和 Android 代码，因此不支持在 Expo Go 中运行。请改用 development build、expo run 或 EAS Build。

ComPDFKit 包内置的 Expo config plugin 会在执行 expo prebuild 时自动更新 iOS Podfile，因此不需要再手动修改 ios/Podfile 作为主流程。

开始之前

请先确保本地环境已具备原生 Expo 构建所需工具：

• Android Studio
• Xcode
• Expo CLI
• EAS CLI

创建 Expo 项目

执行以下命令：

npx create-expo-app compdfkit_expo
cd compdfkit_expo

然后安装项目依赖：

npm install
# or
yarn install

安装 ComPDFKit

执行：

yarn add @compdfkit_pdf_sdk/react_native

在 Expo 配置中添加插件

在 app.json 中添加 ComPDFKit 插件：

{
  "expo": {
    "plugins": ["@compdfkit_pdf_sdk/react_native"]
  }
}

同时，请确保项目配置了正确的 iOS bundleIdentifier 和 Android package。ComPDFKit 的许可证与这些标识符绑定。

如果你的 Expo 项目还需要配置 compileSdkVersion、minSdkVersion 或 deploymentTarget 等原生构建属性，可以额外安装并配置 expo-build-properties。它是可选项，并不是 ComPDFKit 插件运行所必需的。

生成原生项目

执行：

CI=1 npx expo prebuild --clean

该命令会生成 ios 和 android 目录，并应用 ComPDFKit 插件。

验证 iOS 插件是否已生效

prebuild 完成后，打开 ios/Podfile。

在 use_expo_modules! 下方，你应该能看到类似下面的自动生成片段：

# @generated begin compdfkit-react-native-ios-pods
pod 'ComPDFKit', :podspec => 'https://file.compdf.com/cocoapods/ios/compdfkit_pdf_sdk/3.0.1/ComPDFKit.podspec'
pod 'ComPDFKit_Tools', :podspec => 'https://file.compdf.com/cocoapods/ios/compdfkit_pdf_sdk/3.0.1/ComPDFKit_Tools.podspec'
# @generated end compdfkit-react-native-ios-pods

如果存在这段内容，说明插件已正常生效，不需要再手动修改 Podfile。

配置 EAS 云构建

执行：

eas build:configure

如果 Expo 提示你登录，请先完成登录。

当你选择 All 后，Expo 会生成一个类似下面的 eas.json 文件：

{
  "cli": {
    "version": ">= 5.4.0"
  },
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal"
    },
    "preview": {
      "distribution": "internal"
    },
    "production": {}
  },
  "submit": {
    "production": {}
  }
}

添加 Android 权限

当前阶段，ComPDFKit 的 Expo 插件只处理 iOS Podfile 注入。Android 权限仍需要在 prebuild 之后手动添加。

打开 android/app/src/main/AndroidManifest.xml，添加以下权限和配置：

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE"/>

<application
    android:requestLegacyExternalStorage="true"
    ...>
</application>

添加用于测试的 PDF

本示例使用原生打包资源路径。请在执行 prebuild 后，将名为 PDF_Document.pdf 的测试文件复制到以下位置：

1. android/app/src/main/assets/PDF_Document.pdf
2. iOS 工程对应的 App Target 中，确保文件会被打包进应用

如果你后续再次执行 expo prebuild --clean，请重新确认该 PDF 文件是否需要重新复制到生成后的原生工程中。

替换应用代码

将 index.tsx 的内容替换为以下示例：

import { Platform, SafeAreaView } from 'react-native';
import { Component } from 'react';
import { ComPDFKit, CPDFReaderView } from '@compdfkit_pdf_sdk/react_native';

const androidLicense = 'android license';
const iosLicense = 'ios license';

type Props = {};

export default class HomeScreen extends Component<Props> {
  constructor(props: Props) {
    super(props);
    this.initialize();
  }

  async initialize() {
    const result = await ComPDFKit.init_(
      Platform.OS === 'android' ? androidLicense : iosLicense
    );
    console.log('ComPDFKitRN', 'init_:', result);
  }

  samplePDF =
    Platform.OS === 'android'
      ? 'file:///android_asset/PDF_Document.pdf'
      : 'PDF_Document.pdf';

  render() {
    return (
      <SafeAreaView style={{ flex: 1 }}>
        <CPDFReaderView
          document={this.samplePDF}
          configuration={ComPDFKit.getDefaultConfig({})}
          style={{ flex: 1 }}
        />
      </SafeAreaView>
    );
  }
}

在运行应用之前，请将 androidLicense 和 iosLicense 替换为你自己的 ComPDFKit 许可证字符串。

ComPDF React Native SDK 的试用许可证可在 GitHub 示例项目 中获取，或请直接联系销售团队。

运行应用

执行：

npx expo run:android

或者：

npx expo run:ios

使用 EAS 构建

执行：

eas build --platform ios

或者：

eas build --platform android

当你希望由 Expo 在云端根据 app.json 中定义的同一套插件配置完成原生构建时，可以使用这些命令。

常见问题

Expo Go 无法打开 SDK

这是预期行为。ComPDFKit 依赖原生模块，请使用 development build、expo run 或 EAS Build。

生成的 Podfile 中没有 ComPDFKit 依赖

请先确认 @compdfkit_pdf_sdk/react_native 已出现在 expo.plugins 中，然后重新执行：

CI=1 npx expo prebuild --clean

prebuild 后示例 PDF 丢失

执行 expo prebuild --clean 时，Expo 会重新生成原生工程。请将测试 PDF 重新复制到新生成的原生目录中。

支持

• 查看 React Native 指南总览
• 查看 React Native 更新日志
• 如果遇到技术问题，请联系技术支持
• 如果涉及授权与商务问题，请联系销售团队