Flutter 在 OpenHarmony 中利用 package:web 进行 DOM 与 JS 互操作

前言

随着 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);
}