在鸿蒙（HarmonyOS）应用开发中，PDF 文档的渲染与展示是一项高频需求。鸿蒙生态提供了从“轻量级预览”到“深度编辑”的多套方案，开发者可根据具体业务场景（如只读展示、合同签署、文档编辑等）灵活选择。

一、 方案选型：三种主流渲染架构

1. Web 组件预览（轻量级）：适用于网络文档、应用沙箱文档或本地资源的快速预览。无需引入额外模块，支持丰富的预览参数配置（如缩放、页码跳转、工具栏控制）。
2. PDF Kit - PdfView 组件（应用内嵌入）：适用于需要在应用页面内深度集成 PDF 阅读、高亮搜索、批注等交互的场景。
3. Preview Kit（系统级预览）：适用于拉起系统独立窗口预览文件，界面统一，但不支持在应用内嵌入视图。

二、 实战代码：使用 Web 组件快速预览 PDF

Web 组件支持加载网络、沙箱及本地资源中的 PDF，并可配置初始显示参数（如指定页码、缩放比例、背景色等）。

核心代码示例：

import { webview } from '@kit.ArkWeb';

@Entry
@Component
struct WebPdfPreview {
  controller: webview.WebviewController = new webview.WebviewController();

  build() {
    Column() {
      Web({
        // 方式一：加载网络 PDF
        src: 'https://www.example.com/test.pdf#page=2&zoom=100', 
        // 方式二：加载本地沙箱文件（需开启 fileAccess）
        // src: this.getUIContext().getHostContext()!.filesDir + '/test.pdf',
        // 方式三：加载本地资源
        // src: $rawfile('test.pdf'),
        controller: this.controller
      })
        .domStorageAccess(true) // 开启 DOM 存储，支持侧边栏状态记忆
        .fileAccess(true)       // 若加载沙箱文件需开启
        .onPdfLoadEvent((eventInfo) => {
          // 监听加载成功/失败状态
          console.info(`PDF加载结果: ${eventInfo.result}`);
        })
    }
  }
}

三、 实战代码：使用 PDF Kit 实现应用内嵌入预览

对于需要深度定制阅读体验的场景，推荐使用 PdfView 组件配合 pdfViewManager 控制器。该方案支持实时显示编辑后的内容、页码监听及缩放控制。

核心代码示例：

import { pdfService, PdfView, pdfViewManager } from '@kit.PDFKit';
import { common } from '@kit.AbilityKit';

@Entry
@Component
struct AppPdfViewer {
  private controller: pdfViewManager.PdfController = new pdfViewManager.PdfController();
  private context = this.getUIContext().getHostContext() as common.UIAbilityContext;
  @State filePath: string = '';
  @State curPage: number = 0;

  aboutToAppear(): void {
    this.filePath = this.context.filesDir + '/test.pdf';
    // 异步加载文档
    (async () => {
      let loadResult = await this.controller.loadDocument(this.filePath);
      if (pdfService.ParseResult.PARSE_SUCCESS === loadResult) {
        this.controller.setPageZoom(1); // 设置初始缩放
        // 监听页码滑动
        this.controller.registerPageChangedListener((pageIndex: number) => {
          this.curPage = pageIndex;
        });
      }
    })();
  }

  build() {
    Column() {
      Text(`当前页码: ${this.curPage + 1}`)
      PdfView({ controller: this.controller }) // 嵌入 PdfView 组件
        .width('100%')
        .height('90%')
    }
  }
}

四、 进阶能力：PDF 编辑与实时刷新

PDF Kit 的 pdfService 提供了强大的编辑能力（如添加水印、背景、批注等）。注意： saveDocument 不支持直接覆盖正在被 PdfView 加载的文件，必须使用临时文件过渡。

核心代码示例：

// 在 PdfView 所在组件中添加编辑逻辑
async function addBackgroundAndRefresh() {
  // 1. 拷贝一份临时文件用于编辑
  let tempEditFilePath = this.context.tempDir + `/tempEdit_${Date.now()}.pdf`;
  fs.copyFileSync(this.filePath, tempEditFilePath);

  let pdfDocument = new pdfService.PdfDocument();
  let loadResult = pdfDocument.loadDocument(tempEditFilePath);

  if (loadResult === pdfService.ParseResult.PARSE_SUCCESS) {
    // 2. 添加背景色
    let bgInfo = new pdfService.BackgroundInfo();
    bgInfo.backgroundColor = 0xFFE0E0E0; // 示例颜色
    bgInfo.opacity = 0.3;
    pdfDocument.addBackground(bgInfo, 0, pdfDocument.getPageCount(), true, false);

    // 3. 保存到源文件
    pdfDocument.saveDocument(this.filePath);

    // 4. 释放旧文档并重新加载，实现实时刷新
    this.controller.releaseDocument();
    this.controller.loadDocument(this.filePath, '', this.curPage);
  }
}

1. 权限与路径规范：加载网络 PDF 需在 module.json5 中声明 ohos.permission.INTERNET 权限；加载沙箱文件需确保文件存在于应用沙箱路径下。
2. 内存管理：使用 pdfService.PdfDocument 手动加载文档时，务必在组件销毁（aboutToDisappear）时调用 releaseDocument() 释放资源，防止内存泄漏。
3. 大文件优化：对于几百页的超大 PDF，Web 组件和 PdfView 均内置了按需渲染机制，但应避免在加载回调中执行繁重的同步解析任务。
4. 功能边界：若仅需让用户“看一眼”文件内容且无需深度集成，优先考虑 Preview Kit 拉起系统预览窗口，可节省大量应用包体积与开发成本。

五、 进阶渲染：基于 PixelMap 的逐页精细控制

当业务需要实现类似“翻页动画”、“自定义手势缩放”或“将 PDF 页面作为图片进行二次加工”时，PdfView 组件可能不够灵活。此时应使用 pdfService 将指定页面渲染为 PixelMap（像素图），再交由 Image 组件展示。

核心代码示例：

import { pdfService } from '@kit.PDFKit';
import { image } from '@kit.ImageKit';

@State pixelMap: image.PixelMap | undefined = undefined;
private document: pdfService.PdfDocument = new pdfService.PdfDocument();

// 1. 加载文档并获取第一页的像素图
async function loadFirstPage(filePath: string) {
  this.document.loadDocument(filePath, '');
  let page: pdfService.PdfPage = this.document.getPage(0);
  this.pixelMap = page.getPagePixelMap();
}

// 2. 实现上一页/下一页的精细翻页
function goToNextPage() {
  let currentIndex = 0; // 假设当前页索引
  if (currentIndex + 1 >= this.document.getPageCount()) return;
  
  let nextPage: pdfService.PdfPage = this.document.getPage(currentIndex + 1);
  this.pixelMap = nextPage.getPagePixelMap();
}

// 3. 在 UI 中渲染
build() {
  Image(this.pixelMap).width('100%').height('100%')
}

六、 高级文档操作：元数据提取、页面管理与格式转换

对于企业级文档管理应用，除了预览，还需要对 PDF 进行深度解析与重组。pdfService 提供了完整的文档级操作 API。

核心代码示例：

// 1. 获取 PDF 元数据（作者、创建时间等）
let metadata = this.document.getMetadata();
console.info(`文档作者: ${metadata.author}, 创建时间: ${metadata.creationDate}`);

// 2. 页面重组：在指定位置插入空白页并删除第一页
this.document.insertBlankPage(1); // 在索引1处插入空白页
this.document.deletePage(0);      // 删除原第一页

// 3. 批量导出：将整个 PDF 转换为 PNG 图片集
let imageDir = this.context.cacheDir + '/pdf_images';
fileIo.mkdir(imageDir);
let result = this.document.convertToImage(imageDir, pdfService.ImageFormat.PNG);
if (result) {
  console.info('PDF 转图片成功');
}

七、 跨平台框架适配：Flutter 鸿蒙 PDF 渲染深度集成

对于使用 Flutter 构建鸿蒙应用的团队，由于 OHOS 的 ArkUI 框架与 Flutter 渲染引擎独立，PDF 渲染需要借助适配插件（如 pdf_render 或 flutter_pdfview）通过外接纹理（Texture）或原生桥接实现。

核心代码示例（Dart）：

import 'package:flutter_pdfview/flutter_pdfview.dart';

// 在 Flutter 页面中嵌入原生 PDF 视图
PDFView(
  filePath: localPdfPath,
  enableSwipe: true,           // 支持滑动翻页
  swipeHorizontal: false,      // 垂直滑动
  autoSpacing: true,           // 自动添加页间距
  fitPolicy: FitPolicy.WIDTH,  // 宽度自适应
  onRender: (_pages) {
    setState(() { pages = _pages; });
  },
  onPageChanged: (int? page, int? total) {
    print('当前页码: $page/$total');
  },
)

八、 性能与安全：大文件异步加载与沙箱隔离

在处理几百 MB 的工程图纸或高清扫描版 PDF 时，必须避免阻塞 UI 线程。同时，鸿蒙严格的沙箱机制要求所有外部 PDF 必须先复制到应用沙箱才能被加载。

核心代码示例：

// 1. 将外部文件安全复制到沙箱
async function copyToSandbox(srcPath: string): Promise<string> {
  let destPath = this.context.filesDir + '/temp_doc.pdf';
  fileIo.copyFileSync(srcPath, destPath);
  return destPath;
}

// 2. 在后台线程异步加载大文档，防止 UI 掉帧
(async () => {
  let sandboxPath = await copyToSandbox(externalFilePath);
  let loadResult = await this.controller.loadDocument(sandboxPath);
  if (loadResult === pdfService.ParseResult.PARSE_SUCCESS) {
    console.info('大文档加载完成，可安全渲染');
  }
})();

1. 内存泄漏防范：使用 PixelMap 渲染或 pdfService.PdfDocument 手动加载时，务必在组件销毁（aboutToDisappear）时调用 releaseDocument() 并释放 PixelMap 资源，防止内存溢出。
2. 跨平台渲染一致性：在 Flutter 或 Web 跨端项目中，不同平台的底层 PDF 渲染引擎（如 Android 的 Pdfium、iOS 的 CoreGraphics、鸿蒙的 PDF Kit）可能存在微小的排版差异。建议在 UI 层提供“适应宽度”、“适应高度”等用户可调选项以弥补差异。
3. 安全合规：对于包含敏感信息的合同或财务报表，在渲染前可利用 pdfService 的批注或水印功能，动态打上包含当前用户 ID 和时间戳的防伪水印。
4. 按需渲染（Lazy Rendering）：对于超长文档，切勿在初始化时一次性获取所有页面的 PixelMap。应结合 LazyForEach 或监听滚动事件，仅渲染当前可视区域及前后缓冲区的页面。