提示：文章写完后，目录可以自动生成，如何生成可参考右边的帮助文档

---

前言

这篇文章记录的是我们小组在鸿蒙开发学习中完成的一个团队附加实验——选题二：ArkWeb 开发。

选题要求是在鸿蒙应用中使用 Web 组件嵌入网页，并实现原生与 Web 的基本交互。我做的是一个"个人简历展示"应用：原生侧提供导航按钮，Web 侧用 HTML/CSS 做了几个风格各异的简历卡片页面，通过原生按钮控制 Web 页面跳转，实现了原生与 Web 的双向交互。

下面我把开发过程中的核心代码和学习心得整理出来，作为我们学习的记录。

一、项目简介。

本项目是一个鸿蒙原生应用，主要功能包括：
使用 Web 组件在应用内嵌入网页
原生侧提供多个按钮，点击可加载不同的 HTML 页面
Web 页面使用HTML 实现，包含卡片式布局、背景图等
通过 WebviewController 实现原生对 Web 页面的控制权

二、环境配置

1.申请网络权限

在 module.json5 中需要声明网络权限，否则 Web 组件无法正常加载页面：
“requestPermissions”: [
{
“name”: “ohos.permission.INTERNET”
}
]
这个权限是 Web 组件工作的基础，不声明的话网页内容会加载失败。

2.页面路由配置

确保 main_pages.json 中将 Index 设置为主页面：
{
“src”: [“pages/Index”]
}
**

三、原生层开发（ArkTS）

1.主页面 Index.ets

WebviewController 的创建：private controller: webview.WebviewController = new webview.WebviewController() 这一行创建了一个 Web 视图控制器，它是原生层控制 Web 页面的"遥控器"。**

Web 组件的绑定：Web({ src: $rawfile(‘index.html’), controller: this.controller }) 这里做了两件事：一是用 $rawfile 加载资源目录下的 HTML 文件作为初始页面；二是把 controller 传进去，这样后续就能通过 controller 控制这个 Web 组件了。

JavaScript 访问权限：.javaScriptAccess(true) 开启后，Web 页面才能执行 JavaScript 代码。如果不需要 JS 可以关掉以提升性能。

页面跳转：每个按钮的 onClick 里调用 this.controller.loadUrl($rawfile{(}^{\prime }resumeX.htm{l}^{\prime }))，这就是原生控制Web页面跳转的核心API。$rawfile 是 ArkTS 的资源引用语法，指向 entry/resources/rawfile 目录下的文件。
**

2. 项目目录结构

**

四、Web 页面开发（HTML/CSS）

1. 首页 index.html

首页是一个导航页，用卡片式布局展示四个成员的简历入口：

设计要点：
背景图使用 resource://rawfile/ 协议引用鸿蒙资源目录下的图片
卡片使用 rgba 半透明背景，配合背景图产生毛玻璃效果
hover 伪类实现鼠标悬停时的背景色变化，增加交互感
纯标签实现页面跳转，无需 JavaScript 参与
最终效果：

通过点击下方的按钮可以跳转到对应的个人简历页面

2. 简历页面示例（resume1.html - 薄荷）

每个成员的简历页面风格可以不同，这里以薄荷的页面为例：


设计要点：
使用 Flex 布局实现卡片垂直水平居中
卡片采用圆角 + 阴影的 Material Design 风格
照片区域用 object-fit: cover 保证图片不变形填满区域
格言区域用左边框高亮，视觉上有"引用块"的感觉
兴趣爱好等用虚线边框的 slot-box 区分内容层级

3. 个人简历页面效果展示

大概就长成这个样子

五、原生与 Web 的交互实现

本项目的交互模式是"原生控制 Web"：
原生 → Web：通过 WebviewController.loadUrl() 方法加载指定 HTML 文件，实现页面跳转
Web → 原生：Web 页面内使用标签的 href 进行页面间跳转（纯前端路由）
这种设计的好处是：
原生层只负责"路由分发"，不需要关心 Web 页面的具体逻辑
Web 页面之间可以自由跳转，不受原生代码限制
修改 Web 页面内容不需要重新编译打包应用

六、开发中遇到的问题

1. Web 组件页面加载失败

刚开始运行时页面一片空白，检查后发现是 module.json5 里忘记声明 ohos.permission.INTERNET 权限。加上权限后恢复正常。

2. Web 组件高度设置

如果不设置 Web 组件的 height，它会默认收缩为内容高度，可能导致按钮被挤到屏幕外面。我设置了 .height(‘60%’) 让 Web 区域占屏幕 60% 高度，下方留给按钮区域。

3.针对loadUrl的报错

这个报错 Function may throw exceptions. Special handling is required 是 ArkTS 编译器的一个代码规范检查（ArkTSCheck）提示，出现在调用 this.controller.loadUrl() 的时候
在 ArkTS 的严格类型检查模式下，编译器会分析每个可能抛出异常的函数调用。WebviewController.loadUrl() 这个方法在底层是可能抛出异常的——比如传入的 URL 无效、Web 组件未正确初始化、或者资源文件不存在等情况。ArkTS 的设计哲学是"异常必须被显式处理"，所以编译器要求你必须用 try-catch 把这类调用包起来，或者在函数签名上声明 throws。但是我用的是 $rawfile(‘resume1.html’) 这种宏语法，编译器在编译时就能确认这个资源文件存在，所以实际上不可能出现"URL无效"的情况。异常触发的前提条件在我的场景里被排除了。所以再考虑到效率以及实际情况下这个其实可以不处理，实际应用中是否需要注意另作考虑，但是在某些情况下，我认为可以忽视这种显式处理以提高效率。

七、运行效果

总结

过这次 ArkWeb 开发实践，我主要有以下几点收获：
Web 组件的使用方式：鸿蒙的 Web 组件用法和浏览器中的 frame有相似之处，但通过 WebviewController 提供了更强大的原生控制能力。loadUrl、canGoBack、goBack 等方法让原生和 Web 之间的导航变得很简单。
混合开发的思路：传统原生应用开发中，改 UI 需要重新编译打包。而用 ArkWeb 嵌入 HTML 页面后，Web 层的 UI 修改只需要替换 HTML 文件，大大提升了迭代效率。这对于内容频繁更新的应用场景很有价值。
ArkTS 的资源引用：$rawfile 是 ArkTS 中引用原始文件资源的语法糖，编译时会自动处理路径。理解这个机制后，引用图片、HTML 文件等都变得很方便。