MXFlutter 接入指南

v0.8.0 主要更新

工程优化和开发方式变化

1. 开发语言切换到 TypeScript ：使用TS完整重构框架代码，带来了静态代码检查和代码自动提示。
2. 完整接入npm生态：重新设计拆分JS层框架模块，使用Monorepo模式组织模块的关联开发及npm发布。业务代码通过npm包引入框架。
3. 增加工程cli工具：一键创建业务初始工程。内置框架与业务的编译脚本，一键完成业务开发调试与编译打包。

框架逻辑优化

1. 支持了JS Widget的状态保持
2. 通过dart:ffi实现小数据量属性同步调用
3. 支持了异步Widget，同步Widget
4. 提供了更全面的TS Widget， 支持更多UI效果
5. 主框架支持更丰富的性能监控指标。首帧、页面刷新、FPS、Crash率等。
6. 适配 Flutter 1.20.3 版本

特别注意： 因为 v0.8.0 使用了 dart:ffi，mxflutter 作为静态库打包进宿主工程，在 iOS 打包发布时，Xcode 会把相关符号stripped，需要修改引用mxflutter的App proj Xcode配置，详细见Flutter官网说明 Strip Style 配置，否则会引起release archive (IPA)包 crash，对应 issue。后续 MXFlutter 会做成动态库形式，减少业务修改。

v0.8.0 介绍

从0.8.0版本开始，MXFlutter 最大的变化是开发语言切换到了 TypeScript，接入了npm生态，相比原来裸写JS的开发方式，向前端生态靠拢。这样就解决了之前版本最痛的没有代码提示和静态检查的问题。

所以 MXFlutter 目前分为两个部分，一个是发布在 npm 上的 mxflutter TypeScript 库，一个是 mxflutter flutter plugin。

开发方式变为三部曲：

• 第一步 在你的 Flutter 工程里引入 mxflutter flutter plugin。
• 第二步 用 mxflutter cli 工具新建一个TS的 mxflutter 工程。 这个工程是一个标准的 npm 包，开发完成之后编译输出JS Bundle文件。
• 第三步 把 TS 工程编译的bundle-xxx.js 放置在你的Flutter工程制定目录下，然后就可以调用 mxflutter 提供的接口打开 TS 页面了。

下面详细介绍接入步骤

接入指南

可以参考 https://github.com/mxflutter/MXFlutter/tree/master/mxflutter/example 完整例子。

第一步 在 Flutter 工程引入 MXFlutter Plugin

1. 添加依赖

因为mxflutter在快速迭代，推荐 fork 主库 https://github.com/mxflutter/mxflutter.git 来接入，方便自己修改和定期从主库的更新。

将下面内容添加到你 Flutter 工程的pubspec.yaml文件中：

  dependencies:
    mxflutter:
      git:
        url: https://github.com/mxflutter/mxflutter.git
        path: mxflutter/

2. 创建放置JS Bundle文件夹，在 pubspec.yaml 引入 JS Bundle资源

在 pubspec.yaml 文件同级目录下创建 mxflutter_js_bundle 文件夹，用于存放 TS 工程生成的JS bundle文件。

在 pubspec.yaml 文件中引入 mxflutter_js_bundle JS Bundle资源，如果不配置的话，mxflutter_js_bundle 不会被打包进入 App.apk或App.ipa，

 flutter:
   assets:
     - mxflutter_js_bundle/

完成后目录结构应该是这样的

my_flutter/
├── lib/
│   └── main.dart
└── pubspec.yaml
└── mxflutter_js_bundle/

3. 安装和检查

调用 flutter pub get 应该可以正确安装 mxflutter plugin

$ flutter pub get

第二步 设置 TypeScript 开发环境，新建 MXFlutter TS 工程

1. 先为将要新建的 TS 工程找个存放的地方

首先新建一个放置 TS 工程的文件夹， 可以把 MXFlutter TS 工程放在你的 Flutter 工程中，例如在 pubspec.yaml文件同级目录下新建 mxflutter-ts-proj 文件夹，（TS工程也可以放在其他地方，与 Flutter 工程用不同的 git 仓库管理,可以根据业务规模灵活处理）。

完成后目录结构是这样的

my_flutter/
├── lib/
│   └── main.dart
└── pubspec.yaml
└── mxflutter-ts-proj/
└── mxflutter_js_bundle/

2. 再新建 mxflutter TS 工程，配置输出目录

安装 mxflutter 的cli工具

npm install @mxflutter/mxflutter-toolchain@0.8.0 -g

先切换到放置 TS 工程的 mxflutter-ts-proj 为当前目录

cd mxflutter-ts-proj/ 

通过 mxflutter create 命令根据提示新建 TS 工程。

mxflutter create

假如我们要创建工程名字叫 mxflutter-homepage ，根据提示填写好对应内容，其中第二项 “请输入flutter项目放置mxflutter_js_bundle的路径” 是设置 TS 工程编译的JS Bundle输出的地方，通过相对路径指向前面在 Flutter 工程中创建好的 mxflutter_js_bundle，如果 TS 工程和此示例一样放置在 Flutter 工程中，就可以用相对路径指定。

$ mxflutter create
$ ? 请输入项目名字 mxflutter-homepage
$ ? 请输入flutter项目放置mxflutter_js_bundle的路径 ../../mxflutter_js_bundle  
$ ? 请输入你的名字 xsoap
$ ? 请输入你的邮箱 mxflutter@qq.com

完成后的目录结构

my_flutter/
├── lib/
│   └── main.dart
└── pubspec.yaml
└── mxflutter-ts-proj/
│   └── mxflutter-homepage/
│       └── src/
│           └── index.ts
└── mxflutter_js_bundle/

到此如果一切顺利已经配置好了所有内容，新建的 TS 工程里index.ts有经典的 Flutter 初始工程 Counter 完整代码， 下面我们尝试运行起来，打开 TS Counter页面。

4. 编译输出JS Bundle

先切换到刚新建的 TS 工程 mxflutter-homepage 为当前目录，使用 npm install 安装依赖。

$ cd mxflutter-homepage/ 

$ npm install #安装依赖

如果有错误发生，可以根据错误提示排除错误，如果安装成功，解下来就可以使用 npm run build 命令构建 JS Bundle

$ npm run build

如果一切顺利，在 mxflutter_js_bundle 文件夹就能看到有 bundle-mxflutter-homepage.js 输出。

业务 js bundle 资源需按照指定方式打包压缩成 bizBundle.zip。 在iOS下模拟器Debug模式下，bundle-mxflutter-homepage.js 直接放到 mxflutter_js_bundle 目录，按照下面‘开发调试’小节的内容，配置好debugJSBundlePath路径，就可以运行调试了，在android或者要发布，需要打包成bizBundle.zip，打包方式如下。（打包工具下个版本从平台抽离出来后放出）

例如：有两个业务文件 bundle-mxflutter-homepage.js 和 bundle-example2.js，操作步骤如下：

1. 新建两个文件夹，名称分别是 mxflutter-homepage 和 example2，将 js 文件放入对应文件夹；
2. 选中这两个文件夹，右键压缩为归档.zip, 修改名称为 bizBundle.zip。特别注意不要有文件夹嵌套，压缩包里不要多加入一层bizBundle的文件夹。

第三步 在 Flutter 工程中打开 MXFlutter 页面

1. 初始化 MXFlutter

在 main.dart 文件中，调用 MXJSFlutter.runJSApp() 初始化MXFlutter，runJSApp 函数如果不传任何参数，默认会运行 mxflutter_js_bundle 目录下的JS Bundle 文件。

//mxflutter
import 'package:mxflutter/mxflutter.dart';

void main() {
  //-------1. 初始化MXFlutter ---------
  MXJSFlutter.runJSApp();
  runApp(MyApp());
}

2. 在合适时机打开 MXFlutter 页面

在合适时机，比如用户点击按钮时，打开MXFlutter页面

  onTap: () {
                //-------2. 打开MXFlutter页面------
                Navigator.push(
                    context,
                    MaterialPageRoute(
                        builder: (context) => MXJSPageWidget(
                            jsWidgetName: "mxflutter-homepage")));
              }

如果一切顺利，你可以看到 Flutter 的经典页面了

可以把 MXJSPageWidget 当作普通的Flutter Widget，放到任何的地方，其中jsWidgetName: "mxflutter-homepage" 参数，会指示 MXFlutter 框架加载 mxflutter_js_bundle 目录下哪个 JS Bundle 文件。并且会被传递到 index.ts 代码，用来区分打开哪个 TS 页面。

对应代码在 mxflutter-homepage TS工程 src/index.ts 文件最下方。MyApp 可以换成任意 Widget

  mxflutter.regist({
                    name: 'mxflutter-homepage',
                    RootWidget: MyApp,
                });

开发调试

1. 实时监控 TS 源码，构建 JS Bundle

npm run build 命令可以单次构建 JS Bundle，在开发调试过程中，不是非常方便， 可以通过执行 npm run dev 命令监控源码变化，当你修改了源码时，会立即实时输出 bundle 包到您需要的位置 （ mxflutter 终端项目的 js 资源目录 ）

npm run dev

2. iOS 模拟器的hot reload 支持，为iOS 模拟器指定本地路径

在使用iOS 模拟器调试时，MXJSFlutter.runJSApp()可以设置 debugJSBundlePath 参数，推荐设置成 TS 代码的输出目录，这样TS代码实时更新生效。

  if (await MXJSFlutter.canDefineDebugJSBundlePath()) {
     // 在使用iOS 模拟器调试时，MXJSFlutter.runJSApp()可以设置  debugJSBundlePath 参数，推荐设置成 TS 代码的输出目录，这样TS代码实时更新生效。
     MXJSFlutter.runJSApp(debugJSBundlePath: '/Volumes/Data/Work/RFlutter/mxflutter-js/release');
  } else {
     MXJSFlutter.runJSApp();
  }

发布JS Bundle

mxflutter cli 打包支持生产模式 bundle 的构建，并可以兼容低版本 jscore ( ios 9 - 10 )

npm run build:production # 发布版本的构建

npm run build:es5 # es版本兼容构建 主要针对 ios 9 - 10