Flutter 自 2015 年初次亮相以来,经过了多年的发展已经相当成熟,在阿里、美团、拼多多等互联网公司都有广泛的应用。在 ICBU 阿里卖家上 90+% 的新业务使用 Flutter 开发,ICBU 客户端开发组拥有众多的 Flutter 开发人员。
Flutter for Web (FFW) 早期试验版于 2019 年发布,在当时已经有很多感兴趣同学对其进行调研,当时由于刚发布存在诸多问题不适合在生产环境中使用。在今年(2021)三月份,Flutter 2.0 发布,FFW 正式进入 stable 分支。
阿里卖家外贸资讯版块主要使用 Flutter 开发,在本财年的目标中,外贸资讯的App外推广为开源引流的重要一环。App外资讯推广需要一个承载内容Web页面,对该Web页面的要求如下:
由于缺乏前端同学的支持,想要完成此页面只能由 App 端上同学自己投入,经过一定的考虑我们选择了 FFW,理由如下:
经过以上思考,正式开启 FFW 填坑之旅。
目前阿里卖家FFW相关页面已上线,从 FFW 发布至今产物 js 文件大的问题就一直存在,理论上会很影响页面加载体验,实际测试中观察到在 PC、移动设备上加载体验尚可,运行很流畅,相关 Demo 如下:
创建 FFW 工程比较简单,Flutter 切换到 stable 版本,之后运行命令 flutter create xxxProject 进入工程后点击运行一个 Demo 工程便可运行起来。要将 FFW 应用到实际的工程中,需要考虑的是工程的问题和如何融入阿里的体系的问题,如:怎么发布、开发流程如何管控、怎么请求接口等,总结如下:
以上为阿里卖家 FFW 开源引流最小闭环实践中遇到的问题,除此之外 FFW 待建设的问题还有:
接下来是对最小闭环实践中,工程基础问题的出现原因和解决方案的说明。
参考 App 端 Flutter 开发,FFW 中首先要考虑选择 Flutter 的什么版本,其次是考虑如何复用已有的 Flutter 代码。
版本选择问题因 FFW 和 Flutter for App (FFA) 的 Flutter 版本无法统一产生。FFW 需要的 Flutter 版本为 2.0+,而目前我们 App 端内的 Flutter 版本为 1.X+ ,要升级到 2.0+ 版本还需等待不确定的时间。经过一定的考虑目前我们 FFW 和 FFA 选择版本如下:
FFA: hummer/release/v1.22.6.3 -- UC的Hummer分支
FFW: origin/flutter-2.8-candidate.9 -- 官方分支
FFW 不选用 stable 版本是因为在最近刚发布的 iOS 15 上 FFW 页面会因 webGL 问题会卡死,该问题修复方案目前已集成到了candidate版本。(当前最新stable版本为2.10.0,问题已解决)
FFA 代码复用到 FFW 中要考虑的问题分两块:
Dart 代码复用
FFW 需要 Flutter 2.0+ 版本对应的 dart 版本为 2.12,此版本的 dart 引入了空安全 (Sound null safety) 特性。FFA 上使用的 Flutter 版本为 1.+ 版本对应的 dart 还未引入空安全。同时 Flutter 中新老版本 dart 库代码无法混合编译,所以目前对已有 App 端代码库还无法做到无缝复用,只能通过修改已有代码进行复用,代码修改主要的点有:
User? nullableUser;
nullableUser?.toString(); // 空安全,如为空不会出现NPE
nullableUser!.toString(); // 强制指定非空,如为空会报错
/// 老版本
User({
@required this.name,
@required this.age,
});
/// 新版本
User({
required this.name,
required this.age,
});
低版本代码经过这三步修改后基本可在新版本编译通过,除此之外还会有部分 API 由于版本升级产生变更,也需要相应的修改,如:
/// 老版本
typedef ValueWidgetBuilder<T>
= Widget Function(BuildContext context, T value, Widget child);
/// 新版本
typedef ValueWidgetBuilder<T>
= Widget Function(BuildContext context, T value, Widget? child);
在 API 变更中这类问题占大多数,修改起来较简单。另外还有一类改动,如在抽象类 TextSelectionControls中,handleCut等方法参数的个数发生了变更:
/// 老版本
void handleCut(TextSelectionDelegate delegate) {...}
/// 新版本
void handleCut(TextSelectionDelegate delegate,
ClipboardStatusNotifier? clipboardStatus) {...}
这类改动需根据实际情况进行修改,难度中等,新加的参数大概率是可以不使用的。
平台相关插件
平台相关的插件会调用 Native 的能力,要在 FFW 上使用 FFA 中的插件,需要为插件在 Web 平台实现相应的能力,下文 js 调用部分会进行说明。如果使用的是pub.dev 中的库,且该库满足如下条件则可直接使用相应的版本:
支持 Web 版本 | 支持空安全 |
本地Demo工程创建并运行成功后,接下来要考虑几个问题:
对于开发到发布流程的管控,参考前端选用 DEF 平台(阿里内部前端开发发布平台)通过创建 WebApp 方式管理,这里不详细说明。对于页面发布涉及内容如下:
FFW 的构建方式有两种,构建的产物在应用中并非全部需要需要进行一定的精简;另外要在 DEF 平台上发布产物还需对产物进行一些额外的处理。在构建中主要考虑如何构建,FFW 编译构建可选命令如下:
/// canvaskit方式渲染
flutter build web --web-renderer canvaskit
/// html方式渲染
flutter build web --web-renderer html
两条命令的区别是目标页面以何种方式渲染,Flutter 官方对两种方式区别的解释如下:
总结来说如下:
在空工程上两种方式资源加载对比如下,基于对页面大小和页面性能考虑我们选择使用html的方式。
Html 方式 | CanvasKit 方式 |
对于新创建的工程,编译后产物位于 ./build/web目录下,结构为:
build
└── [ 384] web
├── [ 224] assets
│ ├── [ 2] AssetManifest.json
│ ├── [ 82] FontManifest.json
│ ├── [740K] NOTICES
│ └── [ 96] fonts
│ └── [1.2M] MaterialIcons-Regular.otf
├── [ 917] favicon.png
├── [6.5K] flutter_service_worker.js
├── [ 128] icons
│ ├── [5.2K] Icon-192.png
│ └── [8.1K] Icon-512.png
├── [3.6K] index.html 【发布保留】
├── [1.2M] main.dart.js 【发布保留】
├── [ 570] manifest.json
└── [ 59] version.json
其中各目录和文件的作用和说明如下:
在实际发布中,需要的构建产物只有 index.html 和 main.dart.js ,对于每次的迭代,不涉及到 “壳工程” 变更时只需要 main.dart.js 即可。
选定了需要的产物后,在 DEF 平台发布前还需要对这两个文件进行一些处理:
在DEF平台上,产物文件处理完成后 js 和 html 文件会被发布到相应的cdn,同时html会被部署到特定的地址上:
预发:
线上:
对于线上环境index.html内容如下:
<!DOCTYPE html>
<html>
<head>
<!-- 发布到域名的二级目录时使用 -->
<base href="/content_page/" />
</head>
<body>
<!-- 替换为 main.dart.js 相应的 cdn 地址 -->
<script type="text/javascript" src="https://g.alicdn.com/algernon/alisupplier_content_web/1.0.10/main.dart.js"></script>
</body>
</html>
至此使用页面部署地址就可以访问到我们的目标页面了如果页面是一次性打开的,且不需要在内部进行多页面跳转,到这一步发布工作就完成了。如果涉及到多页面跳转,还需要将相关的内容发布到自己的域名下,比较简单的方式为配置重定向,除此之外直接引用产物也可:
基础链路跑通后就可以进行需求的开发了,开发过程中比较重要的环境是代码的调试,FFW 可在 Chrome 中以类似 App 的方式调试且体验较好。在 Debug 环境下在 IDE 中设置断点后,即可在 IDE 中调试断点,也可在 Chrome 中查看断点,Chrome 中甚至可看到 dart 代码。以 VSCode 为例 Debug 过程和体验如下:
启动Flutter调试
VSCode 和 Chrome 中可见的断点
进入到实际的开发中后,就需要诸如路由、接口请求等能力的支持了,首先是页面路由和地址。
在 FFW 应用中出现多页面,或者需要通过 Http 链接传参时,就需要进行相应的路由配置。类似FFA,可在根MaterialApp中配置相应的 Route,之后使用Navigator.push跳转或通过页面地址直接打开页面即可。如下代码可实现命名跳转和页面地址跳转:
/// MaterialApp 配置
class MyApp extends StatelessWidget {
@override
Widget build(BuildContext context) {
return MaterialApp(
debugShowCheckedModeBanner: false,
onGenerateRoute: RouteConfiguration.onGenerateRoute,
onGenerateInitialRoutes: (settings) {
return [RouteConfiguration.onGenerateRoute(RouteSettings(name: settings))];
},
);
}
}
/// 命名路由配置
class RouteConfiguration {
static Map<String, RouteWidgetBuilder?> builders = {
/// 页面A
'/page_a': (context, params) {
return PageA(title: params?['title']);
},
/// 页面B
'/page_b': (context, params) {
return PageB(param1: params?['param1'], param2: params?['param2']);
},
};
static Route<dynamic> onGenerateRoute(RouteSettings settings) {
return NoAnimationMaterialPageRoute(
settings: settings,
builder: (context) {
var uri = Uri.parse(settings.name ?? '');
var route = builders[uri.path];
if (route != null) {
return route(context, uri.queryParameters);
} else {
return CommonPageNotFound(routeSettings: settings);
}
},
);
}
}
配置完成后即可在页面能进行跳转,或者通欧冠浏览器地址直接跳转:
/// Navigator 跳转页面 B
Navigator.of(context).restorablePushNamed('/page_b?param1=123¶m2=abc');
/// 页面 B 访问地址
https://xxx.xx/#/page_b?param1=123¶m2=abc
注意:上述地址跳转方式要求 FFW 的 UrlStrategy 为 hash tag 方式(默认的UrlStrategy)。
通过使用 pub.dev 等仓库,可以在 FFW 中轻松的使用各种能力。对于仓库中没有的能力就要考虑进行扩展了。在 FFA 上可通过插件的方式使用 native 的能力,同样在 FFW 上可通过扩展使用 js 的能力。通过调用 js 的能力前端海量的技术积累便可应用到 FFW 上。
FFW 中的 dart 最终会编译成 js ,在 FFW 中理应可以天然使用 js。为了在 dart 中支持 js 的调用,dart 官方发布了 js 库,通过使用该库中的注解可是很方便的在 dart 中调用 js。
比如需要调用 alert 方法时,进行如下定义:
/// 文件:js_interface.dart
/// 调用js方法的工具类库,需在 dependencies 中引入 js 库
@JS()
library lib.content;
import 'package:js/js.dart';
/// alert 弹窗
@JS('alert')
external void jsAlert(String msg);
之后在需要alert的地方引入js_interface.dart 并调用 jsAlert方法即可:
import 'package:mtest/js_interface.dart';
...
jsAlert('测试消息');
...
更多用法详见 pub.dev 中 js 库的说明:pub.dev/packages/js… js 的能力后,接下来的很多问题迎刃而解。
鉴于 App 端现有 Mtop (阿里App使用的一种网关)的建设,如果能在 FFW 中调用现有的 Mtop 将可以减少很多的工作量。为此需要为 FFW 添加 Mtop 调用的能力,要完成这个工作需要两部分的工作:
通过调用 mtop.js 的能力便可在 FFW 中引入 mtop 的能力。整体流程如下:
1、在index.html 中引入 mtop.js
<script src="//g.alicdn.com/mtb/lib-mtop/2.6.1/mtop.js"></script>
2、定义接口文件 js_mtop_interface.dart
@JS()
library lib.mtop;
import 'package:js/js.dart';
import 'package:js/js_util.dart';
import 'dart:convert';
import 'dart:js';
/// mtop请求的参数
@anonymous
@JS()
class MtopParams {
external String get api;
external String get v;
external dynamic get data;
external String get ecode;
external String get dataType;
external String get type;
external factory MtopParams({
required String api,
required String v,
required dynamic data,
required String ecode,
required String dataType,
required String type,
});
}
/// lib.mtop 请求函数
@JS('lib.mtop.request')
external dynamic _jsMtopRequest(MtopParams params);
/// dart map 转为 js 的 object
Object mapToJSObj(Map<String, dynamic> a) {
var object = newObject();
a.forEach((k, v) {
var key = k;
var value = v;
setProperty(object, key, value);
});
return object;
}
/// mtop js 请求接口
Future mtopRequest(String api, Map<String, dynamic> params, String version, String method) {
var jsPromise = _jsMtopRequest(
MtopParams(
api: api,
v: version,
data: mapToJSObj(params),
ecode: '0',
type: method,
dataType: 'json',
),
);
return promiseToFuture(jsPromise);
}
/// 返回结果解析使用
@JS('JSON.stringify')
external String stringify(Object obj);
3、进行 mtop 接口调用
import 'package:mtest/mtop/js_mtop_interface.dart';
...
try {
var res = await mtopRequest(apiName, params, version, method);
print('res $res');
} catch (err) {
data = stringify(err);
}
4、解析结果:接口请求返回的结果是一个 jsObject,可通过 js 方法 JSON.stringify 转成 json 后在 dart 层面使用
String jsonStr = stringify(res);
FFW 中接入 mtop.js 后,需要对目标 mtop 接口进行相应的处理才可调用:
同 mtop 请求,FFW 中可引入黄金令箭的 js 库进行打点,流程如下:
1、index.html 引入 js 文件
<script type="text/javascript" src="https://g.alicdn.com/alilog/mlog/aplus_v2.js"></script>
2、定义接口文件 js_goldlog_interface.dart
@JS()
library lib.goldlog;
import 'package:js/js.dart';
/// record 函数
@JS('goldlog.record')
external dynamic _jsGoldlogRecord(String t, String e, String n, String o, String a);
void goldlogRecord(String logkey, String eventType, String queryParams) {
_jsGoldlogRecord(logkey, eventType, queryParams, 'GET', '');
}
3、打点调用
import 'package:mtest/track/js_goldlog_interface.dart';
...
goldlogRecord(logkey, eventType, queryParams);
...
之后在 log 平台进行相应的点位配置即可。
监控能力接入较为简单,这里选择 arms(应用实时监控服务),直接在 index.html 中引入 arms 即可。流程如下:
1、在 index.html 中引入相关库
<script type="text/javascript">
var trace = window.TraceSdk({
pid: 'as-content-web',
plugins: [
[window.TraceApiPlugin, { sampling: 1 }],
[window.TracePerfPlugin],
[window.TraceResourceErrorPlugin]
],
});
// 启动 trace 并监听全局 JS 异常,debug时问题暂时注释
trace.install();
trace.logPv();
</script>
2、在 arms 平台上进行相关配置
注意:trace.install() 在 Debug 环境下会导致页面不展示,可在 Debug 环境中禁用。
完成了上述基础能力建设后,FFW 基本可满足简单需求的开发。需求开发之外还需考虑体验、兼容性等问题。
FFW 从发布至今都存在的一个问题就是包大小问题,对与一个空的 helloworld 工程,单 js 包大小是 1.2 MB(未压缩前),在移动设备上网络不好的时候可能需要加载好些秒。为了提升页面加载的体验,考虑可以做的事情如下:
FFW 页面在 js 加载完成之前都是白屏,给人一种页面卡死的感觉,为此可以在 js 加载完成前增加加载动画不至于让页面一直白屏。参考App上管用的做法,可在数据加载出来之间插入骨骼屏,实现如下:
<iframe src="https://g.alicdn.com/algernon/alisupplier_content_web/0.9.1/skeleton/index.html" id="iFrame" frameborder="0" scrolling="no"></iframe>
<script>
function setIframeSize() {
<!-- 骨骼屏尺寸设置,占满全屏 -->
}
function removeIFrame() {
var iframe = document.getElementById("iFrame");
iframe.parentNode.removeChild(iframe);
}
setIframeSize();
</script>
<!-- load 完成之后移除骨骼屏 -->
<script type="text/javascript" src="https://g.alicdn.com/algernon/alisupplier_content_web/1.0.10/main.dart.js"
onload="removeIFrame()"></script>
等待过程优化可在一定程度上提升等待体验,单治标不治本,要想加载快还得让加载的资源小,对于多页面应用,可以将整个 main.dart.js 拆分成多个小的包,在使用的过程中逐步加载,目前了解到美团有相应的技术,但实现细节未知,有待研究。可参考 github.com/flutter/flu…
类似 App 在不同设备上会有体验问题,FFW 在不同的 H5 容器中页会存在兼容问题,在我们的实践中不同 H5 容器踩坑记录如下:
钉钉H5容器内白屏问题:
微信H5容器内白屏问题:
iOS 15 上页面卡死问题:
iOS兼容性问题:
除了 H5 容器的兼容问题外,在实践中还遇到 FFW 自身的一些问题,记录如下:
provider 库问题:
JsonConverter问题:
当前实践中只完成了业务可用的一个小闭环建设,FFW 中仍有很多 TODO 的内容,如下:
工程构建:
基础功能:
兼容和优化
畅想:
关注【阿里巴巴移动技术】微信公众号,每周 3 篇移动技术实践&干货给你思考!