Harmony

[Harmony] 纯血鸿蒙Web组件避坑

Posted by xiuyuantech on 2026-06-19

纯血鸿蒙 Web 组件是 HarmonyOS NEXT 系统中用于在原生应用中加载和展示网页内容的核心组件，
基于 ArkUI 框架和 ArkTS 语言构建，不再依赖 Android 的 AOSP 代码，完全运行在鸿蒙自研内核之上。
相比传统 WebView，它在渲染性能、内存占用和交互流畅度上都有显著提升，尤其在处理复杂 H5 页面时，滚动流畅度比传统方案提升了约 30%。
官网Web组件链接：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkweb。

使用场景

ArkWeb（方舟Web）提供了Web组件，用于在应用中显示Web页面内容。常见使用场景包括：

  • 应用集成Web页面：应用可以在界面中使用Web组件，嵌入Web页面内容，以降低开发成本，提升开发、运维效率。

  • 浏览器网页浏览场景：浏览器类应用可以使用Web组件，打开三方Web网页，使用无痕浏览模式浏览Web页面，设置广告拦截等。

  • 小程序：小程序类宿主应用可以使用Web组件，渲染小程序的页面，实现同层渲染，视频托管等小程序的功能。

Web组件访问在线Web网页时需添加网络权限：ohos.permission.INTERNET

约束与限制

  • 可依据ArkWeb内核版本在相关网站查询W3C标准的支持情况。
    例如：https://developer.mozilla.org/en-US/ 和 https://webassembly.org/features/ 。

  • ArkWeb内核版本：ArkWeb基于谷歌Chromium内核开发，系统版本与Chromium版本的对应关系如表格所示。

    系统版本 Chromium版本
    HarmonyOS 4.0及之前 M99
    HarmonyOS 4.1-5.1 M114
    HarmonyOS 6.0

    M132（默认，推荐使用，请参考M114->M132差异适配指南）

    M114（可选，若应用需切换为此内核，请参考M114内核在HarmonyOS 6.0系统上的适配指导）
    HarmonyOS 6.1 M132
    HarmonyOS 7.0

    M144（默认，推荐使用，请参考M132->M144差异适配指南）

    M132（可选，若应用需切换为此内核，请参考M132内核在HarmonyOS 7.0系统上的适配指导）

  • 为保障用户隐私安全，HarmonyOS内置了ArkWeb组件，旨在为全场景设备提供安全、可靠且一致的网页浏览体验。应用渲染网页需调用ArkWeb组件；元服务内嵌网页渲染则需使用官方提供的Webview组件。开发者可根据其元服务开发框架，选择使用ASCF Webview或AtomicServiceEnhancedWeb组件。元服务内嵌页面内容需遵循元服务内嵌页面管理规范。

Web组件避坑

  • WebviewController绑定后在onControllerAttached方法中才能使用
    一个WebviewController对象只能控制一个Web组件，且必须在Web组件和WebviewController绑定后，才能调用WebviewController上的方法（静态方法除外）。

  • 默认不支持新窗口跳转
    Web组件提供了在新窗口打开页面的能力，开发者可以通过multiWindowAccess()接口来设置是否允许网页在新窗口打开。当有新窗口打开时，应用侧会在onWindowNew()接口或onWindowNewExt()接口中收到Web组件新窗口事件。

    1
    2
    3
    4
    5
    Web({ src: 'xx'})
         .multiWindowAccess(true)
         .onWindowNew(() => {
           //todo somethings
         })

  • 默认不支持js,需要手动开启

    1
    2
    3
    4
    Web({ src: 'xx'})
         .javaScriptAccess(true)
         .javaScriptProxy({})
    // js 对象也可以通过webviewController.registerJavaScriptProxy,但销毁时需要调用deleteJavaScriptRegister移除对象

  • 默认不支持位置、摄像、麦克风等权限,需要app适配

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    aboutToAppear(): void {
      // todo 提前申请相关权限
    }
    Web({ src: 'xx'})
         .onPermissionRequest((event) => {
            if (event) {
             this.uiContext.showAlertDialog({
               title: 'title',
               message: 'text',
               primaryButton: {
                 value: 'deny',
                 action: () => {
                   event.request.deny();
                 }
               },
               secondaryButton: {
                 value: 'onConfirm',
                 action: () => {
                   event.request.grant(event.request.getAccessibleResource());
                 }
               },
               cancel: () => {
                 event.request.deny();
               }
             })
           }
         })
         .geolocationAccess(true)
         .onGeolocationShow((event) => {
           // 位置权限申请通知仅对当前Web组件生效，应用内的其他Web组件不受影响
           this.uiContext.showAlertDialog({
             title: '位置权限请求',
             message: '是否允许获取位置信息',
             primaryButton: {
               value: 'cancel',
               action: () => {
                 if (event) {
                   // 不允许此站点位置权限请求
                   // 注意invoke的第3个参数表示是否记住当前选择，如果传true，则下次不再弹框
                   event.geolocation.invoke(event.origin, false, false);
                 }
               }
             },
             secondaryButton: {
               value: 'ok',
               action: () => {
                 if (event) {
                   // 允许此站点位置权限请求
                   // 注意invoke的第3个参数表示是否记住当前选择，如果传true，则下次不再弹框
                   event.geolocation.invoke(event.origin, true, false);
                 }
               }
             },
             cancel: () => {
               if (event) {
                 // 不允许此站点位置权限请求
                 // 注意invoke的第3个参数表示是否记住当前选择，如果传true，则下次不再弹框
                 event.geolocation.invoke(event.origin, false, false);
               }
             }
           })
         })

Web很多基础配置默认都是关闭的，需要手动设置开启

常见问题, 行业实践与常见问题

鸿蒙、Android、IOS三端对比

对比维度 鸿蒙 Web 组件（ArkWeb） Android WebView iOS WKWebView
‌渲染内核‌ 基于 Chromium 深度定制 Chromium Blink 引擎 WebKit 引擎
‌架构模式‌ 多进程隔离（应用进程、渲染进程、GPU 进程、孵化进程、Foundation 进程分离） 单进程或多进程（取决于版本和配置） 多进程（应用进程与渲染进程分离）
‌崩溃隔离‌ ✅ 单个网页崩溃不影响应用进程 ⚠️ 部分版本支持，稳定性一般 ✅ 单个网页崩溃不影响应用进程
‌内核更新‌ 随系统 OTA 统一推送 通过 Google Play 独立更新 随 iOS 系统版本更新
‌开发语言‌ ArkTS（ArkUI 声明式框架） Java/Kotlin Swift/Objective-C
‌控制器‌ WebviewController WebViewClient + WebChromeClient WKNavigationDelegate + WKUIDelegate
‌首屏渲染速度‌ 提升约 40%（相比传统方案） 基准水平 基准水平
‌内存占用‌ 降低约 30%（相比传统方案） 较高 中等
‌滚动流畅度‌ 提升约 30%（复杂 H5 页面） 一般 较好
‌预加载能力‌ ✅ prepareForPageLoad（预连接）✅ prefetchPage（预加载） ⚠️ 需自行实现 ⚠️ 需自行实现
‌跨平台框架适配‌ 使用 uni.createWebviewContext无 plus 环境 使用 plus.webview 使用 plus.webview
‌消息传递格式‌ e.detail.data.data（多一层包装） e.detail.data e.detail.data
‌URL 安全管控‌ ✅ 系统级白名单 setUrlTrustList自动校验所有加载及跳转 URL ⚠️ 需开发者手动拦截 ⚠️ 需开发者手动拦截
‌深色模式‌ ✅ 支持强制深色模式可设置 backgroundColor 适配 ⚠️ 需自行适配 ✅ 支持
‌文件预览‌ ✅ 支持在线/本地 PDF需开启 domStorageAccess ✅ 支持 ✅ 支持
‌分布式能力‌ ✅ 深度适配鸿蒙全场景分布式能力 ❌ 不支持 ❌ 不支持
‌权限模型‌ 鸿蒙权限体系（ohos.permission.INTERNET） Android 权限体系 iOS 权限体系
‌内核版本选择‌ 支持 M132（常青）和 M114（兼容）双版本 跟随系统或独立更新 跟随系统版本
‌离线包方案‌ ✅ 支持通过 resource 协议加载本地资源 ✅ 支持 ✅ 支持
‌DOM Storage‌ ✅ 支持，需配置 domStorageAccess ✅ 支持 ✅ 支持
‌混合内容加载‌ ✅ 支持，需配置 mixedMode ✅ 支持 ✅ 支持
‌长按菜单自定义‌ ✅ 支持自定义 ✅ 支持 ✅ 支持
‌适用场景‌ 鸿蒙原生应用开发 Android 原生应用开发 iOS 原生应用开发
FEATURED TAGS
Harmony
FRIENDS