跳到正文
CH 02起步Flutter8 分钟阅读

第一个 Flutter App:main、runApp、Widget、热重载

第 2 章 · 第一个 Flutter App:main、runApp、Widget、热重载

本章示例examples/ch02-first-app在线阅读源码下载 zip

run

$cd examples/ch02-first-app && flutter run -d macos(Linux → -d linux,Windows → -d windows,Android → 设备 id)

已验证

  • flutter analyze(0 告警)、flutter test(4 个用例全绿)、flutter build macos --debug(真实构建并启动成功)
  • 完整工程已打包:打包下载
本章目录 · 11 节

2.1 本章目标

  • 用最小代码跑起一个真实 Flutter 应用,并在桌面上看到窗口;
  • 理解 Widget 树 = 你的 UI:声明式(declarative)编程模型,以及它和 C/Go 立即模式(immediate mode)GUI 的根本差异;
  • 知道 BuildContext、const Widget、Key 分别解决什么问题;
  • 会用 flutter run 的热重载(hot reload)工作流,并知道它什么时候失效;
  • 能写第一个 widget 测试,把 UI 断言变成 CI 可跑的东西。

本章还不讲状态(ch06)和布局系统(ch04),但你会看到它们即将出现的接口。

2.2 程序的全部入口

dartlib/main.dart源文件
// examples/ch02-first-app/lib/main.dart
import 'package:flutter/material.dart';
import 'src/home_page.dart';

void main() {
  runApp(const DartBookApp());
}

class DartBookApp extends StatelessWidget {
  const DartBookApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: '第一个 Flutter App',
      debugShowCheckedModeBanner: false,
      theme: ThemeData(
        useMaterial3: true,
        colorScheme: ColorScheme.fromSeed(seedColor: const Color(0xFF00695C)),
      ),
      home: const HomePage(),
    );
  }
}

就这么多。runApp 做三件事:建立引擎与渲染管线、把 widget 树挂到根上、进入事件循环并且永不返回(所以 main 后面写代码是不会执行的)。

对照:一个窗口是怎么出现的

步骤 C + Win32 Go + Gio/gioui Flutter
注册窗口类 RegisterClassEx 框架内部 —
创建窗口 CreateWindowEx app.NewWindow() runApp(widget)
事件循环 while (GetMessage()) DispatchMessage() w.Event() 循环 框架内部(Dart isolate 的事件循环)
绘制 WM_PAINT + GDI/D3D op.Ops 立即模式录制 build() 产出 Widget 树 → 引擎每帧渲染
关闭 WM_DESTROY + PostQuitMessage w.Close() —
代码量 100+ 行 40+ 行 1 行

关键差异不是"代码少",而是绘制模型不同:

  • Win32/GDI 是保留模式:控件是真实存在的 HWND,你改它它才变;
  • 立即模式(Gio、Dear ImGui、SDL)是每帧重录:你一帧不录,画面就是空的;
  • Flutter 是声明式:你写"当前状态下的 UI 应该长什么样",框架负责 diff 出最小变更并交给引擎。build() 会被反复调用,一次调用不代表一次屏幕刷新(build 可能比帧更频繁,比如父级重建但子树被 const 短路)。

这是本章最重要的一句话:build() 必须是纯函数。不要在 build 里发请求、写文件、改全局变量——它随时可能被框架再调一次。

2.3 Widget / Element / RenderObject:三棵树的直觉

Flutter 内部有三棵树,初学者只需要记住分工:

树 是什么 生命周期 类比
Widget 不可变的"配置描述",build() 每次产出一批新对象 极短,重建即丢弃 C 里的 struct 配置、Go 里的 struct 值
Element 树上的"稳定身份",长期存活,持有 Widget 引用 与 UI 结构同生命周期 会话/句柄
RenderObject 真正做布局与绘制的对象 长期存活 HWND / D3D 资源

const Widget 的威力就在这里:Element 在更新时先比较新旧 Widget,若两者 identical(同一个对象),就整棵子树跳过重建。所以 const Text('hi') 不只是省了一次分配,而是省了一整次子树 diff。

dart
// 本例里大量出现的写法:能 const 就 const
body: ListView(
  padding: const EdgeInsets.all(16),   // const
  children: [
    _Intro(accent: scheme.primary),   // 不能 const:依赖 Theme
    for (final Fact fact in facts) _FactCard(fact: fact),
  ],
),

2.4 MaterialApp / Scaffold:框架给你的两样"表"

Widget 作用 对照
MaterialApp 应用级配置:主题、路由表、本地化、导航器 QApplication + 样式表 + 路由表
Scaffold 一页的骨架:AppBar、body、FAB、抽屉、SnackBar Win32 的手工布局 + 状态栏

MaterialApp 一个进程只该有一个(或用 MaterialApp.router);Scaffold 每页一个。桌面端 Scaffold 的 AppBar 会占掉窗口顶部一条,这是 Material 美学,不是平台限制。

代码里的 HomePage 就是一个"组装"型 Widget:

dartlib/src/home_page.dart源文件
// examples/ch02-first-app/lib/src/home_page.dart
const List<Fact> facts = [
  (title: 'main() → runApp()', body: '...'),
  (title: '一切皆 Widget', body: '...'),
  // ...
];

return Scaffold(
  appBar: AppBar(title: const Text('第一个 Flutter App')),
  body: ListView(
    padding: const EdgeInsets.all(16),
    children: [
      _Intro(accent: scheme.primary),
      const SizedBox(height: 16),
      for (final Fact fact in facts) _FactCard(fact: fact),
    ],
  ),
  floatingActionButton: FloatingActionButton.extended(
    key: const Key('about-fab'),
    onPressed: () => _showAbout(context),
    icon: const Icon(Icons.info_outline),
    label: const Text('关于'),
  ),
);

注意几个细节,它们都在后面章节展开:

  • for 元素(集合里的 for)是 Dart 的集合推导,直接生成 Widget 列表,比 Go 里 append 循环更紧凑;
  • Theme.of(context) 从 BuildContext 向上查找 InheritedWidget——这就是 context 的唯一用途:向上找祖先提供的数据(ch11 会用它讲状态管理);
  • Key('about-fab') 给 widget 一个稳定身份,测试和列表重排都靠它。

2.5 没有状态也能有交互

本章刻意只在 StatelessWidget 上做交互——弹对话框:不改任何状态,只是往导航栈上 push 一层。

dart
void _showAbout(BuildContext context) {
  showDialog<void>(
    context: context,
    builder: (BuildContext ctx) => AlertDialog(
      title: const Text('关于'),
      content: const Text('第 2 章示例:main() → runApp() → Widget 树。'),
      actions: [
        TextButton(
          onPressed: () => Navigator.of(ctx).pop(),   // 出栈 = 关闭对话框
          child: const Text('好'),
        ),
      ],
    ),
  );
}

陷阱:builder 里的 ctx 和外面的 context 不是一回事。对话框有自己的 Navigator/Theme 作用域,关闭时要用 builder 给的那个(或者用 Navigator.pop(context) 但要保证还是同一个 Navigator)。C/Go 程序员容易把它当成"回调参数随手用"——Flutter 里 context 是有作用域和生命周期的对象,异步之后再使用 context 必须判 mounted(ch06 展开)。

2.6 热重载:Flutter 真正的生产力差异

bash
cd examples/ch02-first-app
flutter run -d macos      # macOS;Linux 用 -d linux,Windows 用 -d windows

运行中的终端里:

按键 行为 什么时候用
r hot reload:重新编译改动的库,保留状态 改 UI、改文字、改布局(95% 的情况)
R hot restart:重启 App,状态清空 改了全局变量、main()、静态初始化
q 退出 —

热重载生效的条件:改的是代码且不改变已有对象的结构。以下情况它会拒绝或需要热重启:

  • 改了 main() 或顶层 final 的初始化;
  • 改了类的字段类型/泛型参数(已有实例无法原地升级);
  • 改了枚举成员;
  • 引用了新的原生插件(需要重新构建原生壳)。

对比 C/Go 的工作流:C 里改一行 UI 文本 → 重新编译 → 重开窗口 → 手动点回原来的界面状态;Flutter 里改一行 → 按 r → 界面保持当前状态更新。这个循环的差异,是长期项目里最值钱的部分。

2.7 第一个 widget 测试

flutter test 不需要真机/窗口,它在测试环境里用 headless 的渲染桩跑真正的 widget 代码。

darttest/app_test.dart源文件
// examples/ch02-first-app/test/app_test.dart
testWidgets('启动后渲染 AppBar 与所有知识卡片', (WidgetTester tester) async {
  await tester.pumpWidget(const DartBookApp());
  await tester.pumpAndSettle();

  expect(find.byType(Scaffold), findsOneWidget);
  expect(find.byType(AppBar), findsOneWidget);
  expect(find.byType(Card), findsNWidgets(facts.length));
});

testWidgets('点击 FAB 弹出对话框,点"好"关闭', (WidgetTester tester) async {
  await tester.pumpWidget(const DartBookApp());
  await tester.pumpAndSettle();

  await tester.tap(find.byKey(const Key('about-fab')));
  await tester.pumpAndSettle();

  expect(find.byType(AlertDialog), findsOneWidget);
  await tester.tap(find.text('好'));
  await tester.pumpAndSettle();
  expect(find.byType(AlertDialog), findsNothing);
});
概念 作用 Go/C 类比
pumpWidget 把 widget 挂到测试用的根上并跑一帧 启动一个最小进程
pump / pumpAndSettle 推进一帧 / 一直推进到没有动画 手动驱动事件循环
find.byType / byKey / text 在 widget 树里定位 控件句柄查找
expect(..., findsNWidgets(n)) 断言 assert

第三个用例还演示了桌面端的尺寸变化:直接改 tester.view.physicalSize 再 pump,断言不抛异常。桌面应用会被用户随意拉窗口,这个测试能兜住"只在小屏上炸"的溢出问题(ch04 会讲约束系统为什么会导致溢出)。

2.8 运行与验证

bash
cd examples/ch02-first-app
flutter pub get
flutter analyze          # No issues found!
flutter test             # All tests passed! (4 个用例)

# 真实运行(桌面端)
flutter run -d macos     # Linux: -d linux / Windows: -d windows

# 无图形环境(CI/远程 shell)下的等价验证
flutter build macos --debug
./build/macos/Build/Products/Debug/ch02_first_app.app/Contents/MacOS/ch02_first_app

本次验证的真实输出:

text
✓ Built build/macos/Build/Products/Debug/ch02_first_app.app
[IMPORTANT:flutter/shell/platform/embedder/embedder_surface_metal_imp.mm(53)]
    Using the Impeller rendering backend (MetalSDF).
flutter: The Dart VM service is listening on http://127.0.0.1:57664/...

窗口成功显示、进程存活 6 秒以上、无异常日志。移动端(Android/iOS)用同一份 lib/ 代码:

bash
flutter run -d <android-device-id>
flutter run -d <ios-simulator-id>

本例不含任何平台专属 API,桌面与移动端行为一致——这是后续所有章节的约束(见 AGENTS.md §3.4)。

附:C/Go 代码对照:一个窗口需要多少代码

c
/* C / Win32:注册窗口类 → 创建窗口 → 消息循环(错误处理全部省略) */
int main(void) {
    WNDCLASS wc = { .lpfnWndProc = WndProc, .lpszClassName = "demo" };
    RegisterClass(&wc);
    HWND hwnd = CreateWindow("demo", "Hello", WS_OVERLAPPEDWINDOW,
                             100, 100, 640, 480, 0, 0, 0, 0);
    ShowWindow(hwnd, SW_SHOW);
    MSG msg;
    while (GetMessage(&msg, 0, 0, 0)) {
        TranslateMessage(&msg);
        DispatchMessage(&msg);
    }
    return 0;
}
dart
// Dart / Flutter:同样的"打开一个窗口并显示文字"
void main() => runApp(
      const MaterialApp(home: Scaffold(body: Center(child: Text('Hello')))),
    );

差别不在行数,而在谁拥有重绘:Win32 的 WndProc 在 WM_PAINT 里命令式地画;Flutter 的 build() 只描述"应该长什么样",画由框架做。

2.9 本章小结 + C/Go 对照清单

主题 C(Win32/GDI) Go(Gio / Fyne) Flutter
UI 描述 创建真实控件,命令式修改 每帧录制绘制指令 声明式 Widget 树,框架 diff
入口 WinMain + 消息循环 main + 事件循环 main + runApp(内部含循环)
UI 是否可变 可变对象(HWND) 无状态绘制 Widget 不可变,重建出新树
状态放哪 全局/成员变量 应用结构体 Widget 之上的 State(ch06)/ Riverpod(ch11)
布局 手算像素 + MoveWindow 手算坐标 约束(constraints)逐层下传(ch04)
样式/主题 手写画刷/字体 手写样式 ThemeData + Theme.of(context)
迭代速度 重编译 + 重启 重编译 + 重启 热重载(r)
测试 难 难 flutter test 跑真实 widget 代码

给 C/Go 老兵的三句话:

  1. Widget 不是控件,是配置;不要试图去"修改一个 Widget",而是"重新描述一遍"。
  2. build() 是纯函数,会被反复调用;副作用要放在 initState/事件回调/Riverpod 里。
  3. const 在 Flutter 里是性能手段(短路子树),不是可有可无的装饰。

下一章回到纯 Dart:把第 1 章的类型系统补全——类、对象、泛型、集合与 null 安全,那是读懂 Flutter 源码(Widget、State<T>、InheritedWidget)的前提。