Fusion

OS	Android	iOS	HarmonyOS
SDK	5.0(21)+	11.0+	4.1(11)+

简介

Fusion 是新一代的混合栈管理框架，用于 Flutter 与 Native 页面统一管理，并支持页面通信、页面生命周期监听等功能。Fusion 即 融合，我们的设计初衷就是帮助开发者在使用 Flutter 与 Native 进行混合开发时尽量感受不到两者的隔阂，提升开发体验。此外，Fusion 彻底解决了混合开发过程中普遍存在的黑屏、白屏、闪屏等问题，更加适合重视用户体验的App使用。

从 4.0 开始，Fusion 已完成纯鸿蒙平台（HarmonyOS Next/OpenHarmony，以下简称 HarmonyOS）的适配，开发者可以在Android、iOS、HarmonyOS上得到完全一致的体验。（HarmonyOS 的 Flutter SDK 可以在这里获取）

Fusion 采用引擎复用方案，在 Flutter 与 Native 页面多次跳转情况下，APP 始终仅有一份 FlutterEngine 实例，因此拥有更好的性能和更低的内存占用。

Fusion 也是目前仅有的支持混合开发时应用在后台被系统回收后，所有Flutter页面均可正常恢复的混合栈框架。

开始使用

0、准备

在开始前需要按照 Flutter 官方文档，将 Flutter Module 项目接入到 Android、iOS、HarmonyOS 工程中。

1、初始化

Flutter 侧

使用 FusionApp 替换之前使用的 App Widget，并传入所需路由表，默认路由表和自定义路由表可单独设置也可同时设置。

void main() {
  runApp(FusionApp(
    // 默认路由表
    routeMap: routeMap,
    // 自定义路由表
    customRouteMap: customRouteMap,
  ));
}

// 默认路由表，使用默认的 PageRoute
// 使用统一的路由动画
final Map<String, FusionPageFactory> routeMap = {
  '/test': (arguments) => TestPage(arguments: arguments),
  kUnknownRoute: (arguments) => UnknownPage(arguments: arguments),
};

// 自定义路由表，可自定义 PageRoute
// 比如：某些页面需要特定的路由动画则可使用该路由表
final Map<String, FusionPageCustomFactory> customRouteMap = {
  '/mine': (settings) => PageRouteBuilder(
      opaque: false,
      settings: settings,
      pageBuilder: (_, __, ___) => MinePage(
          arguments: settings.arguments as Map<String, dynamic>?)),
};

P.S: kUnknownRoute表示未定义路由

注意：如果项目使用了 flutter_screenutil，需要在 runApp 前调用 Fusion.instance.install()，没有使用 flutter_screenutil则无须该步骤。

void main() {
  Fusion.instance.install();
  runApp(FusionApp(
    // 默认路由表
    routeMap: routeMap,
    // 自定义路由表
    customRouteMap: customRouteMap,
  ));
}

Android 侧

在 Application 中进行初始化，并实现 FusionRouteDelegate 接口

class MyApplication : Application(), FusionRouteDelegate {

    override fun onCreate() {
        super.onCreate()
        Fusion.install(this, this)
    }

    override fun pushNativeRoute(name: String?, arguments: Map<String, Any>?) {
        // 根据路由 name 跳转对应 Native 页面
    }

    override fun pushFlutterRoute(name: String?, arguments: Map<String, Any>?) {
        // 根据路由 name 跳转对应 Flutter 页面
        // 可在 arguments 中存放参数判断是否需要打开透明页面
    }
}

iOS 侧

在 AppDelegate 中进行初始化，并实现 FusionRouteDelegate 代理

@UIApplicationMain
@objc class AppDelegate: UIResponder, UIApplicationDelegate, FusionRouteDelegate {
    
    func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
      ...
      Fusion.instance.install(self)
      ...
    return true
  }
    
    func pushNativeRoute(name: String?, arguments: Dictionary<String, Any>?) {
        // 根据路由 name 跳转对应 Native 页面
    }
    
    func pushFlutterRoute(name: String?, arguments: Dictionary<String, Any>?) {
        // 根据路由 name 跳转对应 Flutter 页面
        // 可在 arguments 中存放参数判断是否需要打开透明页面
        // 可在 arguments 中存放参数判断是 push 还是 present
    }
}

HarmonyOS 侧

在 UIAbility 中进行初始化，并实现 FusionRouteDelegate 代理

export default class EntryAbility extends UIAbility implements FusionRouteDelegate {
  private static TAG = 'EntryAbility'
  private mainWindow: window.Window | null = null
  private windowStage: window.WindowStage | null = null

  override async onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): Promise<void> {
    await Fusion.instance.install(this.context, this)
    GeneratedPluginRegistrant.registerWith(Fusion.instance.defaultEngine!)
  }

  pushNativeRoute(name: string, args: Map<string, Object> | null): void {
    // 根据路由 name 跳转对应 Native 页面
  }

  pushFlutterRoute(name: string, args: Map<string, Object> | null): void {
    // 根据路由 name 跳转对应 Flutter 页面
    // 可在 arguments 中存放参数判断是否需要打开透明页面
  }
}

2、Flutter 容器

普通页面模式

Android 侧

通过 FusionActivity（或其子类）创建 Flutter 容器，启动容器时需要使用 Fusion 提供的 buildFusionIntent 方法，其中参数 transparent 需设为 false。其 xml 配置参考如下（如果使用 FusionActivity 则不用配置）：

        <activity
            android:name=".CustomFusionActivity"
            android:configChanges="orientation|keyboardHidden|keyboard|screenSize|smallestScreenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode"
            android:exported="false"
            android:hardwareAccelerated="true"
            android:launchMode="standard"
            android:theme="@style/FusionNormalTheme"
            android:windowSoftInputMode="adjustResize" />

iOS 侧

通过 FusionViewController （或其子类）创建 Flutter 容器，push 和 present 均支持。FusionViewController 默认隐藏了 UINavigationController。

在 iOS 中需要处理原生右滑退出手势和 Flutter 手势冲突的问题，解决方法也很简单：只需在自定义的 Flutter 容器中实现 FusionPopGestureHandler 并在对应方法中启用或者关闭原生手势即可，这样可以实现如果当前 Flutter 容器存在多个 Flutter 页面时，右滑手势是退出 Flutter 页面，而当 Flutter 页面只有一个时则右滑退出 Flutter 容器。

    // 启用原生手势
    func enablePopGesture() {
        // 以下代码仅做演示，不可直接照搬，需根据APP实际情况自行实现
        navigationController?.interactivePopGestureRecognizer?.isEnabled = true
    }

    // 关闭原生手势
    func disablePopGesture() {
        // 以下代码仅做演示，不可直接照搬，需根据APP实际情况自行实现
        navigationController?.interactivePopGestureRecognizer?.isEnabled = false
    }

HarmonyOS 侧

通过 FusionEntry（或其子类）创建 Flutter 容器，启动容器时需要使用 Fusion 提供的 buildFusionParams 方法，也可直接使用 FusionPage。默认全屏模式。

    const params = buildFusionParams(name, args, false, backgroundColor)
    this.mainLocalStorage?.setOrCreate('params', params)
    router.pushNamedRoute({name: FusionConstant.FUSION_ROUTE_NAME})

透明页面模式

Android 侧

使用方式与普通页面模式相似，只是buildFusionIntent 方法的参数 transparent 需设为 true，其 xml 配置参考如下：

        <activity
            android:name=".TransparentFusionActivity"
            android:configChanges="orientation|keyboardHidden|keyboard|screenSize|smallestScreenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode"
            android:exported="false"
            android:hardwareAccelerated="true"
            android:launchMode="standard"
            android:theme="@style/FusionTransparentTheme"
            android:windowSoftInputMode="adjustResize" />

iOS 侧

使用方式与普通页面模式相似：

let fusionVc = CustomViewController(routeName: name, routeArguments: arguments, transparent: true)
navController?.present(fusionVc, animated: false)

HarmonyOS 侧

使用方式与普通页面模式相似：

    const params = buildFusionParams(name, args, true, backgroundColor)
    this.windowStage?.createSubWindow(FusionConstant.TRANSPARENT_WINDOW, (_, win) => {
      const record: Record<string, Object> = {
        'params': params
      }
      win.loadContentByName(FusionConstant.FUSION_ROUTE_NAME, new LocalStorage(record))
      win.showWindow()
    })

Flutter 侧

同时Flutter页面背景也需要设置为透明

子页面模式

子页面模式是指一个或多个 Flutter 页面同时嵌入到 Native 容器中的场景，如：使用Tab切换Flutter和原生页面，Fusion 支持多个 Flutter 页面嵌入同一个 Native 容器中

Android 侧

使用 FusionFragment 以支持子页面模式，创建 FusionFragment 对象需要使用 buildFusionFragment 方法

iOS 侧

与页面模式一样使用 FusionViewController

HarmonyOS 侧

与页面模式一样使用 FusionEntry，配合 buildFusionParams方法配置参数

自定义容器背景色

默认情况下容器的背景为白色，这是因为考虑到绝大多数的页面都是使用白色背景，但如果打开的首个Flutter页面的背景是其他颜色，比如夜间模式下页面为深灰色，此时是为了更好的视觉效果，可以自定义容器的背景色与首个Flutter页面的背景色一致。

Android 侧

在 buildFusionIntent 和 buildFusionFragment方法中参数 backgroundColor 设为所需背景色

iOS 侧

在创建 FusionViewController （或其子类）对象时，参数 backgroundColor 设为所需背景色

HarmonyOS 侧

在 buildFusionParams方法中参数 backgroundColor 设为所需背景色

3、路由API（FusionNavigator）

push：将对应路由入栈，Navigator.pushNamed 与之等同，根据FusionRouteType分为以下几种方式：
- flutter模式: 在当前Flutter容器中将指定路由对应的Flutter页面入栈，如果没有则跳转kUnknownRoute对应Flutter页面
- flutterWithContainer模式: 创建一个新的Flutter容器，并将指定路由对应的Flutter页面入栈，如果没有则跳转kUnknownRoute对应Flutter页面。即执行FusionRouteDelegate的pushFlutterRoute
- native模式: 将指定路由对应的Native页面入栈，即执行FusionRouteDelegate的pushNativeRoute
- adaption模式: 自适应模式，默认类型。首先判断该路由是否是Flutter路由，如果不是则进入native模式，如果是再判断当前是否是页面是否是Flutter容器，如果是则进入flutter模式，如果不是则进入flutterWithContainer模式
pop：在当前Flutter容器中将栈顶路由出栈，Navigator.pop 与之等同
maybePop：在当前Flutter容器中将栈顶路由出栈，可被WillPopScope拦截
replace：在当前Flutter容器中将栈顶路由替换为对应路由，Navigator.pushReplacementNamed 与之等同
remove：在当前Flutter容器中移除对应路由

路由跳转与关闭等操作既可使用FusionNavigator的 API，也可使用Navigator中与之对应的API（仅上述提到的部分）

4、Flutter Plugin 注册

在 Android 和 iOS 平台上框架内部会自动注册插件，无须手动调用 GeneratedPluginRegistrant.registerWith 进行注册，但 HarmonyOS 必须手动调用该方法。

5、自定义 Channel

如果需要 Native 与 Flutter 进行通信，则需要自行创建 Channel，创建 Channel 方式如下（以 MethodChannel 为例）：

Android 侧

①、与容器无关的方法

在 Application 中进行注册

val channel = Fusion.defaultEngine?.dartExecutor?.binaryMessenger?.let {
    MethodChannel(
        it,
        "custom_channel"
    )
}
channel?.setMethodCallHandler { call, result -> 
}

②、与容器相关的方法

在自实现的 FusionActivity、FusionFragmentActivity、FusionFragment 上实现 FusionMessengerHandler 接口，在 configureFlutterChannel 中创建 Channel，在 releaseFlutterChannel 释放 Channel

class CustomActivity : FusionActivity(), FusionMessengerHandler {
  
    override fun configureFlutterChannel(binaryMessenger: BinaryMessenger) {
        val channel = MethodChannel(binaryMessenger, "custom_channel")
        channel.setMethodCallHandler { call, result -> 
            
        }
    }
  
    override fun releaseFlutterChannel() {
        channel?.setMethodCallHandler(null)
        channel = null
    }
}

iOS 侧

①、与容器无关的方法

在 AppDelegate 中进行注册

var channel: FlutterMethodChannel? = nil
if let binaryMessenger = Fusion.instance.defaultEngine?.binaryMessenger {
    channel = FlutterMethodChannel(name: "custom_channel", binaryMessenger: binaryMessenger)
}
channel?.setMethodCallHandler { (call: FlutterMethodCall, result: @escaping FlutterResult) in
}

②、与容器相关的方法

在自实现的 FusionViewController 上实现 FusionMessengerHandler 协议，在协议方法中创建 Channel

class CustomViewController : FusionViewController, FusionMessengerHandler {
    func configureFlutterChannel(binaryMessenger: FlutterBinaryMessenger) {
        channel = FlutterMethodChannel(name: "custom_channel", binaryMessenger: binaryMessenger)
        channel?.setMethodCallHandler { (call: FlutterMethodCall, result: @escaping FlutterResult) in
            
        }
    }
    
    func releaseFlutterChannel() {
        channel?.setMethodCallHandler(nil)
        channel = nil
    }
}

HarmonyOS 侧

①、与容器无关的方法

在 UIAbility 中进行注册

const binaryMessenger = Fusion.instance.defaultEngine?.dartExecutor.getBinaryMessenger()
const channel = new MethodChannel(binaryMessenger!, 'custom_channel')
channel.setMethodCallHandler({
  onMethodCall(call: MethodCall, result: MethodResult): void {
    
  }
})

②、与容器相关的方法

在自实现的 FusionEntry 上实现 FusionMessengerHandler 接口，在 configureFlutterChannel 中创建 Channel，在 releaseFlutterChannel 释放 Channel

export default class CustomFusionEntry extends FusionEntry implements FusionMessengerHandler, MethodCallHandler {
  private channel: MethodChannel | null = null

  configureFlutterChannel(binaryMessenger: BinaryMessenger): void {
    this.channel = new MethodChannel(binaryMessenger, 'custom_channel')
    this.channel.setMethodCallHandler(this)
  }

  onMethodCall(call: MethodCall, result: MethodResult): void {
    result.success(`Custom Channel：${this}_${call.method}`)
  }

  releaseFlutterChannel(): void {
    this.channel?.setMethodCallHandler(null)
    this.channel = null
  }
}

BasicMessageChannel 和 EventChannel 使用也是类似

P.S.: 与容器相关的方法是与容器生命周期绑定的，如果容器不可见或者销毁了则无法收到Channel消息。

6、生命周期

应用生命周期监听：

①、在 Flutter 侧任意处注册监听皆可，并implements FusionAppLifecycleListener
②、根据实际情况决定是否需要注销监听

void main() {
  ...
  FusionAppLifecycleBinding.instance.register(MyAppLifecycleListener());
  runApp(const MyApp());
}

class MyAppLifecycleListener implements FusionAppLifecycleListener {
  @override
  void onBackground() {
    print('onBackground');
  }

  @override
  void onForeground() {
    print('onForeground');
  }
}

FusionAppLifecycleListener 生命周期回调函数：

onForeground: 应用进入前台会被调用（首次启动不会被调用，Android 与 iOS 保持一致）
onBackground: 应用退到后台会被调用

页面生命周期监听：

①、在需要监听生命周期页面的 State 中 implements FusionPageLifecycleListener
②、在 didChangeDependencies 中注册监听
③、在 dispose 中注销监听

class LifecyclePage extends StatefulWidget {
  const LifecyclePage({Key? key}) : super(key: key);

  @override
  State<LifecyclePage> createState() => _LifecyclePageState();
}

class _LifecyclePageState extends State<LifecyclePage>
    implements FusionPageLifecycleListener {
  @override
  Widget build(BuildContext context) {
    return Container();
  }

  @override
  void didChangeDependencies() {
    super.didChangeDependencies();
    FusionPageLifecycleBinding.instance.register(this);
  }

  @override
  void onPageVisible() {}

  @override
  void onPageInvisible() {}

  @override
  void onForeground() {}

  @override
  void onBackground() {}

  @override
  void dispose() {
    super.dispose();
    FusionPageLifecycleBinding.instance.unregister(this);
  }
}

PageLifecycleListener 生命周期回调函数：

onForeground: 应用进入前台会被调用，所有注册了生命周期监听的页面都会收到
onBackground: 应用退到后台会被调用，所有注册了生命周期监听的页面都会收到
onPageVisible: 该 Flutter 页面可见时被调用，如：从 Native 页面或其他 Flutter 页面 push 到该 Flutter 页面时；从 Native 页面或其他 Flutter 页面 pop 到该 Flutter 页面时；应用进入前台时也会被调用。
onPageInvisible: 该 Flutter 页面不可见时被调用，如：从该 Flutter 页面 push 到 Native 页面或其他 Flutter 页面时；如从该 Flutter 页面 pop 到 Native 页面或其他 Flutter 页面时；应用退到后台时也会被调用。

7、全局通信

支持消息在应用中的传递，可以指定 Native 还是 Flutter 或者全局接收和发送。

注册消息监听

Flutter侧

①、在需要监听消息的类中 implements FusionNotificationListener，并复写 onReceive 方法，该方法可收到发送过来的消息
②、在合适时机注册监听
③、在合适时机注销监听

class TestPage extends StatefulWidget {

  @override
  State<TestPage> createState() => _TestPageState();
}

class _TestPageState extends State<TestPage> implements FusionNotificationListener {

  @override
  void onReceive(String name, Map<String, dynamic>? body) {
    
  }

  @override
  void didChangeDependencies() {
    super.didChangeDependencies();
    FusionNotificationBinding.instance.register(this);
  }

  @override
  void dispose() {
    super.dispose();
    FusionNotificationBinding.instance.unregister(this);
  }
}

Native侧

①、在需要监听消息的类中实现 FusionNotificationListener 接口，并复写 onReceive 方法，该方法可收到发送过来的消息
②、在适当时机使用 FusionNotificationBinding 的 register 方法注册监听
③、在适当时机使用 FusionNotificationBinding 的 unregister 方法注销监听

发送消息

三端均可使用FusionNavigator 的 sendMessage 方法来发送消息，根据使用FusionNotificationType 不同类型有不同效果：

flutter: 仅 Flutter 可以收到
native: 仅 Native 可以收到
global: Flutter 和 Native 都可以收到

8、返回拦截

在纯 Flutter 开发中可以使用WillPopScope组件拦截返回操作，Fusion 也完整支持该功能，使用方式与在纯 Flutter 开发完全一致，此外使用FusionNavigator.maybePop的操作也可被WillPopScope组件拦截。

9、状态恢复

Fusion 支持 Android 和 iOS 平台 APP 被回收后 Flutter 路由的恢复。

Fusion

简介

开始使用

0、准备

1、初始化

2、Flutter 容器

普通页面模式

透明页面模式

子页面模式

自定义容器背景色

3、路由API（FusionNavigator）

4、Flutter Plugin 注册

5、自定义 Channel

6、生命周期

7、全局通信

注册消息监听

发送消息

8、返回拦截

9、状态恢复

Libraries

fusion package