HarmonyOS 6.0 adds new load-result and scroll-to-bottom callbacks for ArkWeb PDF preview, solving the long-standing problem of invisible PDF state. Developers can now implement loading indicators, retry flows, reading confirmation, and progress tracking based on official events. Keywords: ArkWeb, PDF Preview, HarmonyOS 6.0.
Technical specifications are easy to scan
| Parameter | Description |
|---|---|
| Platform / Language | HarmonyOS 6.0+ / ArkTS |
| Core Components | @kit.ArkWeb, WebviewController |
| Protocol / Source | https, resource://rawfile, local sandbox files |
| Minimum Capability Version | API version 20 |
| Key Permissions / Configuration | domStorageAccess(true), fileAccess(true) when needed, network permission |
| Core Callbacks | onPdfLoadEvent, onPdfScrollAtBottom |
AI Visual Insight: The image shows a UI screenshot of ArkWeb’s PDF preview capability. The key takeaway is that the Web component now provides native PDF rendering support, making it suitable for document-heavy scenarios such as contracts, manuals, and reports. In practice, this means developers can complete in-app preview and state-driven interactions without integrating a third-party PDF rendering library.
ArkWeb has turned PDF preview from a black box into an observable workflow
In earlier versions, ArkWeb could open PDF files directly, but the application layer had no way to know whether loading succeeded or whether the user had actually reached the end of the document. That limitation directly blocked common business flows such as agreement confirmation, error feedback, and reading analytics.
With HarmonyOS 6.0 and API version 20, ArkWeb introduces two key callbacks: onPdfLoadEvent detects the load result, and onPdfScrollAtBottom detects when the user reaches the bottom of the document. Together, they fill in the two most important observation points in the PDF lifecycle.
The two callbacks solve different problems
| Callback | Trigger Timing | Returned Data | Typical Scenarios |
|---|---|---|---|
onPdfLoadEvent |
When PDF loading finishes | url, result |
Loading indicators, retry flows, monitoring reports |
onPdfScrollAtBottom |
When the user actively scrolls to the bottom | url |
Agreement consent, reading completion, section transitions |
.onPdfLoadEvent((eventInfo: OnPdfLoadEvent) => {
// Update page state based on the load result
if (eventInfo.result === 'success') {
console.info(`PDF loaded successfully: ${eventInfo.url}`)
} else {
console.error(`PDF failed to load: ${eventInfo.url}`)
}
})This code explicitly exposes the PDF load state to the business layer.
onPdfLoadEvent gives business logic full control over both success and failure
This callback does not fire only on success. It fires whenever loading completes. That makes it a natural fit for unified handling of loading animation dismissal, retry button display, exception logging, and availability metrics.
A minimal working example for state awareness
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct PdfPreviewPage {
controller: webview.WebviewController = new webview.WebviewController();
@State loadStatus: string = 'Loading...';
build() {
Column() {
Text(this.loadStatus)
.fontSize(14)
.padding(12)
Web({ src: 'https://example.com/doc.pdf', controller: this.controller })
.domStorageAccess(true) // PDF preview depends on DOM storage capability
.onPdfLoadEvent((eventInfo: OnPdfLoadEvent) => {
// Handle both success and failure in one place
this.loadStatus = eventInfo.result === 'success'
? 'Document loaded successfully'
: 'Document failed to load. Please try again';
})
}
}
}This code closes the basic state-feedback loop for a PDF page.
onPdfScrollAtBottom makes reading completion a first-class official event
Traditional Web scroll listeners are not reliable for PDF plugin content, because a PDF is not a standard DOM document flow. The value of this new callback is that it directly abstracts the business action of “the user has scrolled to the bottom.”
This is especially important for electronic contracts, privacy policies, and help documents that require reading confirmation. Note that this event emphasizes active user scrolling. It does not fire automatically when rendering completes.
A typical implementation for agreement confirmation
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct AgreementPage {
controller: webview.WebviewController = new webview.WebviewController();
@State canAgree: boolean = false;
build() {
Stack() {
Web({ src: 'resource://rawfile/agreement.pdf', controller: this.controller })
.domStorageAccess(true)
.onPdfScrollAtBottom((eventInfo: OnPdfScrollEvent) => {
// Allow confirmation only after the user reaches the bottom
this.canAgree = true;
console.info(`Reading completed: ${eventInfo.url}`)
})
Button('Agree and Continue')
.enabled(this.canAgree) // Disable the button until the required state is met
}
}
}This code creates a strong dependency between “reading completed” and “proceed to the next action.”
PDF preview parameters can further improve the first-screen experience
ArkWeb supports URL fragment parameters to control the initial PDF page, zoom level, toolbar visibility, and navigation pane visibility. HarmonyOS 6.0 also adds pdfbackgroundcolor to help adapt the viewer to light and dark themes.
Common parameters at a glance
| Parameter | Example | Purpose |
|---|---|---|
page |
#page=3 |
Open page 3 |
zoom |
#zoom=150 |
Set the zoom ratio |
toolbar |
#toolbar=0 |
Hide the top toolbar |
navpanes |
#navpanes=0 |
Hide the side navigation pane |
pdfbackgroundcolor |
#pdfbackgroundcolor=2d2d2d |
Set the PDF background color |
const pdfUrl = 'https://example.com/doc.pdf#page=3&zoom=200&toolbar=0';
// Switch to a dark background in night mode for better reading comfort
const themedUrl = isDarkMode
? `${pdfUrl}&pdfbackgroundcolor=2d2d2d`
: `${pdfUrl}&pdfbackgroundcolor=ffffff`;This code turns the first-screen PDF experience into a configurable option through URL parameters.
ArkWeb supports three PDF loading methods for mainstream business scenarios
Network PDFs work well for online document centers. Sandbox files fit offline reading after download. rawfile resources are ideal for built-in agreements and help documents. All three share the same callback mechanism, but their configuration requirements differ slightly.
Network, sandbox, and bundled resources differ in setup
| Source | Address Format | Extra Requirement | Recommended Scenarios |
|---|---|---|---|
| Network file | https://...pdf |
Network permission | Online documents, remote contracts |
| Sandbox file | filesDir + '/a.pdf' |
fileAccess(true) |
Download cache, offline reading |
| App resource | resource://rawfile/a.pdf |
Resource bundled in app | Agreements, manuals |
Web({ src: 'resource://rawfile/user_guide.pdf', controller: this.controller })
.domStorageAccess(true)
.onPdfLoadEvent((eventInfo: OnPdfLoadEvent) => {
// Bundled resources are usually more stable and fit critical agreement pages
console.info(`Load result: ${eventInfo.result}`)
})This code demonstrates the most stable built-in PDF loading pattern.
Web component configuration determines whether PDF preview works reliably
First, domStorageAccess(true) is effectively mandatory in most cases, because PDF preview uses local storage to preserve part of the UI state. Second, sandbox files require fileAccess(true) to be enabled explicitly.
Another common pitfall appears when switching documents dynamically. Do not rely on updating src through a state variable. The correct approach is to call WebviewController.loadUrl(). Otherwise, the new PDF address may not take effect.
The correct way to switch PDFs dynamically
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct DynamicPdfPage {
controller: webview.WebviewController = new webview.WebviewController();
switchPdf(newUrl: string) {
// Use the controller to load a new PDF when switching dynamically
this.controller.loadUrl(newUrl);
}
}This code avoids the issue where reactive updates to src do not refresh the PDF as expected.
Agreement confirmation pages are the most direct production use case for this feature set
A complete agreement page usually contains three stages: show a loading indicator on entry, allow retry on failure, and enable the consent button only after the user reaches the bottom. The new ArkWeb callbacks connect these three stages into a standard workflow.
If your application runs in a high-security mode, note that ArkWeb may restrict PDF Viewer preview capability. In that case, prepare a fallback plan, such as opening an external viewer or switching to a custom reading component.
FAQ
1. Which HarmonyOS version first supports ArkWeb PDF callbacks?
Support starts with API version 20, which corresponds to HarmonyOS 6.0 and later. On earlier versions, you should detect capability availability and provide graceful degradation.
2. Why can I open the PDF, but the callback or UI state behaves abnormally?
First check whether domStorageAccess(true) is enabled. If you are loading a sandbox file, also confirm that fileAccess(true) is enabled and that the path is real and accessible.
3. Why does updating @State pdfUrl not switch the page to the new PDF?
Because ArkWeb PDF preview does not rely on reactive src updates. Dynamic switching must go through WebviewController.loadUrl(), which is the official and reliable approach.
AI Readability Summary: This article provides a structured walkthrough of the enhanced PDF preview capabilities in HarmonyOS 6.0 ArkWeb, focusing on the two key callbacks onPdfLoadEvent and onPdfScrollAtBottom. It covers supported versions, parameter configuration, three loading methods, dynamic switching, and real-world agreement confirmation flows.