【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%')
}
}
}