【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 初始显示状态，常用参数如下：
示例：
// 加载第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@Componentstruct 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%') } }}
复制代码
评论