Flutter package:web 在 OpenHarmony 中的 Wasm GC 与 DOM 互操作

前言

随着 Flutter 3.x 全面拥抱 Wasm（WebAssembly），Dart 团队推出了全新的 package:web 来取代老旧的 dart:html。 package:web 是基于最新的 JS Interop 机制构建的，它不仅性能更好，而且兼容 Wasm GC 标准。

虽然这个库通过名字看是为'Web'平台的，但对于 OpenHarmony 开发者来说，了解它有着特殊的意义：

1. 混合开发：鸿蒙原生支持 ArkWeb (WebView)，在 Flutter 中通过 JS 互操作与 Web 页面交互是常见需求。
2. 架构演进：理解 package:web 的设计有助于理解 Dart 如何与宿主环境（无论是 Browser 还是 Embedder）进行高效通信。

（注：本库主要用于 Flutter Web 目标平台。在鸿蒙 App 原生端，通常使用 flutter_inappwebview 或 js 库进行 JS 交互。但如果你的鸿蒙应用采用了'Flutter Web 运行在鸿蒙 WebView 中'的架构，本库就是核心）。

一、核心原理

package:web 不再封装很重的 Dart 对象，而是直接将 Dart 类型映射到 JS 对象（Zero-cost interop）。

@JS() Annotation

Wasm / JS

Dart Code

JS Interop Layer

浏览器 DOM / JS Context

二、OpenHarmony 适配说明

场景一：Flutter App 编译为 HAP (原生)
此时 package:web不可用，因为底层没有 V8/SpiderMonkey 引擎环境。你应该使用 plugin 机制与 ArkTS 通信。

场景二：Flutter Web 运行在鸿蒙浏览器/WebView
此时 package:web完全可用，且是官方推荐方案。你可以用它来调用鸿蒙浏览器暴露给 JS 的特殊能力。

三、基础用例 (Web 环境)

3.1 操作 DOM (新一代 API)

import 'package:web/web.dart' as web;

void main() {
  // 💡 无需 dart:html，直接操作宿主 DOM
  final div = web.document.createElement('div') as web.HTMLDivElement;
  div.innerText = 'Hello from Modern Dart Web!';
  div.style.backgroundColor = 'blue';
  web.document.body?.append(div);
}

3.2 调用 JS 函数

// 假设 JS 环境中有一个函数：function showAlert(msg) { alert(msg); }
import 'dart:js_interop';

@JS()
external void showAlert(JSString message);

void callJs() {
  showAlert('HarmonyOS Web'.toJS);
}

四、完整实战示例：鸿蒙 ArkWeb 中的 JS 互操作

本示例展示了在 Flutter Web 编译模式下，如何利用 package:web 与鸿蒙宿主环境进行高效通信。

import 'dart:js_interop';
import 'package:web/web.dart' as web;

// 💡 模拟鸿蒙系统注入的全局 JS 桥接对象
@JS('OhosBridge')
extension type OhosBridge._(JSObject _) implements JSObject {
  external static JSString getDeviceId();
  external static void onActionSuccess(JSString data);
}

void callHarmonyOS() {
  // 1. 检查对象是否存在
  if (web.window.has('OhosBridge')) {
    // 2. 直接获取设备 ID
    final id = OhosBridge.getDeviceId().toDart;
    print('✅ 获取到鸿蒙设备 ID: $id');
  }
}

五、总结

package:web 是 Dart 迈向 Wasm 时代的关键一步。 虽然它主要面向 Web 平台，但在'大前端'融合的今天，鸿蒙应用中嵌入 Web 页面、小程序的情况比比皆是。掌握新一代的 JS 互操作技术，能让你在混合架构开发中游刃有余。