HarmonyOS ArkUI训练营入门-组件掌握系列-Web 组件加载网页-PC版本

概述

Web 组件是移动应用中常用的组件，用于在应用内加载和显示网页内容。HarmonyOS ArkUI 提供的 Web 组件功能强大，支持网页加载、进度监听、页面导航等特性。本文将从组件基础、属性配置、事件处理、高级用法、实际应用等多个维度，深入讲解 Web 组件的使用方法。

一、Web 组件基础

1.1 组件定义与作用

Web 组件用于在应用内嵌入网页，支持加载本地 HTML 文件和远程 URL。它是构建浏览器、网页预览、在线文档等场景的核心组件。

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

@Entry
@Component
struct WebBasic {
controller: webview.WebviewController = new webview.WebviewController();

build() {
Column() {
Web({ src: 'https://www.harmonyos.com', controller: this.controller })
.width('100%')
.height('100%')
}
}
}

1.2 构造函数

Web 的构造函数支持以下参数：

Web(options: {
src?: string; // 网页地址
controller?: WebviewController; // 控制器
})

1.3 WebviewController

WebviewController 用于控制 Web 组件的行为：

class WebviewController {
loadUrl(url: string): void; // 加载指定 URL
reload(): void; // 重新加载当前页面
goBack(): void; // 返回上一页
goForward(): void; // 前进到下一页
stop(): void; // 停止加载
}

1.4 核心属性

1.5 核心事件

二、属性配置

2.1 设置网页地址

通过 src 属性设置网页地址：

@Entry
@Component
struct WebUrl {
controller: webview.WebviewController = new webview.WebviewController();
@State url: string = 'https://www.harmonyos.com';

build() {
Column() {
TextInput({ placeholder: '输入网址', text: this.url })
.width('100%')
.height(40)
.margin({ bottom: 12 })
.onChange((value: string) => {
this.url = value;
})

Button('访问')
.width('100%')
.height(40)
.margin({ bottom: 16 })
.onClick(() => {
this.controller.loadUrl(this.url);
})

Web({ src: this.url, controller: this.controller })
.width('100%')
.height(400)
}
.padding(20)
}
}

2.2 JavaScript 访问控制

通过 javaScriptAccess 属性控制 JavaScript 访问：

@Entry
@Component
struct JavaScriptAccess {
controller: webview.WebviewController = new webview.WebviewController();
@State allowJs: boolean = true;

build() {
Column() {
Row() {
Text('允许 JavaScript')
.fontSize(14)
.layoutWeight(1)
Toggle({ type: ToggleType.Switch, isOn: this.allowJs })
.onChange((isOn: boolean) => {
this.allowJs = isOn;
})
}
.width('100%')
.margin({ bottom: 16 })

Web({ src: 'https://www.harmonyos.com', controller: this.controller })
.width('100%')
.height(400)
.javaScriptAccess(this.allowJs)
}
.padding(20)
}
}

三、事件处理

3.1 加载进度监听

通过 onProgressChange 事件监听加载进度：

@Entry
@Component
struct ProgressChange {
controller: webview.WebviewController = new webview.WebviewController();
@State progress: number = 0;

build() {
Column() {
Progress({ value: this.progress, total: 100, type: ProgressType.Linear })
.width('100%')
.height(4)
.margin({ bottom: 12 })

Web({ src: 'https://www.harmonyos.com', controller: this.controller })
.width('100%')
.height(400)
.onProgressChange((event: { newProgress: number }) => {
this.progress = event.newProgress;
})
.onPageBegin(() => {
this.progress = 0;
})
.onPageEnd(() => {
this.progress = 100;
})
}
.padding(20)
}
}

3.2 页面加载事件

通过 onPageBegin 和 onPageEnd 事件监听页面加载状态：

@Entry
@Component
struct PageEvents {
controller: webview.WebviewController = new webview.WebviewController();
@State status: string = '未开始';

build() {
Column() {
Text('页面状态：' + this.status)
.fontSize(14)
.fontColor('#666666')
.margin({ bottom: 12 })

Web({ src: 'https://www.harmonyos.com', controller: this.controller })
.width('100%')
.height(400)
.onPageBegin(() => {
this.status = '加载中…';
})
.onPageEnd(() => {
this.status = '加载完成';
})
.onError((event: { errorCode: number }) => {
this.status = '加载失败，错误码：' + event.errorCode;
})
}
.padding(20)
}
}

四、高级用法

4.1 页面导航控制

使用 WebviewController 控制页面导航：

@Entry
@Component
struct NavigationControl {
controller: webview.WebviewController = new webview.WebviewController();

build() {
Column() {
Row() {
Button('返回')
.layoutWeight(1)
.height(40)
.onClick(() => {
this.controller.goBack();
})
Button('前进')
.layoutWeight(1)
.height(40)
.margin({ left: 8 })
.onClick(() => {
this.controller.goForward();
})
Button('刷新')
.layoutWeight(1)
.height(40)
.margin({ left: 8 })
.onClick(() => {
this.controller.reload();
})
}
.width('100%')
.margin({ bottom: 12 })

Web({ src: 'https://www.harmonyos.com', controller: this.controller })
.width('100%')
.height(400)
}
.padding(20)
}
}

4.2 加载本地 HTML

加载本地 HTML 文件：

@Entry
@Component
struct LocalHtml {
controller: webview.WebviewController = new webview.WebviewController();

build() {
Column() {
Web({ src: $rawfile('local.html'), controller: this.controller })
.width('100%')
.height(400)
}
.padding(20)
}
}

五、实际案例：简易浏览器

5.1 需求分析

构建一个简易浏览器页面，包含网址输入框、加载进度条和 Web 页面显示区域。

5.2 代码实现

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

@Entry
@Component
struct SimpleBrowser {
controller: webview.WebviewController = new webview.WebviewController();
@State urlText: string = 'https://www.harmonyos.com';
@State loadProgress: number = 0;

build() {
Column() {
Row() {
Button('返回')
.onClick(() => {
router.back();
})
Text('Web 组件')
.fontSize(20)
.fontWeight(FontWeight.Bold)
.layoutWeight(1)
.textAlign(TextAlign.Center)
}
.width('100%')
.padding(12)
.backgroundColor('#F1F3F5')

Column() {
Row() {
TextInput({ placeholder: '输入网址', text: this.urlText })
.layoutWeight(1)
.height(40)
.onChange((value: string) => {
this.urlText = value;
})
Button('访问')
.height(40)
.margin({ left: 8 })
.onClick(() => {
this.controller.loadUrl(this.urlText);
})
}
.width('90%')
.margin({ top: 8 })

if (this.loadProgress > 0 && this.loadProgress < 100) {
Progress({ value: this.loadProgress, total: 100, type: ProgressType.Linear })
.width('90%')
.height(4)
.margin({ top: 6 })
}

Web({ src: this.urlText, controller: this.controller })
.width('90%')
.layoutWeight(1)
.margin({ top: 8, bottom: 12 })
.onProgressChange((event: { newProgress: number }) => {
this.loadProgress = event.newProgress;
})
.onPageBegin(() => {
this.loadProgress = 0;
})
.onPageEnd(() => {
this.loadProgress = 100;
})
}
.width('100%')
.layoutWeight(1)
}
.width('100%')
.height('100%')
.backgroundColor('#FFFFFF')
}
}

六、总结

Web 组件是 HarmonyOS ArkUI 中常用的网页加载控件，掌握其使用方法对于构建浏览器和网页预览功能至关重要。

核心要点：

希望本文能帮助你更好地理解和使用 Web 组件，构建出优秀的 HarmonyOS 应用。

参考资料：

• HarmonyOS ArkUI Web 官方文档
• HarmonyOS 开发指南