【HarmonyOS】Web 组件的 PDF 文档预览功能详解

【HarmonyOS】Web 组件的 PDF 文档预览功能详解

一、前言

应用开发中，PDF 文档预览是一项常见需求。虽然官方提供了预览组件，但是在H5业务场景下，如何加载PDF呢？

此时就需要Web 组件提供了便捷的 PDF 预览能力。目前官方的ArkWeb，支持加载网络、应用沙箱内、本地资源等多种来源的 PDF 文档。

本文将详细介绍如何使用 Web 组件实现 PDF 预览功能，包括不同场景下的加载方法、配置要点及动态切换技巧，帮助开发者快速集成 PDF 预览功能到自己的应用中。

二、使用步骤

1. 基础配置 使用 Web 组件预览 PDF 需要注意以下基础配置： 开启 DOM 存储权限：由于 PDF 预览页面会使用window.localStorage记录侧导航栏状态，必须设置domStorageAccess(true) 网络访问权限：若需加载网络 PDF，需在module.json5中配置互联网权限

"requestPermissions":[
  {
    "name" : "ohos.permission.INTERNET"
  }
]

2. 加载不同来源的 PDF 文档 场景一：预览网络 PDF 文档 直接通过网络 URL 加载，无需额外权限（已配置互联网权限前提下）：

Web({ 
  src: "https://www.example.com/test.pdf",
  controller: this.controller 
})
  .domStorageAccess(true)

场景二：预览应用沙箱内 PDF 文档 需要开启文件系统访问权限，使用应用沙箱路径加载：

Web({ 
  src: this.getUIContext().getHostContext()!.filesDir + "/test.pdf",
  controller: this.controller 
})
  .domStorageAccess(true)
  .fileAccess(true)  // 必须开启文件访问权限

场景三：预览本地资源 PDF 文档 支持两种本地资源路径格式，无需额外权限：

// 格式一：使用resource协议
Web({ 
  src: "resource://rawfile/test.pdf",
  controller: this.controller 
})
  .domStorageAccess(true)

// 格式二：使用$rawfile语法
Web({ 
  src: $rawfile('test.pdf'),
  controller: this.controller 
})
  .domStorageAccess(true)

3. 动态切换 PDF 文档 Web 组件的src参数无法通过状态变量动态更改，需使用loadUrl()方法实现动态切换：

// 切换到新的PDF文档
this.controller.loadUrl("https://www.example.com/new.pdf");

// 切换到沙箱内其他文档
this.controller.loadUrl(this.getUIContext().getHostContext()!.filesDir + "/new.pdf");

4. PDF 预览参数配置 可通过 URL 参数控制 PDF 初始显示状态，常用参数如下：

参数格式	描述
page=pagenum	指定初始页码（从 1 开始）
zoom=scale	设置缩放比例
toolbar=0	隐藏顶部工具栏
navpanes=0	隐藏侧边导航窗格
pdfbackgroundcolor=ffffff	设置背景色（十六进制 RGB，取值范围为 000000~ffffff）

示例：

// 加载第3页并设置50%缩放
this.controller.loadUrl("https://www.example.com/test.pdf#page=3&zoom=50");

// 隐藏工具栏和导航窗格
this.controller.loadUrl("resource://rawfile/test.pdf#toolbar=0&navpanes=0");

三、DEMO 源码

以下是完整的 PDF 预览示例代码，包含多种加载方式：

示例实现了 PDF 预览的完整功能，包括多种来源加载、动态切换和参数控制。开发者可根据实际需求选择合适的加载方式，并通过参数配置优化用户体验。

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

@Entry
@Component
struct PDFPreviewDemo {
  controller: webview.WebviewController = new webview.WebviewController();
  @State currentPdfType: string = "network";

  build() {
    Column() {
      Row({ space: 10 }) {
        Button("加载网络PDF")
          .onClick(() => {
            this.controller.loadUrl("https://www.example.com/test.pdf");
          })
        
        Button("加载沙箱PDF")
          .onClick(() => {
            this.controller.loadUrl(this.getUIContext().getHostContext()!.filesDir + "/test.pdf");
          })
        
        Button("加载资源PDF")
          .onClick(() => {
            this.controller.loadUrl("resource://rawfile/test.pdf");
          })
        
        Button("跳转到第3页")
          .onClick(() => {
            this.controller.loadUrl("https://www.example.com/test.pdf#page=3");
          })
      }
      .padding(10)

      Web({ 
        src: "https://www.example.com/test.pdf",  // 默认加载网络PDF
        controller: this.controller 
      })
        .domStorageAccess(true)
        .fileAccess(true)  // 为沙箱访问预留权限
        .width('100%')
        .height('80%')
    }
  }
}