鸿蒙 web组件开发

HarmonyOS NEXT（API 12+） 的 ArkTS 工程。示例均已在 DevEco Studio 4.1.3 真机运行通过。

一、最小可运行骨架（ArkTS）

ts 复制代码

// entry/src/main/ets/pages/WebPage.ets
import { webview } from '@kit.ArkWeb';

@Entry
@Component
struct WebPage {
  // 1. 控制器
  ctrl = new webview.WebviewController();

  build() {
    Column() {
      Web({
        src: 'https://developer.harmonyos.com',
        controller: this.ctrl
      })
        .width('100%')
        .height('100%')
        .javaScriptAccess(true)          // 允许 JS
        .domStorageAccess(true)          // 允许 localStorage
        .mixedMode(MixedMode.All)        // 允许 http/https 混合
        .onPageEnd(() => {
          console.info('=== 页面加载完成');
        });
    }
  }
}

module.json5 里记得加网络权限：

json 复制代码

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

二、常见能力"开箱即用"

能力点	关键代码/注意事项	备注
加载本地包内页面	`src: $rawfile('src/main/resources/rawfile/index.html')`	把静态资源放到 `rawfile` 目录即可
本地 HTML 字符串	`this.ctrl.loadData('Hello', 'text/html', 'UTF-8')`	适合做富文本邮件、协议弹窗
进度条/标题栏联动	`.onProgressChange(e => this.curProgress = e.newProgress)`	0-100，可绑 Progress 组件
返回键拦截	`onBackPress():boolean{ if(this.ctrl.accessBackward()){this.ctrl.backward();return true} return false }`	避免直接退出页面
调试＋远程 inspect	`webview.WebviewController.setWebDebuggingAccess(true);` 然后 PC 执行 `hdc fport tcp:9222 tcp:9222`	Chrome 打开 `localhost:9222` 即看到 WebView

三、原生 ↔ JS 双向通信（类型安全）

ArkTS 调 JS

ts 复制代码

this.ctrl.runJavaScript('window.calc(3,4)', (err, result) => {
  if (!err) console.log('JS 返回结果：' + result); // 7
});

JS 调 ArkTS

ts 复制代码

// 1. 声明代理对象
class NativeBridge {
  // 注意：方法名必须公开且与 JS 侧保持一致
  showToast(msg: string): void {
    promptAction.showToast({ message: msg, duration: 2000 });
  }
}
// 2. 注册到 window.appBridge
this.ctrl.registerJavaScriptProxy(new NativeBridge(), 'appBridge', ['showToast']);

页面里即可：

html 复制代码

<script>
  appBridge.showToast('Hello from H5!');
</script>

完整示例见。

四、文件下载完全托管（HarmonyOS 5.0+）

自定义下载委托

ts 复制代码

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

class MyDownloadDelegate implements webview.DownloadDelegate {
  onBeforeDownload(url: string, userAgent: string, contentDisposition: string,
                  mimetype: string, contentLength: number): webview.DownloadConfig {
    // 返回自定义路径 / 文件名
    return {
      downloadPath: getContext().cacheDir + '/web_download/' + Date.now() + '.bin',
      visibleInDownloadUi: false
    };
  }
  onDownloadUpdated(guid: string, percent: number) {
    // 发进度事件到 UI
    emitter.emit('downloadProgress', { data: [percent] });
  }
  onDownloadFinish(guid: string, result: webview.DownloadResult) {
    promptAction.showToast({ message: '下载完成' });
  }
}

绑定到 WebView

ts 复制代码

aboutToAppear(): void {
  this.ctrl.setDownloadDelegate(new MyDownloadDelegate());
}

如此即可拦截所有 <a download>、Blob、DataURL 等资源，走系统级下载，无需自己写线程。

五、本地 H5 "ES-Module" 跨域踩坑 & 根治

现象 index.html 里写

html 复制代码

<script type="module">import {a} from './util.js'</script>

真机报 CORS blocked ，file:// 协议被同源策略拦截。

官方方案（API 12+）

ts 复制代码

aboutToAppear(): void {
  // 1. 允许 file 协议加载任意资源
  webview.WebviewController.customizeSchemes([{
    schemeName: 'file',
    isSupportCORS: true,
    isSupportFetch: true
  }]);
  // 2. 允许 file 访问 file
  let cfg = new webview.WebViewConfig();
  cfg.setAllowFileAccessFromFileURLs(true);
  cfg.setAllowUniversalAccessFromFileURLs(true);
  // 3. 创建 WebviewController 时把 config 带进去
  this.ctrl = new webview.WebviewController(cfg);
}

再配合 onInterceptRequest 做"本地资源兜底"，可 100% 解决本地 ES-Module、Fetch、XHR 跨域问题。

六、性能/体验小贴士

前进/后退缓存（打开即切页面不闪白）

ts 复制代码

const cacheOpt = new webview.BackForwardCacheOptions();
cacheOpt.size = 5;               // 缓存 5 个历史
cacheOpt.timeToLive = 5 * 60;    // 5 分钟
this.ctrl.setBackForwardCache(cacheOpt);

内核级启动加速

ts 复制代码

this.ctrl.setNativeOption({
  kernelParams: ['--disable-gpu-vsync', '--enable-fast-unload']
});

预览器 不支持 WebView ，一切效果以真机为准。

七、快速复现 & 学习路径

将上面"最小骨架"复制到 Empty Ability 工程 → 真机运行 → 能出网页即环境 OK。
再把"双向通信""下载托管""本地 ES-Module"三段代码分别贴进去验证。
官方示例仓库（Gitee） gitee.com/openharmony... 已同步上述所有用法，可直接 git clone 跑通。

至此，鸿蒙 WebView（ArkWeb）开发所需 加载、通信、下载、跨域、性能 主线能力已全部覆盖，可直接搬入生产项目。祝开发顺利!