鸿蒙学习实战之路-PDF Kit 全攻略

最近好多朋友问我：“西兰花啊，我想在鸿蒙应用里搞个 PDF 功能，可这官方文档看的我头大，到底该用哪个组件啊？” 害，这问题可问对人了！今天这篇，我就手把手带你搞定鸿蒙 PDF 开发，从基础使用到进阶功能，全程不绕弯子～

PDF Kit 是什么？

PDF Kit（PDF 服务）是鸿蒙提供的 PDF 处理工具包，主要包含两员大将：

• pdfService：负责 PDF 文档的核心操作，比如加载保存、添加内容、修改格式等
• PdfView：负责 PDF 文档的展示预览，比如查看、搜索、批注等

简单来说，pdfService 是"后厨"（负责制作和修改 PDF），PdfView 是"前厅"（负责展示 PDF 给用户看）。

pdfService vs PdfView 能力对比

咱们先搞清楚这哥俩到底能干嘛，别用错了地方！

PDF Kit 能力	pdfService 是否支持	PdfView 预览组件是否支持
打开和保存文档	支持	支持
释放文档	支持	支持
PDF 文档转图片	支持	支持
添加、删除批注	支持	支持
管理书签	支持	不支持
添加、编辑、删除 PDF 页	支持	不支持
添加、删除文本内容	支持	不支持
添加、删除图片内容	支持	不支持
编辑页眉页脚、水印、背景	支持	不支持
判断 PDF 文档是否加密	支持	不支持
删除文档加密	支持	不支持
PDF 文档预览	不支持	支持
搜索关键字	不支持	支持
PDF 文档监听回调	不支持	支持

快速上手 PDF 预览功能

说了这么多，咱们先整个简单的 PDF 预览功能，热热身！

步骤 1：添加依赖

首先，在你的项目配置文件里添加 PDF Kit 依赖：

"dependencies": {
  "@ohos/pdf": "^1.0.0"
}

步骤 2：创建 PdfView 组件

接下来，在你的页面中添加 PdfView 组件：

import { PdfView } from '@ohos/pdf';

@Entry
@Component
struct PdfPreviewPage {
  private pdfController: PdfView.Controller = new PdfView.Controller();

  build() {
    Column() {
      Text("PDF预览示例").fontSize(20).fontWeight(FontWeight.Bold).margin(20);

      PdfView({
        file: "resources/rawfile/sample.pdf",
        controller: this.pdfController
      })
      .width('100%')
      .height('80%')
      .backgroundColor('#f5f5f5')
      .onLoad(() => {
        console.log("PDF加载成功");
      })
      .onError((error) => {
        console.error("PDF加载失败: " + error.message);
      })
    }
  }
}

步骤 3：添加基本操作按钮

咱们再给用户加几个常用操作按钮：

// 在PdfView组件后面添加
Row({
  space: 20
})
.margin(20)
.width('100%')
.justifyContent(FlexAlign.Center) {
  Button("上一页")
    .onClick(() => {
      this.pdfController.previousPage();
    })

  Button("下一页")
    .onClick(() => {
      this.pdfController.nextPage();
    })

  Button("放大")
    .onClick(() => {
      this.pdfController.zoomIn();
    })

  Button("缩小")
    .onClick(() => {
      this.pdfController.zoomOut();
    })
}

使用 pdfService 编辑 PDF

如果需要对 PDF 进行编辑，咱们就得请出 pdfService 了！

示例：给 PDF 添加水印

import { pdfService } from "@ohos/pdf";

async function addWatermarkToPdf() {
  try {
    // 打开PDF文档
    const pdfDoc = await pdfService.open("internal://cache/source.pdf");

    // 获取文档页数
    const pageCount = await pdfDoc.getPageCount();

    // 遍历每页添加水印
    for (let i = 0; i < pageCount; i++) {
      const page = await pdfDoc.getPage(i);

      // 添加水印文本
      await page.addText({
        text: "机密文档",
        x: 100,
        y: 200,
        fontSize: 48,
        color: "#ff000088", // 半透明红色
        rotate: 45, // 旋转45度
      });

      await page.close();
    }

    // 保存修改后的PDF
    await pdfDoc.save("internal://cache/result.pdf");
    await pdfDoc.close();

    console.log("水印添加成功");
  } catch (error) {
    console.error("添加水印失败: " + error.message);
  }
}

🥦 西兰花警告

• 权限问题：操作 PDF 文件时，记得申请文件访问权限，不然会直接报错！
• 内存管理：使用 pdfService 时，打开的文档和页面一定要记得关闭，不然会内存泄漏！
• 文件路径：PDF 文件路径要使用鸿蒙支持的协议（internal://、resources://等），别直接写本地路径！

🥦 西兰花小贴士

• PDF 转图片：如果只需要展示 PDF 的某一页，可以用pdfService的转图片功能，性能更好
• 批注功能：PdfView 支持添加文本批注、高亮批注等，适合做文档阅读应用
• 加密处理：如果需要处理加密 PDF，可以用pdfService的加密判断和删除加密功能

约束与限制

• 地区限制：当前 PDF Kit 仅支持中国境内（香港、澳门、台湾除外）
• 设备支持：支持 Phone、Tablet 和 PC/2in1 设备
• 模拟器差异：模拟器可以开发，但与真机存在部分能力差异，建议最终测试用真机

示例代码

PDF Kit 更多的示例代码请参考：

• CodeLab
• SampleCode

---

📚 推荐资料

• PDF Kit 官方文档
• pdfService 能力文档
• PdfView 组件文档

我是盐焗西兰花，
不教理论，只给你能跑的代码和避坑指南。
下期见！🥦