ArkWeb实战学习笔记02-环境搭建与基础配置

在HarmonyOS应用中嵌入Web页面是常见需求，ArkWeb作为应用框架Kit中的Web组件，提供了完整的页面加载与交互能力。开始集成之前，需要先确认开发环境版本与Kit导入方式，这些细节直接决定了后续代码能否正常运行。所有技术细节必须严格依据官方文档，本文不会添加文档未明确的内容。

核心概念

根据官方文档，HarmonyOS SDK以Kit维度提供开放能力，ArkWeb正是应用框架Kit中的一员。在基础入门环节，我们需要通过导入Kit的方式使用其接口能力。

文档中的"接口使用说明"指出：

导入-导入HarmonyOS SDK的开放能力

这意味着集成ArkWeb的第一步是确认开发环境支持API版本，然后按照Kit导入机制引入ArkWeb。

环境准备

从HarmonyOS版本清单可知，推荐使用的是 HarmonyOS 6.0.0(20) 及以上版本（6.1.0(23)等也可按需使用）。对应DevEco Studio版本为 6.0.0 Release 或更高。

如果选择API 23（6.1.0(23)），那么DevEco Studio需使用6.1.0 Release。文档未提供更低版本的具体限制。

注意：版本不匹配可能导致编译时接口不可用或运行时异常，务必对照官方版本兼容性表格确认。

核心实现

1. 导入 ArkWeb Kit

ArkWeb 以 Kit 形式提供能力，在 ArkTS 文件顶部通过以下方式导入：

typescript 复制代码

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

@kit.ArkWeb 是 HarmonyOS SDK 统一导出的 Kit 入口，webview 命名空间下包含 WebviewController 等核心类。

2. 创建最简 Web 组件

Web 是 ArkUI 声明式组件，通过 src 指定加载地址，controller 绑定控制器实例：

typescript 复制代码

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

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

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

Web 组件的 src 属性支持远程 URL（需网络权限）和本地资源路径（$rawfile('index.html')）两种形式。controller 属性不可缺省，后续的导航控制、JS 注入等操作均依赖该控制器实例。

3. 加载本地 HTML 资源

将 HTML 文件放在模块的 src/main/resources/rawfile/ 目录下，使用 $rawfile() 引用：

typescript 复制代码

Web({ src: $rawfile('index.html'), controller: this.controller })
  .width('100%')
  .height('100%')

4. module.json5 配置网络权限

加载远程 URL 时必须在 module.json5 中声明网络权限，否则页面无法加载：

json5 复制代码

// entry/src/main/module.json5
{
  "module": {
    "name": "entry",
    "type": "entry",
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      }
    ]
  }
}

提示：ohos.permission.INTERNET 是普通权限，无需用户授权弹窗，仅需在 module.json5 中声明即可生效。

注意事项

网络权限必须声明 ：加载远程 URL 时若未配置 ohos.permission.INTERNET，Web 组件将显示空白页，且不会抛出明显错误提示。
控制器不可复用 ：同一个 WebviewController 实例只能绑定一个 Web 组件。若在多个 Web 组件间共享同一控制器，运行时会抛出异常。
版本匹配 ：webview.WebviewController 从 API 9 起可用，但部分高级接口（如 setScrollable、createWebMessagePorts）有更高的 API 版本要求，使用前需查阅 API Reference 中的版本标注。
组件销毁时清理 ：在页面销毁时调用 webview.WebviewController 相关资源清理接口，避免内存泄漏。

常见问题 FAQ

Q: 如何确认当前SDK版本是否支持ArkWeb？

A: 在API参考页面左侧目录使用"高级筛选 > API version"，选择目标版本，ArkWeb相关的接口节点若正常显示则表示支持。文档中明确说明：API版本号小于等于指定版本的API节点正常显示，否则会被置灰。

Q: ArkWeb接口需要在元服务中使用吗？

A: 文档中"元服务API"标记规则：从API version 12开始，支持在元服务中使用的接口会添加该标记。ArkWeb是否支持元服务需查看具体接口说明，当前文档未给出。

关于ArkWeb的环境配置，依赖信息均可在官方文档中找到。下一篇将深入页面加载与导航控制（假设文档将提供相关内容），如果你在集成过程中遇到其他问题，欢迎在评论区讨论。