Flutter 笔记:它是什么,语言要点,架构和坑

2 阅读11分钟

前提假设你界面已经会写,所以这里不讲环境、组件大全和某个库的 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 树。普通按钮也不必先包一层事件。

按这个顺序:

  1. 团队已经有一套,就用那套。Provider、Riverpod、Bloc 都能守住「Widget 薄、ViewModel 管状态、Repository 管数据」。
  2. 从零开始、以后还要自己维护,用 Riverpod。
  3. 流程长,而且要能复述用户点过什么,比如下单、审核、多步表单,用 Bloc。页面就是一份状态加几个方法时,用 Cubit。
  4. 一个人、几天的小工具,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 前面。

坑

这些要知道原因,不是清单打卡。

  1. 在 build 里发请求、订阅流。 build 会反复执行。请求放在 ViewModel 的创建或 initState,订阅在 dispose 里取消。
  2. await 之后继续 setState 或用 context。 中间这帧页面可能已经拆掉。先看 mounted 或 context.mounted。
  3. 纵向无限约束套无限高的子组件。 Column 里直接放 ListView 就是这个。列表交给 Expanded,或者整页只有一个滚动组件。
  4. 长列表开 shrinkWrap: true。 它会把子项一次布局完,懒加载没了。只有嵌在另一个滚动里、而且项数很少时才值得。
  5. 刷新范围太大。 setState 刷新的是这个 State 下面的子树。MediaQuery.of(context) 会听整份媒体信息,键盘一变根节点就重建。会变的部分拆成子 Widget;只要尺寸时用 MediaQuery.sizeOf,或者只 select 用到的字段。
  6. 列表没有 Key,或者到处是 GlobalKey。 同类型的兄弟节点靠 Key 认身份,重排时状态才跟着那一项走。GlobalKey 在全局登记,用来跨树拿到 State,不要把它当普通句柄。
  7. Controller 和订阅没释放。 TextEditingController、AnimationController、ScrollController、StreamSubscription 都在 dispose 里配对关掉。
  8. 热重载之后觉得初始化没生效。 热重载不重跑 main 和 initState。改了初始化、静态变量、枚举,用热重启。改了原生代码,要重新编。
  9. 大 JSON 和图片解码留在 UI isolate。 掉帧先看是不是这个,再考虑渲染。重活丢到 Isolate.run。
  10. 滚动里叠 Opacity、ClipPath、BackdropFilter、IntrinsicHeight。 它们会多一次离屏图层或额外布局。能用透明色、FadeTransition、固定高度就别用这些。
  11. 平台通道当成同步函数。 通道是异步的,参数在 UI isolate 和平台线程之间排队。不要在 build 里调。频繁的小调用合并掉;类型化接口用 Pigeon,紧凑的二进制用 FFI。
  12. 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 这几个坑,比组件参数值得多看两眼。

文档