更新记录

1.0.0（2026-06-23）

1.0.0 IOS PDFKit（Apple 官方框架，iOS 11+，零依赖，最稳定，开箱即用的 PDFView） 鸿蒙 使用官方自带的PdfView组件 Android 使用第三方pdf包：android-pdf-viewer

平台兼容性

uni-app x(5.0)

ff-uni-pdf-view

PDF 预览组件 - 支持 Android、iOS、Harmony 平台的原生 PDF 查看器。

平台支持

安装

将 ff-uni-pdf-view 目录放置到项目的 uni_modules 目录下即可。

依赖要求：

• HBuilderX >= 4.0
• uni-app x >= 5.0

使用方法

基础用法

<template>
  <view class="container">
    <ff-uni-pdf-view
      id="pdfView"
      :src="pdfSrc"
      :page="currentPage"
      @load="onPdfLoad"
      @error="onPdfError"
      @pageChange="onPageChange"
      style="flex: 1;"
    />
  </view>
</template>

<script setup lang="uts">
  import { createPdfViewContext } from '@/uni_modules/ff-uni-pdf-view'

  const pdfSrc = ref<string>('https://example.com/sample.pdf')
  const currentPage = ref<number>(1)
  const pageCount = ref<number>(0)
  const pdfContext = ref<IPdfViewContext | null>(null)

  // PDF 加载完成
  function onPdfLoad(detail: UTSJSONObject) {
    pageCount.value = detail['pageCount'] as number
    pdfContext.value = createPdfViewContext('pdfView')
  }

  // 加载失败
  function onPdfError(detail: UTSJSONObject) {
    console.log('PDF 加载失败:', detail['errCode'], detail['errMsg'])
  }

  // 翻页
  function onPageChange(detail: UTSJSONObject) {
    currentPage.value = detail['page'] as number
  }

  // 跳转到指定页
  function goToPage(page: number) {
    pdfContext.value?.setPage(page)
    currentPage.value = page
  }
</script>

<style>
  .container {
    flex: 1;
  }
</style>

本地文件加载

<ff-uni-pdf-view
  src="/static/document.pdf"
  :page="1"
  @load="onLoad"
/>

网络文件加载

<ff-uni-pdf-view
  src="https://example.com/report.pdf"
  :page="1"
  @load="onLoad"
  @error="onError"
/>

API

Props

Events

命令式 API

通过 createPdfViewContext 获取组件上下文对象：

import { createPdfViewContext, IPdfViewContext } from '@/uni_modules/ff-uni-pdf-view'

const pdfContext = createPdfViewContext('pdfView') as IPdfViewContext

IPdfViewContext 方法：

错误码

平台差异说明

Android

• 依赖库：android-pdf-viewer 3.2.0-beta.3
• minSdkVersion：21（Android 5.0+）
• 特性：支持手势缩放、双击放大、平滑滚动

iOS

• 依赖框架：PDFKit.framework（Apple 官方）
• 最低版本：iOS 12+
• 特性：零依赖，最稳定，开箱即用

Harmony

• 依赖：PDFKit（鸿蒙官方 @kit.PDFKit）
• API：pdfViewManager.PdfController + PdfView 组件
• 限制：
  • loadDocument 不支持重复调用，二次加载前必须先 releaseDocument
  • 页码为 0-based（内部转换）

注意事项

1. src 变化会触发重新加载：当 src 属性变化时，组件会自动重新加载 PDF
2. page 变化仅跳页：当 page 属性变化时，只执行跳页操作，不会触发 pageChange 事件
3. 网络文件自动下载：鸿蒙平台会先下载网络 PDF 到沙箱临时目录再加载
4. 内存管理：组件销毁时会自动释放原生资源，避免内存泄漏

权限声明

• Android：需要 android.permission.INTERNET 权限（用于下载网络 PDF）

版本历史

1.0.0（2026-06-23）

• iOS：使用 PDFKit（Apple 官方框架）
• Harmony：使用官方 PdfView 组件
• Android：使用 android-pdf-viewer 第三方库
• 支持本地文件和网络 URL 加载
• 支持页码跳转和翻页事件