做业务开发的时候，很多场景没必要全部原生写页面。比如活动落地页、帮助文档、协议页面，产品经常临时改文案，每次改都要打包发版本，成本太高。这种时候直接内嵌网页，后端改网页，App 不用重新发包，非常省事。

不少新手第一次上手 ArkWeb，直接复制网上旧版本鸿蒙代码，结果在鸿蒙 7 里各种报错：网页空白、JS 和 ArkTS 互相调用没反应、页面返回直接退出 App，还有权限忘了配置导致图片加载失败。

很多人误以为 ArkWeb 就是套个浏览器，其实不是。它是鸿蒙 7 内置的网页渲染内核，和系统浏览器内核同源，但能力受 App 权限管控。今天我们从零搭建 ArkWeb 页面，讲网页加载、JS 双向通信、返回事件拦截，把开发里最高频的坑一次性讲清楚，所有代码直接在 DevEco 鸿蒙 7 环境运行。

一、先理清 ArkWeb 基础概念与使用前提

ArkWeb 组件，就是在鸿蒙应用里开辟一块区域用来渲染 H5 网页。 两种加载来源：

1. 网络远程网页：https 在线地址，适合活动页、动态页面；
2. 本地静态网页：把 html、css、js 放到项目 rawfile 目录，适合离线协议、静态帮助页。

重要误区提醒：鸿蒙 7 使用 ArkWeb，必须手动申请网络权限。没有权限，远程网页直接白屏，控制台不会给很明显的报错提示，很多人卡在这一步排查很久。

类比理解：ArkWeb 就像在你的 App 里面放一个小浏览器窗口。窗口归 App 管，网页里的逻辑归 H5，两者可以约定接口互相传数据，但默认是隔离的，需要手动开启桥接才能互通。

第一步：添加网络权限

打开项目module.json5文件，在 requestPermissions 里面加上网络权限。

​
"requestPermissions": [
  {
    "name": "ohos.permission.INTERNET"
  }
]

​

说明：如果只加载本地 rawfile 静态网页，不需要 INTERNET 权限；只要加载线上 https 网页，必须配置这条。

1. 最简 ArkWeb 示例：加载远程网页

​
import { ArkWeb, WebController } from '@kit.ArkWeb';

@Entry
@Component
struct WebSimplePage {
  // 声明Web控制器，用来控制网页前进、后退、刷新
  @State webController: WebController = new WebController();

  build() {
    Column() {
      ArkWeb({
        src: "https://www.example.com",
        controller: this.webController
      })
      .width('100%')
      .height('100%')
    }
  }
}

​

关键语句拆解

import { ArkWeb, WebController } from '@kit.ArkWeb'; 鸿蒙 7 中 ArkWeb 相关 API 全部在@kit.ArkWeb这个包，旧版本包名不一样，直接复制旧代码会导入失败。

WebController：网页控制器。核心能力：网页刷新、前进、后退、停止加载。相当于浏览器的控制手柄。

src：网页地址。远程网页写 https 链接；本地静态页面写法：$rawfile("index.html")

执行效果

页面打开，直接渲染 example 网页，支持滚动、点击网页内链接。

常见错误

忘记导入 ArkWeb 包、module.json5 没加网络权限，现象就是页面空白，看不到网页内容。

二、本地静态网页加载（rawfile）

很多场景需要离线页面，比如用户协议、隐私说明，没有网络也能打开。

1. 在项目 entry 模块下，新建resources/rawfile文件夹；
2. 在 rawfile 放入 index.html。

ArkWeb 加载本地页面代码：

​
import { ArkWeb, WebController } from '@kit.ArkWeb';

@Entry
@Component
struct WebLocalPage {
  @State webController: WebController = new WebController();

  build() {
    Column() {
      ArkWeb({
        src: $rawfile("index.html"),
        controller: this.webController
      })
      .width('100%')
      .height('100%')
    }
  }
}

​

注意：rawfile 里面资源路径不要带中文、空格，部分特殊字符会导致加载失败。

三、拦截返回按键：网页内返回，不直接退出页面

默认情况下，页面点击系统返回键，直接关闭整个 ArkWeb 页面。但正常浏览器逻辑是：网页有历史记录，先网页后退，没有历史再关闭页面。我们通过 WebController 判断网页是否可以回退。

 ​
import { ArkWeb, WebController } from '@kit.ArkWeb';
import { BackPressEvent } from '@ohos/ui';

@Entry
@Component
struct WebBackPage {
  @State webController: WebController = new WebController();

  // 拦截页面返回事件
  onBackPress(event: BackPressEvent): boolean {
    // 判断网页能不能后退
    if (this.webController.accessBackward()) {
      this.webController.backward();
      // 消费事件，不退出页面
      return true;
    }
    // 不能后退，交给系统默认逻辑，关闭页面
    return false;
  }

  build() {
    Column() {
      ArkWeb({
        src: "https://www.example.com",
        controller: this.webController
      })
      .width('100%')
      .height('100%')
    }
  }
}

​

关键说明

onBackPress是页面返回回调。accessBackward()查询网页是否存在可回退历史。 return true代表我们自己处理返回动作，阻止系统默认关闭页面。

这是 ArkWeb 项目必写逻辑，几乎所有内嵌网页需求都要加上，否则用户体验很差。

四、ArkTS 和 H5 JS 双向通信（JS 桥）

最核心的高级能力：H5 网页调用鸿蒙原生代码；鸿蒙原生代码调用网页里面 JS 方法。

默认两者隔离，必须开启javaScriptAccess: true才能启用 JS 能力，线上网页开启要注意安全风险。

完整示例代码

​
import { ArkWeb, WebController, WebMessagePort } from '@kit.ArkWeb';

@Entry
@Component
struct WebJsBridgePage {
  @State webController: WebController = new WebController();
  @State msg:string = "等待网页消息";

  build() {
    Column() {
      Text(this.msg).fontSize(20).margin(10)
      ArkWeb({
        src: "https://www.example.com",
        controller: this.webController
      })
      .javaScriptAccess(true) // 开启JS执行支持
      .onMessage((event)=>{
        // 接收H5发送过来的消息
        this.msg = "收到网页消息：" + event.message;
      })
    }
    .width('100%')
    .height('100%')
  }
}

​

H5 网页里面 JS 发送消息代码（html 内）

​
// H5向鸿蒙ArkTS发送消息
web.postMessage("来自H5页面的消息");

​

原生调用 H5 里面 JS 函数：

​
// 在ArkTS中调用网页内js函数
this.webController.runJavaScript("hello('我是鸿蒙原生调用')", (result)=>{
  console.info("js执行返回结果：", result);
})

​

安全提醒：如果网页来源不可信，不要开启 javaScriptAccess，存在注入风险。只对可控的内部业务网页打开 JS 桥。

五、ArkWeb 开发高频踩坑汇总

坑 1：只记得前端网页调试，忽略鸿蒙网络权限

现象：网页白屏，网络请求全部失败。解决：module.json5 配置 ohos.permission.INTERNET。

坑 2：返回键直接关闭页面，没有网页回退

解决方案：实现 onBackPress，搭配 accessBackward 和 backward，上面代码可以直接复制。

坑 3：JS 通信不生效，忘记开启 javaScriptAccess

默认 JS 是关闭状态，不开启，H5 和原生无法互相调用。

坑 4：rawfile 资源路径带中文、特殊符号

网页资源加载失败，图片、css、js 丢失，尽量全部英文命名。

坑 5：ArkWeb 高度没有占满，页面被截断

ArkWeb 外层布局记得给 100% 宽高，父容器不能固定过小高度。

六、ArkWeb 功能选型速查表

功能	API	适用场景
加载远程网页	src 填 https 地址	活动页、后端动态页面
加载离线本地网页	src 填 $rawfile ("xxx.html")	协议、帮助文档，无网络可用
网页后退 / 刷新	WebController	控制网页浏览行为
拦截系统返回按键	onBackPress	优化返回交互体验
H5 与原生互发消息	onMessage + runJavaScript	H5 调用原生能力，原生调用网页 JS

结尾总结

ArkWeb 就是鸿蒙 7 应用里内置网页渲染组件，适合快速接入 H5 页面，不用全部原生开发。

1. 加载线上网页必须配置 INTERNET 网络权限，本地 rawfile 页面不需要；
2. WebController 用来操控网页，实现刷新、前进后退；
3. onBackPress 拦截返回事件，优先网页历史回退，提升用户体验；
4. javaScriptAccess 开启 JS 桥，实现 H5 和 ArkTS 双向通信，外部不可信网页谨慎开启；
5. 资源文件尽量英文命名，避免 rawfile 静态资源加载失败。

实操指南

新建页面，使用 ArkWeb 加载 rawfile 本地 html，实现：点击网页内按钮，发送消息到鸿蒙原生页面，原生接收后修改页面 Text 文字。