鸿蒙开发：Web页面适配

ArkWeb组件助力应用集成Web页面，支持浏览器浏览、小程序渲染等功能。通过WebviewController实现双向交互：应用侧可通过runJavaScript调用前端函数，前端通过javaScriptProxy调用应用侧方法。示例展示了本地HTML集成、深色模式适配、双向方法调用等实战场景，包括改变文本颜色、参数传递等交互功能。使用异步渲染模式提升性能，注意及时删除注册对象防止内存泄漏。

汉堡黄

722人浏览 · 2025-11-21 10:37:58

汉堡黄 · 2025-11-21 10:37:58 发布

🎯 Web页面适配

⭐⭐⭐⭐

📌 见解

ArkWeb（方舟Web）提供了Web组件，用于在应用程序中显示Web页面内容

🎬 使用场景

应用集成Web页面： 应用可以在页面中使用Web组件，嵌入Web页面内容，以降低开发成本，提升开发、运营效率
浏览器网页浏览场景： 浏览器类应用可以使用Web组件，打开三方网页，使用无痕模式浏览Web页面，设置广告拦截等
小程序： 小程序类宿主应用可以使用Web组件，渲染小程序的页面，实现同层渲染，视频托管等小程序的功能

🧩 拆解

⚠️ 注意

应用侧调用前端页面函数： 应用侧可以通过runJavaScript()和runJavaScriptExt()方法调用前端页面的JavaScript相关函数
前端页面调用应用侧函数： 一种在Web组件初始化调用，使用 javaScriptProxy()接口。另外一种在Web组件初始化完成后调用，使用registerJavaScriptProxy()接口。两种方式都需要和deleteJavaScriptRegister接口配合使用，防止内存泄漏

🔥🔥🔥 实战环节

创建本地html src/main/resources/rawfile/index.html

<!-- index.html -->
<!DOCTYPE html>
<html>
<head>
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <style type="text/css">
        /* 默认样式 */
        body {
            background-color: White;
            color: Black;
        }


        /* 浅色样式，Web关闭深色模式时覆盖默认样式 */
        @media (prefers-color-scheme: light) {
            body {
                background-color: White;
                color: Black;
            }
        }

        /* 深色样式，Web开启深色模式时覆盖默认样式 */
         @media (prefers-color-scheme: dark) {
            body {
                background-color: Black;
                color: White;
            }
        }
    </style>
</head>
<body>
<button type="button" onclick="handleFromArkFunc()" class="textColor">前端点击-弹出应用弹窗</button>
<h1 id="text" class="textColor">汉堡黄（测试颜色改变）</h1>
<p id="pdemo" class="textColor">应用参数</p>
<script>
    // 改变前端文本组件颜色
    function changeTextColor() {
        document.getElementById('text').style.color = 'blue'
    }

    // 应用传递给前端的参数弹窗
    function changeTest(param) {
        document.getElementById('pdemo').innerHTML = param
    }

    // 处理
    function handleFromArkFunc() {
        testFunc.showToast()
    }
</script>
</body>
</html>

视图使用

import { webview } from '@kit.ArkWeb'

class TestClass {
  uiContext: UIContext | undefined = undefined

  constructor(uiContext: UIContext) {
    this.uiContext = uiContext
  }

  showToast() {
    this.uiContext?.getPromptAction().showToast({ message: '点击成功' })
  }
}

@Entry
@Component
struct WebViewCase {
  webviewController: webview.WebviewController = new webview.WebviewController()
  @State testClass: TestClass = new TestClass(this.getUIContext())
  private javaScriptProxyName: string = 'testFunc'

  aboutToAppear() {
    // 配置Web开启调试模式
    webview.WebviewController.setWebDebuggingAccess(true)
  }

  aboutToDisappear(): void {
    // 删除通过registerJavaScriptProxy注册到window上的指定name的应用侧JavaScript对象。删除后，须调用refresh接口
    this.webviewController.deleteJavaScriptRegister(this.javaScriptProxyName)
    this.webviewController.refresh()
  }

  build() {
    Column() {
      Column({ space: 10 }) {
        Button('改变前端文本组件颜色')
          .onClick(() => {
            this.webviewController.runJavaScript('changeTextColor()')
          })
        Button('传递参数给前端页')
          .onClick(() => {
            this.webviewController.runJavaScript('changeTest("来自应用端的参数")', (err) => {
              // 回调执行JavaScript脚本结果
              console.info(JSON.stringify(err))
            })
          })
      }
      .padding({ left: 10, right: 10 })

      Web({
        src: $rawfile('index.html'),
        controller: this.webviewController,
        renderMode: RenderMode.ASYNC_RENDER // 建议使用异步渲染模式，异步渲染模式有更好的性能和更低的功耗
      })
        .layoutMode(WebLayoutMode.FIT_CONTENT) // 设置为Web组件大小自适应页面内容
        .overScrollMode(OverScrollMode.NEVER) // 设置滚动模式
        .darkMode(WebDarkMode.Auto) // 跟随系统：设置Web深色模式。当属性没有显式调用时，默认Web深色模式关闭
        .forceDarkAccess(true) // 设置网页是否开启强制深色模式
        // 将对象注入到web端
        .javaScriptProxy({
          object: this.testClass,
          name: this.javaScriptProxyName, // 注册对象的名称，与window中调用的对象名一致
          methodList: ['showToast'], // 方法列表
          controller: this.webviewController,
        })
        .onPageEnd(() => {
          // TODO:按需使用 this.webviewController.setScrollable(false)// 页面加载完成后禁用滚动
        })
    }
    .width('100%')
    .height('100%')
  }
}