Flutter js_wrapping库鸿蒙适配方案详解

1. 为什么需要将js_wrapping适配到鸿蒙？

在Flutter生态中，js_wrapping库扮演着桥梁角色，它实现了Dart与JavaScript对象间的双向互操作。这个库的核心价值在于：

• 自动生成类型安全的包装层代码
• 支持Dart与JS对象的属性映射
• 提供强类型回调机制
• 实现双向方法调用

当我们需要将Flutter应用迁移到鸿蒙平台时，原有的JavaScript交互层面临重大挑战。鸿蒙的ArkCompiler采用方舟编译器，其JS运行时环境与标准V8引擎存在显著差异：

这种底层差异导致直接使用原js_wrapping库会出现以下典型问题：

1. 属性访问器失效（如obj.property）
2. 方法调用签名不匹配
3. 回调函数上下文丢失
4. 类型转换异常

实际案例：在鸿蒙上调用window.navigator.userAgent时，传统JS交互方式会抛出"undefined is not a function"错误，这正是因为ArkCompiler对浏览器API的封装方式不同。

2. 适配方案设计与核心改造点

2.1 架构层适配策略

我们需要在保持原有API设计的前提下，重构底层交互机制。整体架构调整为：

code复制Dart层 (Flutter)
│
├── 接口适配层 (保持原js_wrapping API)
│   │
│   └── 平台抽象层 (新增)
│       │
│       ├── Android/iOS实现 (原V8交互)
│       │
│       └── HarmonyOS实现 (新增ArkCompiler交互)
│
└── 代码生成器 (改造模板)

关键改造点包括：

1. 类型系统映射表重建：

   dart复制// 原V8类型映射
   final _typeMap = {
     'String': (jsVal) => jsVal.toString(),
     'num': (jsVal) => jsVal.toDouble(),
   };
   
   // 鸿蒙新类型映射
   final _harmonyTypeMap = {
     'String': (arkVal) => arkVal.getString(),
     'int': (arkVal) => arkVal.getInt(),
     'double': (arkVal) => arkVal.getDouble(),
   };
   

2. 对象生命周期管理：

   dart复制// 新增Ark对象引用计数器
   class ArkObjectRef {
     final int _handle;
     int _refCount = 0;
     
     void retain() {
       _refCount++;
       _nativeRetain(_handle);
     }
     
     void release() {
       _refCount--;
       _nativeRelease(_handle);
       if (_refCount <= 0) {
         _dispose();
       }
     }
   }
   

2.2 回调机制的重构

原库的回调处理依赖V8的FunctionTemplate，在鸿蒙上需要改为Ark的NativeCallback：

dart复制// 改造后的回调处理器
class HarmonyCallback {
  static final _callbacks = <int, Function>{};
  
  static void register(int id, Function fn) {
    _callbacks[id] = fn;
  }
  
  static dynamic invoke(int id, List<dynamic> args) {
    return _callbacks[id]?.call(args);
  }
}

// 原生侧注册
extern "C"
void Java_com_example_ArkBridge_registerCallback(
  JNIEnv* env, 
  jobject thiz,
  jint callbackId,
  jobject callback
) {
  // 将Java回调转为Native存储
}

2.3 代码生成器的改造

修改mustache模板文件以适应鸿蒙的API规范：

javascript复制// 原模板片段
{{#properties}}
  {{name}}() {
    return _jsObject.{{name}};
  }
{{/properties}}

// 鸿蒙适配模板
{{#properties}}
  {{name}}() {
    return _arkObject.getProperty("{{name}}");
  }
{{/properties}}

3. 具体实现步骤详解

3.1 环境准备与依赖配置

首先在pubspec.yaml中添加鸿蒙专用配置：

yaml复制dependencies:
  js_wrapping:
    git:
      url: https://gitee.com/harmony-adapted/js_wrapping
      ref: harmony
      path: packages/js_wrapping

flutter:
  module:
    androidPackage: com.example.harmony_bridge
    iosBundleIdentifier: com.example.harmonyBridge
    harmonyConfig:
      arkVersion: 3.1.0+
      jsRuntime: ark_js

3.2 核心适配层实现

创建harmony_bridge.dart作为平台抽象层：

dart复制abstract class JsInterop {
  dynamic eval(String code);
  dynamic getProperty(dynamic obj, String name);
  dynamic invokeMethod(dynamic obj, String method, List<dynamic> args);
}

class HarmonyInterop implements JsInterop {
  final _channel = MethodChannel('harmony_js');
  
  @override
  dynamic eval(String code) {
    return _channel.invokeMethod('evaluate', code);
  }
  
  @override
  dynamic getProperty(dynamic obj, String name) {
    return _channel.invokeMethod('getProperty', {
      'handle': (obj as ArkObjectRef)._handle,
      'name': name
    });
  }
  
  @override
  dynamic invokeMethod(dynamic obj, String method, List<dynamic> args) {
    return _channel.invokeMethod('invokeMethod', {
      'handle': (obj as ArkObjectRef)._handle,
      'method': method,
      'args': _serializeArgs(args)
    });
  }
}

3.3 类型序列化处理

实现跨平台类型转换器：

dart复制class HarmonyTypeSerializer {
  static dynamic serialize(dynamic value) {
    if (value is num) {
      return {'type': 'number', 'value': value};
    } else if (value is String) {
      return {'type': 'string', 'value': value};
    } else if (value is bool) {
      return {'type': 'boolean', 'value': value};
    } else if (value is ArkObjectRef) {
      return {'type': 'object', 'handle': value._handle};
    } else if (value is Function) {
      final id = _nextCallbackId++;
      HarmonyCallback.register(id, value);
      return {'type': 'function', 'id': id};
    }
    throw ArgumentError('Unsupported type: ${value.runtimeType}');
  }
  
  static dynamic deserialize(Map<dynamic, dynamic> data) {
    switch (data['type']) {
      case 'number': return data['value'] as num;
      case 'string': return data['value'] as String;
      case 'boolean': return data['value'] as bool;
      case 'object': return ArkObjectRef(data['handle'] as int);
      case 'function': 
        return (...args) => HarmonyCallback.invoke(data['id'], args);
      default: throw ArgumentError('Unknown type: ${data['type']}');
    }
  }
}

4. 实战验证与性能优化

4.1 基础功能测试用例

创建测试用例验证核心功能：

dart复制@JS()
library harmony_test;

import 'package:js_wrapping/js_wrapping.dart';

@JS()
class TestObject {
  external factory TestObject();
  external String get name;
  external set name(String value);
  external String greet(String who);
}

void main() {
  final interop = HarmonyInterop();
  interop.eval('''
    class TestObject {
      constructor() { this._name = 'Harmony'; }
      get name() { return this._name; }
      set name(v) { this._name = v; }
      greet(who) { return `Hello ${who} from ${this._name}`; }
    }
    globalThis.TestObject = TestObject;
  ''');

  final obj = TestObject();
  print(obj.name); // 输出: Harmony
  obj.name = 'OpenHarmony';
  print(obj.greet('Developer')); // 输出: Hello Developer from OpenHarmony
}

4.2 性能关键指标对比

在华为MatePad Pro上测试结果：

4.3 内存管理最佳实践

针对鸿蒙的静态内存特性，推荐以下模式：

dart复制class ManagedArkObject {
  final ArkObjectRef _ref;
  final List<Function> _cleanups = [];
  
  ManagedArkObject(this._ref);
  
  void registerDispose(Function fn) {
    _cleanups.add(fn);
  }
  
  void dispose() {
    for (final fn in _cleanups) {
      fn();
    }
    _ref.release();
  }
}

// 使用示例
void fetchData() {
  final obj = ManagedArkObject(ArkObjectRef.create());
  obj.registerDispose(() => print('清理资源'));
  
  try {
    // 使用obj...
  } finally {
    obj.dispose();
  }
}

5. 常见问题解决方案

5.1 类型转换异常处理

当遇到类型不匹配时，可以扩展类型转换器：

dart复制extension TypeConversionExt on dynamic {
  T asType<T>() {
    if (this is T) return this as T;
    
    if (T == String) return toString() as T;
    if (T == num) {
      if (this is String) return num.tryParse(this) ?? 0 as T;
      return (this ?? 0) as T;
    }
    
    throw ArgumentError('Cannot convert ${runtimeType} to $T');
  }
}

// 使用方式
final value = arkObject.getProperty('count').asType<int>();

5.2 回调丢失上下文问题

通过绑定技术保持上下文：

dart复制class ContextKeeper {
  final Function _fn;
  final dynamic _context;
  
  ContextKeeper(this._fn, this._context);
  
  dynamic call([List<dynamic> args = const []]) {
    return Function.apply(_fn, [_context, ...args]);
  }
}

// 注册回调时
final keeper = ContextKeeper(callback, this);
HarmonyCallback.register(id, keeper.call);

5.3 多线程访问冲突

使用原子操作保证线程安全：

dart复制import 'dart:ffi';
import 'package:ffi/ffi.dart';

final _mutex = allocate<Int32>();
final _lock = DynamicLibrary.process().lookupFunction<
  Void Function(Pointer<Int32>),
  void Function(Pointer<Int32>)
>('os_mutex_lock');

final _unlock = DynamicLibrary.process().lookupFunction<
  Void Function(Pointer<Int32>),
  void Function(Pointer<Int32>)
>('os_mutex_unlock');

void safeAccess(void Function() action) {
  _lock(_mutex);
  try {
    action();
  } finally {
    _unlock(_mutex);
  }
}

6. 进阶应用场景

6.1 与鸿蒙原生组件交互

实现Flutter与ArkUI的深度集成：

dart复制@JS()
class ArkUIComponent {
  external factory ArkUIComponent(String tagName);
  external void setAttribute(String name, dynamic value);
  external void addEventListener(String event, Function handler);
  external dynamic get boundingClientRect;
}

// 创建原生组件
final div = ArkUIComponent('div')
  ..setAttribute('width', '100%')
  ..addEventListener('click', (event) {
    print('Clicked at ${event['clientX']}, ${event['clientY']}');
  });

// 获取布局信息
final rect = div.boundingClientRect;
print('Component size: ${rect['width']}x${rect['height']}');

6.2 性能敏感场景优化

对于高频调用的场景，使用直接内存访问：

dart复制final _nativeAccess = DynamicLibrary.process().lookupFunction<
  Pointer<Void> Function(Int32 handle),
  Pointer<Void> Function(int handle)
>('ark_get_object_ptr');

class DirectAccessObject {
  final Pointer<Void> _ptr;
  
  DirectAccessObject(int handle) : _ptr = _nativeAccess(handle);
  
  dynamic getProperty(String name) {
    final result = _ptr.cast<Utf8>().toDartString();
    return _deserializeNative(result);
  }
  
  void setProperty(String name, dynamic value) {
    final json = _serializeToNative(value);
    _ptr.cast<Utf8>().fromDartString(json);
  }
}

6.3 插件化扩展机制

允许第三方扩展功能：

dart复制typedef HarmonyExtension = dynamic Function(dynamic input);

final _extensions = <String, HarmonyExtension>{};

void registerExtension(String name, HarmonyExtension extension) {
  _extensions[name] = extension;
}

dynamic invokeExtension(String name, dynamic input) {
  return _extensions[name]?.call(input);
}

// 使用示例
registerExtension('crypto', (data) {
  return sha256.convert(data.codeUnits);
});

final hash = invokeExtension('crypto', 'password123');