前提假设你界面已经会写,所以这里不讲环境、组件大全和某个库的 API。口径以当时的官方架构建议和 Impeller 说明为准,小版本差异去文档查。鸿蒙工具链以 CPF-Flutter/flutter_flutter 当时的说明为准。
按这个顺序看就够:它自己画 UI,Widget 只是配置;Dart 留下空安全、事件循环和混入;架构按 MVVM 分层再选库;坑集中在刷新范围、约束和生命周期。
它是什么
Flutter 是 Google 的 UI 框架,用 Dart 写。官方工具链出 iOS、Android、Web 和桌面。控件树不交给系统 View 去画,框架自己布局、自己合成,再交给引擎上屏。所以像素级一致,平台差异要自己补,系统控件的外观和辅助功能也要自己对齐。鸿蒙不在官方 SDK 里,国内用社区适配的同一套框架,见后面的「鸿蒙」。
可以分成两层:
- 框架用 Dart 写。Widget、手势、动画、Material / Cupertino 都在这层。
- 引擎负责渲染、文字、图片和平台通信。iOS 上现在只有 Impeller。Android API 29 及以上默认 Impeller,更低版本或不支持 Vulkan 时回退到旧的 OpenGL 渲染。业务代码一般不用管这条开关。
Debug 是 JIT,改完 Dart 能热重载,状态还在。Release 是 AOT,启动和运行都更快,热重载没有了。Web 的渲染路径和手机不是同一套,性能不能拿移动端的结论硬套。
三棵树
后面的问题大多从这三层来。
| 是什么 | 活多久 | |
|---|---|---|
| Widget | 不可变配置。build 里不断 new 出来,本身很便宜 | 一次 build |
| Element | 这棵配置在树上的位置。StatefulElement 持有 State,生命周期在这里 | 跟着树走,配置没变类型和 Key 就复用 |
| RenderObject | 真正做布局、绘制、命中测试 | 挂在需要绘制的 Element 上 |
BuildContext 就是 Element 暴露出来的接口。拿着 context 做的事,生命周期跟这个 Element 走。
不是每个 Widget 都有 RenderObject。StatelessWidget、StatefulWidget 只负责往下组合,真正的盒子来自 RenderObjectWidget,比如 Row、Padding、Text、ColoredBox。
父组件重建时,框架拿新旧 Widget 比 运行时类型和 Key。两者都相同,Element 更新配置,State 留着;有一个不同,旧子树拆掉,重新挂。所以 const 能让同一份配置被认出来,列表重排时要靠 Key 告诉框架「这还是刚才那一项」。
布局就一句
约束向下,尺寸向上,位置由父决定。
父组件把最小、最大宽高传给子组件,子组件在这个范围里报自己要多大,父组件再决定把它放哪。Row 里 Expanded 的 flex 不是子组件自己的属性,是父组件写进 ParentData 的。子组件不知道自己在弹性布局里占几份,它只看到一份收紧后的约束。
Column 在主轴上经常给出「高度可以无限」的约束。这时候再放一个也想无限高的 ListView,两边都定不了尺寸,就会报错。这是布局题,不是 ListView 坏了。
谁在跑
Dart 业务代码跑在 UI isolate 上,一条事件循环,没有共享内存的线程。引擎另有光栅线程把画面交给 GPU,平台线程处理通道。卡顿先看是不是把重活堵在了 UI isolate 上,而不是先怀疑「Flutter 渲染慢」。
语言要点
Flutter 的语言就是 Dart。冷门语法不记,留这几件。
空安全
类型默认非空,可空写成 String?。局部变量一旦判断过非空,后面的代码会把它当成非空,这叫类型提升。实例字段不会提升,因为别的方法可能改它。要提升就先赋给局部变量。
! 是你向编译器保证这里不是 null,保证错了就在运行时炸。能用判断和 ?? 就别用 !。
final、const、late
final:运行时赋一次。const:编译期常量。相同的 const 是同一个实例,Element 更新时可以直接跳过。late:推迟到第一次读之前赋值。读的时候还没有值会抛。late final常见于initState里创建、dispose里释放的 Controller。
const 不是代码风格。它让框架认出「配置没变」。
事件循环
UI isolate 上先跑完当前这段同步代码,再把微任务队列清光,然后才处理下一个事件(I/O、Timer、手势)。await 和 Future.then 的回调在微任务里,Future(() {}) 和 Timer 在事件队列里。
print(1);
Future(() => print(2));
Future.microtask(() => print(3));
print(4);
// 1 4 3 2
所以 await 之后,中间可能已经插入别的事件,Widget 可能已经卸掉。异步代码默认不在「刚才那个同步调用栈」里。
Future 是一个还没结束的结果。Stream 是一串结果。界面上持续变化的数据用 Stream 或可监听对象,一次性请求用 Future。
Isolate
重计算、大 JSON、图片解码如果留在 UI isolate,手势和帧都得排队。丢到 Isolate.run 或 compute。isolate 之间内存不共享,靠消息传,传的对象要能被拷贝。不要为了每个小请求都开一个 isolate,创建本身有成本。
混入
Dart 只有单继承。一段实现要复用、又不想把它放进父类时,用 mixin,with 混进类里。extends 拿走整条父类,implements 只拿走方法签名,with 拿走实现。
mixin 不能写生成构造函数。on 用来限制能混进谁,限定之后,mixin 内部才能用那个类型的成员。
class _PageState extends State<Page> with SingleTickerProviderStateMixin {}
一个 AnimationController 用 SingleTickerProviderStateMixin。同一页要好几个 ticker,换成 TickerProviderStateMixin。WidgetsBindingObserver 也是 mixin,用来听前后台切换,记得在 dispose 里 removeObserver。
同名方法谁生效,看 with 的顺序。链是从左到右叠上去的,最右边最靠近类自己。类里的方法压过所有 mixin;mixin 之间,写在后面的压过前面的。mixin 里的 super 不是固定的某个父类,而是这条链上的前一个。
class A {
String name() => 'A';
}
mixin M1 on A {
@override
String name() => 'M1(${super.name()})';
}
mixin M2 on A {
@override
String name() => 'M2(${super.name()})';
}
class C extends A with M1, M2 {}
// C().name() == 'M2(M1(A))'
// 写成 with M2, M1 就会反过来
所以多个 mixin 不要随便换位置。with 后面的那个先接到调用,它的 super 才会进到前一个。
组合,而不是继承一棵大树
Dart 里把能力拼起来,比继承体系更常见:
- extension:给已有类型加方法,不改原类。
- sealed class:子类闭集写在同一个库里,
switch必须写全,漏一个编译不过。适合结果、状态这种有限集合。 - record 和模式匹配:临时把几个值捆在一起返回,不用为了拆包去建一个只活一行的类。
sealed class Result {}
final class Ok extends Result {
Ok(this.value);
final int value;
}
final class Err extends Result {
Err(this.message);
final String message;
}
String show(Result result) => switch (result) {
Ok(:final value) => '$value',
Err(:final message) => message,
};
状态对象保持不可变,变更用新对象替换。这样监听方只要比较引用,就知道要不要刷新。
架构怎么选
官方现在的建议可以当成底:
- UI 和数据分开。数据层对外提供数据,UI 层负责显示和把用户操作交出去。
- 数据层用 Repository,把「从接口来还是从本地来」挡在里面。
- UI 层用 ViewModel 加很薄的 Widget。判断显示隐藏、跟屏幕尺寸有关的布局,可以留在 Widget 里。请求、校验、状态迁移不要写在
build里。 - 数据单向流:用户操作进数据层,新状态再流回 UI。
- 领域层(各种 UseCase)只有规则又多又重复时再加。小项目加这一层,常常只是把函数多转一次。
MVVM
页面按 MVVM 拆。View 是 Widget,ViewModel 管这个页面的状态和动作,Model 是界面要的那份数据,后面站着 Repository。
- View 照着状态画界面,点击只转到 ViewModel 的方法。布局、主题、动画留在这里。
- ViewModel 保存加载中、成功、失败,对外是
load()、submit()这种动作。它向 Repository 要结果,再通知 View。这里只依赖 Repository 和状态对象。 - Repository 决定数据来自接口还是本地。ViewModel 拿到的是 Model,不拼 URL,也不碰数据库。
方向固定成一圈:用户操作进入 ViewModel,ViewModel 向 Repository 要数据,新状态通知回 View,View 重建。数据只在 ViewModel 里改,界面只在 View 里刷新。
class OrderViewModel extends ChangeNotifier {
OrderViewModel(this._repository);
final OrderRepository _repository;
OrderUiState _state = const OrderLoading();
OrderUiState get state => _state;
Future<void> load() async {
_state = const OrderLoading();
notifyListeners();
final order = await _repository.fetch();
_state = OrderReady(order);
notifyListeners();
}
}
状态收成一个不可变对象,View 用 switch 画,不在 Widget 里判断「该不该请求」。
ListenableBuilder(
listenable: viewModel,
builder: (context, _) => switch (viewModel.state) {
OrderLoading() => const CircularProgressIndicator(),
OrderReady(:final order) => OrderBody(order: order),
OrderFailed() => const Text('加载失败'),
},
)
换 Riverpod 或 Cubit 时,换的是 notifyListeners 这一层。load() 和 Repository 留下来。页面跳转也收成状态,比如「去订单详情」,View 看到后再 go。ViewModel 不拿 BuildContext。
页面销毁时把 ViewModel 一起释放。登录态这种跨页面的状态放到更高一层,不要关在某个页面的 State 里。
状态分成两类,别混在一个全局单例里:
- 页面内的瞬时状态:输入内容、当前页签、动画进度。放在
State里就够。 - 离开页面还要在的状态:登录态、列表、购物车。放进 ViewModel,数据来源放进 Repository。
状态库
库只做一件事:ViewModel 的状态变了,让对应的 Widget 重建。Repository 留在原处。ChangeNotifier 加 ListenableBuilder 就是上面那段 MVVM,不引第三方库也能用。下面四个是常见的接法。
Provider
Provider 把对象放进 Widget 树,子组件沿着 context 按类型往上拿。它是 InheritedWidget 的包装。
build 里用 watch 订阅,notifyListeners 之后这个 Widget 会重建。按钮回调里用 read,只为了调用方法,不建立订阅。只关心状态里的一个字段时用 select,避免 ViewModel 任意一次通知都把整页刷掉。
ChangeNotifierProvider(
create: (_) => OrderViewModel(repository),
child: const OrderPage(),
);
final state = context.watch<OrderViewModel>().state;
context.read<OrderViewModel>().load();
查找靠两样东西:类型,以及页面确实挂在这个 Provider 下面。同一段子树里放两个 OrderViewModel,下面的页面分不清要哪一个。离开这棵树,context 也拿不到它。
Riverpod
Riverpod 不把依赖藏在父组件里。一个 provider 就是一个变量,谁要状态谁 watch 这个变量。身份是变量本身,所以两个订单页可以各有各的 provider,不会因为类型相同撞在一起。
根上套 ProviderScope,页面用 ConsumerWidget。ref.watch 写在 build 里,这个 provider 一变,只有 watch 了它的 Widget 重建。按钮里用 ref.read 调用一次。
final orderViewModelProvider =
NotifierProvider<OrderViewModel, OrderUiState>(OrderViewModel.new);
class OrderViewModel extends Notifier<OrderUiState> {
@override
OrderUiState build() => const OrderLoading();
Future<void> load() async {
state = const OrderLoading();
state = OrderReady(await ref.read(orderRepositoryProvider).fetch());
}
}
class OrderPage extends ConsumerWidget {
@override
Widget build(BuildContext context, WidgetRef ref) {
final state = ref.watch(orderViewModelProvider);
return switch (state) {
OrderLoading() => const CircularProgressIndicator(),
OrderReady(:final order) => OrderBody(order: order),
OrderFailed() => const Text('加载失败'),
};
}
}
ViewModel 要 Repository,也是 read 另一个 provider。依赖写在代码里,测试时把那个 provider 覆盖掉,不用先搭一棵 Widget 树。类名以锁住的 Riverpod 大版本为准,要认的是「变量加 ref.watch」这件事。
Bloc
Bloc 规定状态只能从 Cubit 或 Bloc 里面 emit 出来,外面改不了内部状态。挂到树上的方式和 Provider 一样,用 BlocProvider,取的时候也是 context.read。
页面就是一份 ViewModel 时,用 Cubit:方法里 emit 新状态。
class OrderCubit extends Cubit<OrderUiState> {
OrderCubit(this._repository) : super(const OrderLoading());
final OrderRepository _repository;
Future<void> load() async {
emit(const OrderLoading());
emit(OrderReady(await _repository.fetch()));
}
}
BlocBuilder 包住要刷新的那一块,状态变了只重建这块。按钮里 context.read<OrderCubit>().load()。
流程长、要把「用户点了加载、点了提交」留成一条记录时,再用 Bloc。先定义 OrderLoadRequested 这种事件,在 on<OrderLoadRequested> 里 emit。Cubit 少一个事件类;Bloc 多出来的是可以复述的事件流。
emit 出去的用新对象。和当前状态相等的那次 emit,界面不会动。
GetX
GetX 把状态、依赖查找和路由放在同一个包里。ViewModel 写成 GetxController,要让界面看见的字段加上 .obs。Obx 的闭包里读到哪个 .obs,就只订哪一个,别的字段变了它不重建。
class OrderController extends GetxController {
OrderController(this._repository);
final OrderRepository _repository;
final state = const OrderLoading().obs;
Future<void> load() async {
state.value = const OrderLoading();
state.value = OrderReady(await _repository.fetch());
}
}
Get.put 注册,Get.find<OrderController>() 取出。查找不经过 Widget 树,哪里都能 find。换页用 Get.to。少接三个库,所以搭一个小工具很快。
find 处处能用,Widget 就会直接改业务,Controller 也会顺手管跳转、文案和请求。页面少的时候省事;页面一多,Controller 容易什么都管。要用的话,Controller 仍然只调 Repository,Obx 只画 state。
怎么选
新项目自己能拍板时,用 Riverpod。Notifier 就是 ViewModel,Repository 是另一个 provider,页面 ref.watch 到谁就只跟谁重建。测试时替换 Repository 那个 provider,不用先搭 Widget 树。普通按钮也不必先包一层事件。
按这个顺序:
- 团队已经有一套,就用那套。Provider、Riverpod、Bloc 都能守住「Widget 薄、ViewModel 管状态、Repository 管数据」。
- 从零开始、以后还要自己维护,用 Riverpod。
- 流程长,而且要能复述用户点过什么,比如下单、审核、多步表单,用 Bloc。页面就是一份状态加几个方法时,用 Cubit。
- 一个人、几天的小工具,GetX 能用。Controller 只调 Repository,
Obx只画状态。打算做成长线产品,不要从 GetX 起步。
Provider 适合页面少,或者只想要 InheritedWidget 那一层包装。同一段子树里要放两个同类型的 ViewModel 时,它按类型查找会含糊,就不要再往上叠。
目录和路由
按功能切:feature/order 里放这个功能的页面、ViewModel、Repository。跨功能的网络、存储、主题放公共目录。按技术层切(所有 model 一文件夹、所有 page 一文件夹)在项目变大之后会不好找。
路由用 go_router 这种声明式方案。路径、页面、登录拦截放在一处,深链也从这里进。临时对话框继续用 Navigator 即可。
收成一句
按 MVVM:Widget 只渲染和转发,状态和动作在 ViewModel,数据从哪来在 Repository。自己能选时用 Riverpod;团队已有 Bloc 或 Provider 就顺着用。领域层等规则重复了再加。
鸿蒙
官方 Flutter 没有 ohos 这个平台。国内要一套 Dart 同时覆盖 Android、iOS 和鸿蒙,用 CPF-Flutter/flutter_flutter。它是 Flutter SDK 和引擎的 OpenHarmony 适配,组织由跨平台框架社区的 Flutter SIG 维护。旧的 OpenHarmony-SIG、鸿蒙突击队仓库已迁走,依赖和远程地址改到 CPF-Flutter。
业务 Widget、状态和路由不用为鸿蒙重写。换的是工具链和平台壳:鸿蒙产物是 HAP,平台目录叫 ohos/,原生侧是 ArkTS。Android、iOS 仍用官方 Flutter 编。同一个终端里把两套 bin 都放进 PATH,先出现的那套会接管全部命令。
3.35 及以后,引擎源码在这个仓库的 engine/ 目录里,不用再单独克隆引擎。应用开发直接下发布包或检出稳定 tag,不必自己编引擎。flutter build hap 会去拉配套的引擎产物。
版本号比官方慢一截。笔记写的时候,仓库发布表上的新线是 3.41.9+ohos-1.0.2(2026-09-30,Dart 3.11.5),旁边还有 3.35、3.27、3.22、3.7 的维护线。tag 形态是 上游版本+ohos-补丁,例如基于上游 3.41.9 的适配。新项目跟当前发布表里的最新稳定版,不要停在 dev 分支上。具体 tag 以仓库 README 的发布表为准。
环境
macOS 上 JDK 17、当前正式版 DevEco Studio,以及它自带的 SDK、ohpm、hvigor、node。鸿蒙 SDK 的 API 级别跟你选的 Flutter OH 发行说明走,不要拿 3.22 时代的 API 12 去套 3.41。
export PUB_HOSTED_URL=https://pub.flutter-io.cn
export FLUTTER_STORAGE_BASE_URL=https://flutter-ohos.obs.cn-south-1.myhuaweicloud.com
export PATH="$HOME/sdk/flutter_flutter/bin:$PATH"
export TOOL_HOME="/Applications/DevEco-Studio.app/Contents"
export DEVECO_SDK_HOME="$TOOL_HOME/sdk"
export PATH="$TOOL_HOME/tools/ohpm/bin:$TOOL_HOME/tools/hvigor/bin:$TOOL_HOME/tools/node/bin:$PATH"
export FLUTTER_GIT_URL="https://gitcode.com/CPF-Flutter/flutter_flutter.git"
FLUTTER_STORAGE_BASE_URL 指鸿蒙这条线的引擎缓存。官方镜像和它不是同一套产物。换过这个地址之后删掉 SDK 里的 bin/cache,工程里再 flutter clean。若 Dart 快照版本对不上,也是这一步。回头用官方 SDK 编 Android、iOS 时,把这个地址改回去,否则官方引擎缓存也会错。
flutter doctor -v 里 Flutter 和 OpenHarmony 都要是过的。真机或模拟器连上后,flutter devices 能看见设备。
工程
新工程要出三端:
flutter create --platforms ohos,android,ios --org com.example my_app
已有的 Android、iOS 工程,在用鸿蒙 SDK 的前提下补平台目录:
flutter create --platforms ohos .
用官方 flutter 执行这两句,CLI 不认识 ohos。生成之后根目录多一个 ohos/,和 android/、ios/ 并列。里面是 DevEco 工程:AppScope/app.json5 写包名和版本,entry/ 是 HAP 模块,ArkTS 在 entry/src/main/ets。lib/ 仍是原来的 Dart。
真机安装前要签名。用 DevEco 打开 ohos/,在 Signing Configs 里勾选自动签名,登录华为开发者账号后保存。
flutter pub get
flutter run -d <deviceId>
flutter build hap --release --target-platform ohos-arm64
日常调试用 --debug,看掉帧用 --profile。真机架构是 ohos-arm64,模拟器常用 ohos-x64。两种设备来回编时把 --target-platform 写上,避免缓存里的架构和当前设备不一致。
签名过的包名是 entry-default-signed.hap。路径各版本不完全一样,以命令打印的为准,常见在 build/ohos/hap/。版本号不要只改 app.json5,构建时用参数,否则可能被写回 1.0.0:
flutter build hap --release --target-platform ohos-arm64 \
--build-name=1.2.0 --build-number=120
--build-name 对应 versionName,--build-number 对应 versionCode。
插件
纯 Dart 包可以直接用。碰到 path_provider、相机、登录、支付这种要调系统 API 的包,先看它的 pubspec.yaml 有没有 platforms.ohos。没有的话,官方 pub.dev 版本在鸿蒙上不会出现实现。
CPF-Flutter 另有 flutter_packages 和三方库适配列表。优先换组织里已经适配的版本,再考虑自己补。
给现有插件加鸿蒙实现:
flutter create . --template=plugin --platforms=ohos
Dart 侧还是 MethodChannel。鸿蒙侧在插件的 ohos/ 里用 ArkTS 实现,类名写进 pubspec:
flutter:
plugin:
platforms:
ohos:
pluginClass: HelloPlugin
模板里的基类和方法通道写法以当前 SDK 生成为准。通道仍然是异步的,不要在 build 里调。FFI 插件用 --template=plugin_ffi,平台同样加上 ohos。
依赖解析也要当心。鸿蒙构建如果拉到没有 ohos 实现的传递依赖,链接阶段才失败。锁定适配过的版本,别让 flutter pub upgrade 把它们升回只有 Android、iOS 的版本。
和原来的工程怎么放
界面、ViewModel、Repository 保持一份。平台差异收在三处:
- 权限、应用图标、包名、签名,改
ohos/里的配置,不动lib/。 - 系统能力走插件。业务代码只调用 Dart API,鸿蒙的 ArkTS 留在插件里。
- 渲染仍是 Flutter 自绘,由适配过的引擎上屏。Impeller 的开关在
ohos工程的构建配置里,以当前版本文档为准,不要沿用 3.22 笔记里的默认值。
发布流水线把「鸿蒙 job」和「Android / iOS job」拆开,各用各的 Flutter SDK。本地可以用目录切换 PATH,不要在 ~/.zshrc 里永久把鸿蒙 SDK 放在官方 SDK 前面。
坑
这些要知道原因,不是清单打卡。
- 在
build里发请求、订阅流。build会反复执行。请求放在 ViewModel 的创建或initState,订阅在dispose里取消。 await之后继续setState或用 context。 中间这帧页面可能已经拆掉。先看mounted或context.mounted。- 纵向无限约束套无限高的子组件。
Column里直接放ListView就是这个。列表交给Expanded,或者整页只有一个滚动组件。 - 长列表开
shrinkWrap: true。 它会把子项一次布局完,懒加载没了。只有嵌在另一个滚动里、而且项数很少时才值得。 - 刷新范围太大。
setState刷新的是这个State下面的子树。MediaQuery.of(context)会听整份媒体信息,键盘一变根节点就重建。会变的部分拆成子 Widget;只要尺寸时用MediaQuery.sizeOf,或者只select用到的字段。 - 列表没有 Key,或者到处是
GlobalKey。 同类型的兄弟节点靠 Key 认身份,重排时状态才跟着那一项走。GlobalKey在全局登记,用来跨树拿到State,不要把它当普通句柄。 - Controller 和订阅没释放。
TextEditingController、AnimationController、ScrollController、StreamSubscription都在dispose里配对关掉。 - 热重载之后觉得初始化没生效。 热重载不重跑
main和initState。改了初始化、静态变量、枚举,用热重启。改了原生代码,要重新编。 - 大 JSON 和图片解码留在 UI isolate。 掉帧先看是不是这个,再考虑渲染。重活丢到
Isolate.run。 - 滚动里叠
Opacity、ClipPath、BackdropFilter、IntrinsicHeight。 它们会多一次离屏图层或额外布局。能用透明色、FadeTransition、固定高度就别用这些。 - 平台通道当成同步函数。 通道是异步的,参数在 UI isolate 和平台线程之间排队。不要在
build里调。频繁的小调用合并掉;类型化接口用 Pigeon,紧凑的二进制用 FFI。 - Debug 很顺,Release 才暴露的问题。 Debug 有额外检查,帧时间不能当线上性能。看 jank 用 profile 模式。Impeller 解决的是着色器编译造成的首帧卡顿,解决不了 UI isolate 上的重活。
总结
值得记住的是这条链:Dart 写出不可变的 Widget 配置,Element 保住树上的状态,RenderObject 在约束里完成布局和绘制,Impeller 负责上屏。业务代码跑在单线程的 UI isolate 上,所以异步要让出事件循环,重活要离开这个 isolate。
架构上用 MVVM:View 只渲染和转发,ViewModel 管状态和动作,Repository 挡数据来源,状态单向流回界面。自己能选时用 Riverpod;团队已经定了 Bloc、Provider 或 GetX,就守住这层再沿用。
鸿蒙用 CPF-Flutter 的工具链单独出 HAP。lib/ 仍是同一份,Android 和 iOS 继续用官方 SDK。
三棵树、事件循环、分层,以及 build、约束、Key、dispose 这几个坑,比组件参数值得多看两眼。