【HarmonyOS 6.0】ArkWeb新特性：PDF加载成功/失败回调及滚动到底部监听

文章目录

• 1 -> 概述
• 2 -> 背景：ArkWeb PDF预览能力概览
• • 2.1 -> 基础配置
  • 2.2 -> 三种PDF加载方式
  • 2.3 -> 预览参数配置
• 3 -> `onPdfLoadEvent`：PDF加载状态回调（API 20+）
• • 3.1 -> 事件定义与参数说明
  • 3.2 -> 完整代码示例
  • 3.3 -> 实际应用场景
• 4 -> `onPdfScrollAtBottom`：滚动到底部事件回调（API 20+）
• • 4.1 -> 事件定义与参数说明
  • 4.2 -> 完整代码示例
  • 4.3 -> 实际应用场景
• 5 -> 综合应用：两个事件的协同使用
• 6 -> 总结

1 -> 概述

在移动应用开发中，PDF文档预览是一项非常高频的需求——合同展示、电子发票预览、电子书阅读、产品说明书浏览等场景都离不开PDF的支持。HarmonyOS ArkWeb组件早在API 9版本便已提供基础的PDF预览能力，支持加载网络、应用沙箱内和本地资源等多种来源的PDF文档。然而，在API 20版本之前，开发者只能被动地展示PDF内容，无法感知PDF是否加载成功、是否因为网络异常或文件损坏而加载失败，也难以准确判断用户是否已经滚动到PDF文档的末尾。

从API version 20开始，ArkWeb针对PDF浏览能力进行了重要增强，新增了两个关键回调事件：

• onPdfLoadEvent：通知应用PDF页面的加载状态，包括加载成功或加载失败，并提供详细的错误信息
• onPdfScrollAtBottom：通知应用用户已将PDF页面滚动到底部

这两个事件从底层解决了PDF预览场景中“状态不可知”的痛点，让开发者能够基于用户行为构建更完整、更智能的产品体验。本文将围绕这两个新增特性展开详细讲解，涵盖API用法、代码示例和典型应用场景。

2 -> 背景：ArkWeb PDF预览能力概览

在深入讲解这两个新增事件之前，有必要先回顾一下ArkWeb组件的基础PDF预览能力，以便理解本次增强在整个功能架构中的位置。

2.1 -> 基础配置

使用Web组件预览PDF，需要进行以下基础配置：

• 开启DOM存储权限：PDF预览页面会使用window.localStorage记录侧导航栏的展开状态，因此必须设置domStorageAccess(true)
• 网络访问权限（仅网络PDF需要）：在module.json5中配置ohos.permission.INTERNET权限
• 文件访问权限（仅应用沙箱PDF需要）：设置fileAccess(true)

2.2 -> 三种PDF加载方式

ArkWeb支持通过三种方式加载PDF文档：

方式一：加载网络PDF文档

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)

2.3 -> 预览参数配置

在加载PDF文档时，还可以通过URL参数控制初始显示状态，这些参数通过URL片段（#）传递：

使用示例：

// 加载第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");

关于动态切换PDF文档：需要特别注意的是，WebOptions的第一个参数变量src不能通过状态变量（如@State）动态更改地址，如需切换PDF文档，必须调用loadUrl()接口重新加载。

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

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

3 -> onPdfLoadEvent：PDF加载状态回调（API 20+）

3.1 -> 事件定义与参数说明

onPdfLoadEvent是API version 20新增的PDF加载状态回调事件，用于通知应用PDF页面的加载结果，包括加载成功和加载失败两种情况。

事件回调函数的参数类型为OnPdfLoadEvent，包含以下关键字段：

3.2 -> 完整代码示例

以下是一个完整的示例，演示如何监听PDF加载状态，并根据加载结果给出相应的用户反馈：

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

@Entry
@Component
struct PdfPreviewWithLoadEvent {
controller: webview.WebviewController = new webview.WebviewController();
@State loadStatus: string = '等待加载…';
@State isLoadError: boolean = false;

build() {
Column() {
// 状态展示区域
Row() {
Text(`加载状态：${this.loadStatus}`)
.fontSize(14)
.fontColor(this.isLoadError ? '#FF4444' : '#4CAF50')
}
.padding(12)
.width('100%')
.backgroundColor(this.isLoadError ? '#FFEBEE' : '#E8F5E9')

// Web组件展示PDF
Web({
src: 'https://www.example.com/test.pdf',
controller: this.controller
})
.domStorageAccess(true)
.onPdfLoadEvent((eventInfo: OnPdfLoadEvent) => {
console.info(`PDF加载事件触发，URL: ${eventInfo.url}, result: ${eventInfo.result}`);

if (eventInfo.result === 0) {
// 加载成功
this.loadStatus = '加载成功';
this.isLoadError = false;
console.info('PDF文档加载成功，可以开始预览');
} else {
// 加载失败
this.loadStatus = `加载失败，错误码：${eventInfo.result}`;
this.isLoadError = true;
console.error(`PDF文档加载失败，错误码：${eventInfo.result}，URL：${eventInfo.url}`);
}
})
.width('100%')
.height('80%')
}
}
}

3.3 -> 实际应用场景

onPdfLoadEvent的应用价值非常明确：

场景一：加载失败提示与重试机制

当用户网络不稳定或PDF文件损坏时，加载失败是一个高频场景。通过监听onPdfLoadEvent，可以在加载失败时自动弹出友好提示，并提供重试按钮，而不是让用户面对一个空白的Web视图。

.onPdfLoadEvent((eventInfo: OnPdfLoadEvent) => {
if (eventInfo.result !== 0) {
// 显示加载失败弹窗，提供重试选项
this.showRetryDialog(eventInfo.url);
}
})

场景二：大数据量的PDF预加载

在电商、医疗、金融等需要展示大量PDF文档的场景中，可以在用户浏览文档列表时提前预加载下一个PDF。监听加载成功事件后，可以将预加载的PDF内容缓存起来，提升用户切换文档时的响应速度。

场景三：加载耗时统计与性能监控

开发侧可以在onPdfLoadEvent中记录PDF从发起加载到完成的时间，用于监控特定文档的加载性能，辅助优化文档的分发策略。

.onPdfLoadEvent((eventInfo: OnPdfLoadEvent) => {
if (eventInfo.result === 0) {
const loadTime = Date.now() – this.startTime;
console.info(`PDF加载完成，耗时：${loadTime}ms，文件：${eventInfo.url}`);
// 上报性能数据
this.reportPerformance('pdf_load_time', loadTime);
}
})

4 -> onPdfScrollAtBottom：滚动到底部事件回调（API 20+）

4.1 -> 事件定义与参数说明

onPdfScrollAtBottom是API version 20新增的滚动到底部回调事件，用于通知应用用户已将PDF页面滚动到文档末尾。

在API 20版本之前，由于PDF是以插件的形式在Web组件中加载的，传统的onScroll事件无法监听到PDF内部滚动条的滚动。开发者只能通过onOverScroll回调中的偏移量来粗略判断PDF是否到达顶端或底端，但这种方式不仅精度有限，而且需要自行处理偏移量阈值判断，代码复杂且不可靠。

onPdfScrollAtBottom的出现从根本上解决了这一问题——ArkWeb底层直接提供了PDF滚动到底部的精准通知。

事件回调函数的参数类型为OnPdfScrollEvent，包含以下关键字段：

4.2 -> 完整代码示例

以下是一个完整的示例，演示如何监听PDF滚动到底部事件，并在到达底部时触发相应的业务逻辑：

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

@Entry
@Component
struct PdfPreviewWithScrollEvent {
controller: webview.WebviewController = new webview.WebviewController();
@State scrollMessage: string = '滚动到底部时将自动触发';
@State bottomReachedCount: number = 0;

build() {
Column() {
// 提示区域
Row() {
Text(this.scrollMessage)
.fontSize(14)
.fontColor('#666')
}
.padding(12)
.width('100%')
.justifyContent(FlexAlign.Center)

// 已触发次数统计
if (this.bottomReachedCount > 0) {
Text(`已触发滚动到底部事件 ${this.bottomReachedCount} 次`)
.fontSize(12)
.fontColor('#999')
.padding({ bottom: 8 })
}

// Web组件展示PDF
Web({
src: 'https://www.example.com/long-document.pdf',
controller: this.controller
})
.domStorageAccess(true)
.onPdfScrollAtBottom((eventInfo: OnPdfScrollEvent) => {
console.info(`PDF滚动到底部，URL: ${eventInfo.url}`);

// 更新UI状态
this.bottomReachedCount++;
this.scrollMessage = `已滚动到底部！第${this.bottomReachedCount}次触发`;

// 模拟震动反馈（可选）
// this.getUIContext().getPromptAction().showToast({ message: '已滚动到底部' });
})
.width('100%')
.height('80%')
}
}
}

4.3 -> 实际应用场景

onPdfScrollAtBottom的应用价值同样十分广泛：

场景一：电子书阅读与分页标记

在电子书应用中，当用户阅读完一本书的最后一页时，可以自动记录“已读完”标记，并推荐下一本书或展示评分界面。

.onPdfScrollAtBottom((eventInfo: OnPdfScrollEvent) => {
// 记录用户已阅读完毕
this.markBookAsCompleted(this.currentBookId);
// 弹出读后感或评分弹窗
this.showRatingDialog();
})

场景二：合同签署场景中的“签字确认”

在电子合同签署流程中，通常要求用户在阅读完合同全文后才能在签字区签名。通过监听滚动到底部事件，可以动态解锁签字按钮，确保用户确实浏览了完整内容。

.onPdfScrollAtBottom((eventInfo: OnPdfScrollEvent) => {
// 解锁签字按钮
this.isSignEnabled = true;
// 显示提示信息
this.showToast('您已阅读完整合同内容，现在可以进行签字');
})

场景三：无限滚动与分页加载

在需要展示大量PDF文档的场景中，可以在用户滚动到当前PDF末尾时自动加载下一个PDF，实现连续阅读的无缝体验。

.onPdfScrollAtBottom((eventInfo: OnPdfScrollEvent) => {
if (this.hasNextDocument()) {
// 自动加载下一个PDF
const nextPdfUrl = this.getNextDocumentUrl();
this.controller.loadUrl(nextPdfUrl);
this.showToast('正在加载下一篇文档…');
}
})

5 -> 综合应用：两个事件的协同使用

在实际开发中，onPdfLoadEvent和onPdfScrollAtBottom往往需要协同工作。以下是一个综合示例，展示如何同时使用这两个事件构建一个完整的PDF阅读体验：

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

@Entry
@Component
struct ComprehensivePdfReader {
controller: webview.WebviewController = new webview.WebviewController();
@State isLoading: boolean = true;
@State loadSuccess: boolean = false;
@State errorMessage: string = '';
@State hasReachedBottom: boolean = false;
@State showBottomIndicator: boolean = false;

build() {
Column() {
// 加载状态指示器
if (this.isLoading) {
LoadingProgress()
.width(40)
.height(40)
.color('#007DFF')
}

// 加载失败时的错误展示
if (!this.loadSuccess && !this.isLoading && this.errorMessage) {
Column() {
Text('📄 PDF加载失败')
.fontSize(16)
.fontWeight(FontWeight.Medium)
Text(this.errorMessage)
.fontSize(14)
.fontColor('#999')
.margin({ top: 8 })
Button('重新加载')
.onClick(() => {
this.isLoading = true;
this.loadSuccess = false;
this.errorMessage = '';
this.controller.loadUrl('https://www.example.com/test.pdf');
})
.margin({ top: 16 })
}
.width('100%')
.height('60%')
.justifyContent(FlexAlign.Center)
}

// PDF预览
if (!this.errorMessage || (this.loadSuccess && !this.isLoading)) {
Web({
src: 'https://www.example.com/test.pdf',
controller: this.controller
})
.domStorageAccess(true)
.onPdfLoadEvent((eventInfo: OnPdfLoadEvent) => {
this.isLoading = false;
if (eventInfo.result === 0) {
this.loadSuccess = true;
this.errorMessage = '';
console.info(`PDF加载成功: ${eventInfo.url}`);
} else {
this.loadSuccess = false;
this.errorMessage = `加载失败，错误码：${eventInfo.result}`;
console.error(`PDF加载失败: ${eventInfo.url}, result: ${eventInfo.result}`);
}
})
.onPdfScrollAtBottom((eventInfo: OnPdfScrollEvent) => {
if (!this.hasReachedBottom) {
this.hasReachedBottom = true;
this.showBottomIndicator = true;
console.info(`PDF滚动到底部: ${eventInfo.url}`);
// 显示提示并自动隐藏
setTimeout(() => {
this.showBottomIndicator = false;
}, 2000);
}
})
.width('100%')
.height('80%')
}

// 滚动到底部提示浮层
if (this.showBottomIndicator) {
Text('📌 已阅读至文档末尾')
.fontSize(14)
.fontColor('#FFFFFF')
.backgroundColor('rgba(0,0,0,0.7)')
.borderRadius(20)
.padding({ left: 16, right: 16, top: 8, bottom: 8 })
.position({ x: '50%', y: '90%' })
.translate({ x: '-50%', y: 0 })
}
}
}
}

6 -> 总结

HarmonyOS 6.0（API version 20）中，ArkWeb组件的PDF预览能力在“状态感知”维度上迈出了重要一步。onPdfLoadEvent让开发者能够准确获知PDF的加载结果——无论是成功还是失败，都可以基于此构建完善的异常处理与用户反馈机制。onPdfScrollAtBottom则从根本上解决了PDF内部滚动状态不可知的问题，使电子书阅读、合同签署、连续阅读等场景的交互设计变得更加优雅和可靠。

从开发者的视角来看，这两个事件的接入成本很低——只需在Web组件上添加对应的回调函数即可。结合已有的PDF参数配置（如页码跳转、缩放、工具栏隐藏、背景色设置等），ArkWeb已经能够覆盖绝大多数PDF预览需求。随着HarmonyOS生态的持续演进，ArkWeb在PDF能力方面的进一步增强值得持续关注。

感谢各位大佬支持！！！

互三啦！！！