欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net

Flutter 三方库 js 的鸿蒙化适配指南 - 实现鸿蒙应用中 Dart 与 JavaScript 的极速双向互操作、打造跨平台 Web 插件的底层逻辑桥梁、赋能鸿蒙应用深度集成 Web 生态

前言

在鸿蒙（OpenHarmony）生态的开发过程中，虽然我们主要使用 Dart 和 ArkTS/C++ 协作，但随着鸿蒙对 Web 技术的深度融合（如元服务中大量嵌入 H5 片段，或是在鸿蒙浏览器环境中运行 Flutter Web），如何优雅地在 Dart 端调用现有的 JavaScript 库变得至关重要。js 库（即 package:js）是官方提供的用于定义 JS 互操作接口的行业标准方案。本文将详解如何在该库的加持下，打通鸿蒙 Flutter 应用与 JS 世界的任督二脉。

一 : 原原理析 / 概念介绍

1.1 基础原理/概念介绍

js 库使用 Dart 的注释注解（Annotations）机制。通过在 Dart 中声明带有 @JS() 注解的类和函数，编译器会自动生成底层的 JS 绑定代码，从而实现在不编写任何动态查找逻辑的情况下，直接以 Dart 对象的方式操作网页环境中的 JS 资源。

1.2 为什么在鸿蒙项目中使用它？

1. 类型安全：为原本松散的 JS 代码套上一层强类型的“铠甲”，显著降低在鸿蒙 Web 环境下的崩溃率。
2. 性能优异：通过静态编译实现互调，避免了 evaluateJavascript 这种字符串拼接方式的巨大开销。
3. 生态复用：直接在鸿蒙项目中接入现成的 JS 图表库（如 ECharts）、加密库或其他成熟的 Web SDK。

特性	通过 evalJavascript 调用	使用 package:js
交互方式	字符串拼接转换	原生对象方法调用
维护成本	极高（字符串难调试）	低（遵循 Dart 语法）
自动补全	无	有 (IDE 支持)

二 : 鸿蒙 Web 端基础指导

2.1 适配情况

1. 运行环境：主要针对其在鸿蒙浏览器环境下的运行（Flutter Web for OpenHarmony）。
2. 注意事项：无法在鸿蒙 Native AOT（即原生手机应用）中直接操作 JS 引擎，若需在原生 App 中与 WebView 通信，建议配合 flutter_inappwebview 使用。

2.2 核心定义逻辑

在鸿蒙工程中声明一个 JS 互操作类：

@JS()
library harmony_js_bridge;

import 'package:js/js.dart';

// 1. 定义与 JS 侧对应的构造函数
@JS('HarmonyTracker')
class HarmonyTracker {
  external HarmonyTracker(String appId);
  
  // 2. 定义可调用的成员方法
  external void trackEvent(String eventName);
}

// 3. 定义顶级 JS 函数
@JS('alert')
external void showHarmonyAlert(String message);

三 : 核心 API / 组件详解

3.1 跨语言匿名对象的创建

如何将 Dart 中的 Map 对象转换为 JS 环境可识别的 Anonymous 对象。

3.2 深度控制：处理 JS 异步回调（Promises to Futures）

import 'package:js/js_util.dart' as js_util;

Future<dynamic> callHarmonyAsyncJs(dynamic promise) {
  // 将 JS 的 Promise 转换为 Dart 可等待的 Future
  return js_util.promiseToFuture(promise);
}

四、典型应用场景

4.1 场景一：鸿蒙 Web 应用集成现成的登录 SDK

利用 JS 编写的单点登录（SSO）模块，在 Flutter Web 侧一键唤起。

// 汉化示例：触发登录逻辑
@JS('auth.login')
external void triggerJsLogin();

4.2 场景二：复杂 3D 渲染引擎在鸿蒙浏览器的协同

利用 Three.js 进行 3D 渲染，而逻辑控制由鸿蒙端的 Flutter 完成。

五 : OpenHarmony 平台适配挑战

5.1 变量名混淆（Minification）导致的调用失败

在进行鸿蒙 Web 端生产打包时，编译器会压缩变量名，导致 @JS() 找不到对应的 JS 对象。
解决方案：技巧：务必确认您的 JS 测变量已被挂载在 window 对象下，并在 Dart 定义中使用准确的包名路径，以防止被编译器随机重命名。

5.2 宿主环境的类型不一致（Number vs double/int）

JS 不区分整数和浮点数，这在强类型的鸿蒙 Dart 中偶尔会导致运行时类型转换异常。
优化建议：在处理 JS 返回的数值时，建议先使用 js_util.getProperty 获取原始引用，再手动进行类型转换。

六、综合实战演示

import 'package:flutter/material.dart';
import 'package:js/js.dart';

// 定义引用
@JS('console.log')
external void logToHarmonyConsole(String text);

class JsBridgeView extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('鸿蒙 JS 交互实验室')),
      body: Center(
        child: ElevatedButton(
          onPressed: () {
            // 直接调用定义好的外部 JS 函数
            logToHarmonyConsole("该消息将出现在鸿蒙浏览器的 F12 面板中");
          },
          child: Text("发送日志至 JS 端"),
        ),
      ),
    );
  }
}

七、总结

js 库为鸿蒙 Web 应用开发开启了“上帝视角”。它通过优雅的声明式语法，抹平了两种语言之间的鸿沟。在鸿蒙全场景、全栈化演进的过程中，掌握这种基于静态绑定的互操作技术，不仅能让您站在巨人的肩膀上复用现有的 Web 生态，更能助力构建出更加健壮、高性能的跨端 Web 应用。

[!TIP]
推荐在复杂的互操作场景中，配合 allowInterop 函数来安全地将 Dart 回调函数传递给 JS 环境，防止内存泄漏。