今天它用在哪

• Flutter 一套代码跨 6 端：iOS、Android、Web、Windows、macOS、Linux；Google Pay、BMW 车主应用、闲鱼都是它写的；
• 双引擎是开发体验的来源：JIT 给开发期亚秒级热重载（改完保留应用状态），AOT 给发布期原生机器码。

两份 SDK 的关系：包含，不是并列

• Flutter SDK 内含一份完整的 Dart SDK（在 flutter/bin/cache/dart-sdk/ 下）。要做 Flutter 只装 Flutter 就够，别再单独装 Dart；只写命令行工具或服务端，装独立 Dart SDK 体积小得多。
• 判断你实际在用哪一份，别看 dart --version，看 flutter --version——它会同时打印 Flutter 版本和它自带的 Dart 版本，这两个数字才是配套的。

装完先跑 flutter doctor

• 它是一张体检表，逐项检查 SDK、Android toolchain、Xcode、编辑器插件与可用设备；-v 会打印每一项的具体路径，排查「找错了 SDK」时最有用；
• 不必追求全绿：只做 Web 与桌面时，Android/Xcode 那两项红着不影响。第一个红叉通常是 Android 许可证没接受，跑 flutter doctor --android-licenses 一路 y 即可。

生成的目录，三个文件要认识

• bin/hello.dart——入口，含 main()。只有 bin/ 下的文件能被 dart run 直接执行；
• pubspec.yaml——声明依赖与 SDK 版本约束；pubspec.lock 锁定实际解析到的版本，应用要提交它，库不提交；
• lib/ 放代码主体（包内引用写 import 'package:hello/hello.dart' 而不是相对路径），test/ 下以 _test.dart 结尾的文件会被 dart test 自动发现。

四步跑起来

• flutter create my_app 生成一个能跑的计数器示例，flutter devices 列出可用设备（Chrome 与桌面开箱就有，也不需要 Android 工具链）；
• cd my_app && flutter run，或用 -d chrome 直接指定设备；
• 跑起来后终端处于交互状态：r 热重载、R 热重启、q 退出、v 打开 DevTools；
• 改 lib/main.dart 里任意一段文案，存盘，按 r——界面变了，而计数器的数字还在。这一条就是热重载与重启的全部区别。

r 与 R：一个保状态，一个清状态

• r 热重载把改过的代码注入正在运行的 VM 再重建 widget 树，State 全部保留；R 热重启丢掉整个状态从 main() 重来。
• 什么时候必须用 R：改了 main()、全局／静态变量的初值、类的形状、initState 里的逻辑——这些热重载不会重新执行，你会看到「代码明明改了却没效果」。
• 改了 pubspec.yaml 或原生侧代码，连 R 都不够，必须停掉重跑。

四个关键词，四件事

• var 类型推断但可重新赋值；final 运行时常量，只赋一次；const 编译期常量。
• 优先用 final——大多数变量赋值后不再改变，习惯比 JS 的 let 更收敛。
• const 对象会被规范化（同值共享同一实例），对 Flutter widget 性能很关键。
• late 延迟初始化：声明非空但稍后赋值，编译器能证明必然未赋值时直接编译报错，证明不了（如类字段）则运行时抛 LateInitializationError。
• dynamic 关闭类型检查（慎用）；Object? 是所有类型的顶；想推断就用 var/final。

const 为什么是 Flutter 里最便宜的优化

「const 对象会被规范化」这句话很抽象，一行 identical 就能看穿：

identical(const Point(1), const Point(1)) → true   同一个实例
identical(      Point(1),       Point(1)) → false  两个实例

• 规范化（canonicalization）发生在编译期：值相同的 const 表达式在整个程序里只留一份实例；
• Flutter 的 widget 比较靠 ==，而框架对 const widget 有一条捷径——引用相同就直接判定「没变」，整棵子树跳过重建。所以给不含变量的 widget 加 const，收益是白捡的；
• 反过来也说明了限制：只要构造参数里有一个运行时值，整个 const 就用不了——这就是为什么 Flutter 代码里 const 常常只能加在叶子节点上。

三件套与插值

• int 与 double 都是 num 的子类型；整除用 ~/，普通除法 / 总返回 double。
• 字符串可用单引号或双引号；插值用 $变量 或 ${表达式}。
• 三引号 '''…''' 写多行字符串；相邻字符串字面量自动拼接。
• 字符串不可变；常用：split、contains、replaceAll、padLeft、trim。

字符串的长度有三个答案

final s = 'a👍中';
s.length            → 4   UTF-16 码元数（👍 占两个）
s.runes.length      → 3   Unicode 码点数
utf8.encode(s).length → 8   UTF-8 字节数
s.codeUnitAt(1)     → 55357      取到的是半个代理对，不是一个字符

• String 在 Dart 里是 UTF-16 码元序列，length 与下标都按码元算——这是所有「emoji 截断成乱码」「按长度切字符串切坏了」的根源；
• 要按「人看到的字符」处理，标准库没有现成方案，得用 characters 包的字素簇（grapheme cluster）API，Flutter 项目里它是默认依赖；
• 要按字节算（存储、网络），先 utf8.encode——字节数是编码的属性，不是字符串的属性。

四件工具，四种姿势

• String 不能为 null；String? 才可空。这是 Dart 类型系统的根基。
• ?. 空安全调用；?? 空合并取默认；??= 为空才赋值。
• ! 断言非空（你向编译器担保），错了会运行时崩溃——能不用就不用。
• 类型提升：if (x != null) { x.foo } 中 x 自动收窄为非空。
• 对照 TS 的 strictNullChecks，但 Dart 默认开启且更彻底。

「健全」到底健全在哪

• Dart 的空安全是 sound（健全）的：编译器一旦把某个表达式定为非空类型，运行时就保证它不可能是 null——不是「大概率不是」，而是类型系统与运行时联合担保；
• 这带来一个 TS 没有的红利：编译器可以据此优化掉判空检查，非空类型不必在每次访问前再测一遍。健全性在这里换来的是实打实的性能，不只是心理安慰；
• 代价是没有后门：TS 里 strictNullChecks 可以逐文件开关、any 随时逃逸，Dart 的空安全是全语言强制的，混着写旧代码的过渡期比 TS 痛苦得多——这也是 Dart 2 教程今天全部作废的原因。

三件事：bool、不贯穿、多值

• if / else if / else 链与 JS 一致，从上往下命中第一个成立分支。
• 条件必须是 bool：Dart 没有 truthy/falsy，if (0)、if (str)、if (list.length) 全是编译错误——写显式判断 if (list.isNotEmpty)、if (x != null)。
• switch 语句不贯穿：Dart 3 起非空 case 执行完自动跳出，无需 break；多值命中同分支用逻辑或模式 case a || b。
• 兜底分支写 default: 或通配模式 _，二选一。
• 这是语句形态；switch 作表达式产出值、配模式解构是进阶——见本页 03 章「Switch 表达式」与「if-case 语句」。

「没有 truthy」不是龟毛，是省 bug

• JS 里 if (list.length)、if (str) 能跑，但 0、""、NaN 全是假值——「空字符串」和「没有这个值」被混成一件事，是 JS 最高发的一类 bug；
• Dart 直接在类型层面堵死：条件位置只接受 bool，报 Conditions must have a static type of 'bool'.（诊断码 non_bool_condition）；
• 于是你被迫写出意图：list.isNotEmpty（我关心空不空）、x != null（我关心有没有）、str.isNotEmpty——读代码的人不用再猜你想表达哪一个。

四种循环各管一段

• 三段式 for (var i = 0; i < n; i++) 管「按次数」，初始化、条件、步进各司其职。
• for-in 遍历一切 Iterable，日常遍历集合首选（Map 需经 entries，见「集合」卡）。
• while 先判断后执行（可能一次不跑）；do-while 先执行后判断（至少跑一次）。
• break 结束整个循环，continue 跳过本轮；嵌套跳出外层给循环起标签 break outer;。

惰性：Iterable 不遍历就不计算

final lazy = [1,2,3].map((e) { print('计算 $e'); return e*2; });
// 此处一行输出都没有
lazy.first;          // 只打印「计算 1」——算了一个就停

• map / where / expand 返回的是惰性 Iterable，它描述「怎么算」而不是「算好的结果」；
• 好处是省：只要 .first 就只算一个；坏处是每次遍历都重算一遍，副作用会重复发生、昂贵计算会重复付费；
• 要多次消费、要 length、要下标，就 .toList() 固化——「用两次以上就固化」是条够用的经验法则。

三种参数形态

• 箭头函数 => expr 是单表达式函数的简写。
• 位置可选参数用方括号 [ ]；命名参数用花括号 { }，调用时写参数名。
• 命名参数默认可空；加 required 强制传入——Flutter widget 构造函数大量使用。
• 函数是一等公民：可作参数、返回值、存入变量（与 JS 一致）。
• 命名参数让调用处自文档化，是 Flutter API 的标志性风格。

为什么 Flutter 的 API 长成那样

• Flutter 的 widget 构造函数动辄十几个参数，如果是位置参数，调用处会变成一串无法阅读的字面量；命名参数让每个实参自带标签，调用处即文档；
• 命名参数默认可空、加 required 才强制——于是「可选配置一大堆、必填只有一两个」这种 UI 组件的典型形状能被自然表达；
• 配合尾随逗号（trailing comma）：给参数列表最后一项加逗号，dart format 就会把每个参数各占一行竖排。Flutter 代码里到处是尾随逗号，不是手抖，是在指挥格式化器。

三大件与字面量 DSL

• List（有序可重复）、Set（无序唯一）、Map（键值对）。
• Map 不是 Iterable：for-in 遍历键值对要经 entries（只要键或值用 keys/values），再取 entry.key / entry.value。
• 展开操作符 ... 与空安全展开 ...? 合并集合。
• collection-if 与 collection-for 可在字面量里直接做条件/循环——比 JSX 更优雅。
• 常用：map、where（≈filter）、fold/reduce、any/every、firstWhere。
• List.generate(n, (i)=>…) 快速构造；惰性求值返回 Iterable，必要时 .toList()。

字面量里的四件小工具

[...a, ...b]        展开          → [1, 2, 3]
[...?maybe, 9]      空安全展开     → [9]        （maybe 为 null 时展开成空）
[for (x in a) if (x.isEven) x*10]  collection-if/for → [20]
{1, 1, 2}           Set 去重      → {1, 2}

• ...? 是最被低估的一个：可空列表要合并时，它省掉一整个 if (maybe != null) 分支；
• collection-for 与 collection-if 可以嵌套、可以混用，在 Flutter 的 children: 里比 .map().toList() 干净——后者还得记着补 toList()，忘了就是类型错误。

不用类的写法，两个人就开始难受

String name = '小明';
int age = 12;
String intro(String n, int a) => '$n，$a 岁';   // 每次调用都要重新把数据接一遍

// 来了第二个人，只能再来一套变量
String name2 = '小红';
int age2 = 9;
intro(name, age2);   // 「小明，9 岁」——编译器不会拦你，因为它们之间毫无关系

• 数据和用它的函数没有任何绑定：把 name 和 age2 传进同一次调用，编译完全通过。
• 人一多就得多一套变量。这两件难受，就是类要替你解决的全部。

写成类

class Person {
  String name;                       // 字段：这个盒子里装什么数据
  int age;

  Person(String n, int a) {          // 构造函数：造盒子的时候怎么填
    name = n;
    age = a;
  }

  String intro() => '$name，$age 岁';   // 方法：只管自己的字段，不用再传参
}

final a = Person('小明', 12);   // 实例：按 Person 这张图纸造出来的一个具体对象
final b = Person('小红', 9);    // 另一个实例，两套数据互不干扰

a.intro();   // 小明，12 岁
b.age;       // 9

• 类是图纸，实例是照图纸造出来的东西。Person 只写一次，实例可以有一万个，每个自带一份字段。
• 方法体里的 name 指的是当前这个实例的 name——所以 a.intro() 和 b.intro() 结果不同。这就是「数据和行为绑在一起」的全部含义，没有更玄的东西。
• Dart 里 new 可以省，写 Person(...) 就是创建实例。

再加两样，日常就够用了

class Person {
  String name;
  int age;
  Person(this.name, this.age);            // 上面那段赋值样板的简写，下一卡细讲

  bool get isAdult => age >= 18;          // getter：像字段一样读的计算值
  @override
  String toString() => 'Person($name, $age)';   // print 这个对象时用它
}

print(Person('小明', 12));   // Person(小明, 12)，而不是 Instance of 'Person'

• get 声明的是取值时才算的属性，调用处不写括号——p.isAdult。
• toString 是每个类都从 Object 继承来的方法，@override 表示「我要换掉父类的版本」（继承那张卡会展开）。

一步一步减

// ① 原样：参数接进来，再一个个赋给字段
class Point {
  double x, y;
  Point(double a, double b) { x = a; y = b; }
}

// ② this.x 简写：「这个参数直接赋给同名字段」，最常用的一条
class Point {
  double x, y;
  Point(this.x, this.y);            // 没有函数体了，一个分号收尾
}

// ③ 需要另一种造法时加命名构造，名字随便起
class Point {
  double x, y;
  Point(this.x, this.y);
  Point.origin() { x = 0; y = 0; }  // 用法：Point.origin()
}

• 到这一步为止，日常写类够了。下面两样是遇到具体需求才用得上的。

需求一：字段是 final，就得用初始化列表

class Point {
  final double x, y;                // final：造好之后不许改
  Point(this.x, this.y);            // 这样还行
  Point.origin() { x = 0; }         // 编译错：构造体里已经不能赋 final 字段
  Point.origin() : x = 0, y = 0;    // 对：冒号之后这一段叫「初始化列表」
}

• 初始化列表在构造体之前跑，所以它是 final 字段唯一的赋值时机之一。要拿参数算一下再赋值也用它：Point.polar(double r) : x = r, y = 0;。
• 为什么 final 字段之后就不能赋？因为构造体开始执行时对象已经「成形」了——本卡 pitfall 有报错原文和完整解释。

需求二：想让实例成为编译期常量，就得 const 构造

class Point {
  final double x, y;                // 前提：所有字段都是 final
  const Point(this.x, this.y);      // 构造函数前面加 const
}

const p1 = Point(3, 4);
const p2 = Point(3, 4);
identical(p1, p2);                  // true——同样的参数编译期只留一个实例

• 这不是可选的讲究：Flutter 里 const widget 能让框架靠「引用相等」直接跳过重建，是最便宜的一条优化（05 章「const 构造与性能」）。
• 判据很简单：所有字段都是 final，就顺手给它一个 const 构造，用不用是调用方的事。

factory 管「怎么拿到」

• factory 构造函数不一定创建新实例，可返回缓存对象或子类实例。
• 经典用途：单例、对象池、根据参数返回不同子类、从 JSON 解析。
• 与普通构造的区别：factory 体内可有逻辑、可 return。
• 实现单例：私有构造 _internal() + 静态实例 + factory 返回它。

缓存型 factory 第二次不再创建

class Cache {
  static final Map<String, Cache> _pool = {};
  Cache._(this.k) { print('真的创建了 $k'); }
  factory Cache(String k) => _pool.putIfAbsent(k, () => Cache._(k));
}

Cache('a'); Cache('a');
// 输出只有一行「真的创建了 a」
// identical(c1, c2) → true

• 这是 factory 最有价值的形态：调用方写法完全不变（还是 Cache('a')），是否复用是类自己的实现细节；
• 同一套骨架换个 return 就是别的模式：返回子类实例＝多态工厂，返回唯一静态实例＝单例，从 Map 造对象＝ fromJson。

① 先看那段重复

class Circle {
  double r;
  Circle(this.r);
  double area() => 3.14159 * r * r;
  String describe() => '面积 ' + area().toString();   // 这一行
}
class Square {
  double a;
  Square(this.a);
  double area() => a * a;
  String describe() => '面积 ' + area().toString();   // 和上面一模一样
}

• describe() 重复了，而且它只用到 area()、根本不关心面积怎么算。「公共的行为 + 各自不同的一小步」——这个形状就是继承的用武之地。

② 把公共部分提上去，不同的那一步留空

abstract class Shape {
  double area();                                    // 抽象方法：只有签名没有方法体
  String describe() => '面积 ' + area().toString();  // 公共实现，只写一次
}

class Circle extends Shape {
  final double r;
  Circle(this.r);
  @override                                         // 标注「我在覆写父类的方法」
  double area() => 3.14159 * r * r;
}
class Square extends Shape {
  final double a;
  Square(this.a);
  @override
  double area() => a * a;
}

• abstract class 不能实例化：写 Shape() 直接编译错——「形状」本来就不是一个具体东西，它只是「圆和方共同那部分」的名字。
• 子类必须实现所有抽象方法，漏一个就编译错。这是 abstract 的全部作用：把「每个子类都得自己回答」这件事写进类型里。
• 父类已有的实现想换掉就 @override 重写，想在原有基础上加就先调一次 super.方法()；构造函数往父类传参写 : super(...)，Dart 2.17 起可以直接写 Circle(super.r)。

③ 多态：一段不提子类名字的代码

final List<Shape> shapes = [Circle(1), Square(2), Circle(3)];

for (final s in shapes) {
  print(s.describe());     // 每个都跑自己那份 area()
}

• 这段代码一次都没提 Circle 和 Square。以后加一个 Triangle extends Shape，这里一个字都不用改——这才是继承换来的东西，比「省了两行重复代码」值钱得多。
• Dart 的实例方法全都是虚方法，不用像 C++ 那样写 virtual：变量的静态类型是 Shape，跑起来找的是实际那个对象的实现。
• 但 Dart 没有方法重载：同名不同参数直接编译错。要多种入口就用命名参数或命名构造。

① 只要「必须长这个样子」→ implements

class Duck {
  void quack() => print('嘎');
  void swim() => print('游');
}

class RobotDuck implements Duck {     // 借 Duck 的「形状」，实现一行都不继承
  @override void quack() => print('滴');
  @override void swim() => print('划');
}

• Dart 里每个类都自动带一个同名接口，没有单独的 interface 关键字：想当接口用的类，直接 implements 它。
• 和 extends 的分界很干净：implements 只借形状，父类写好的方法体一行都不给你，全部成员都得自己实现，漏一个就编译错；extends 连实现一起继承，但只能一个，而 implements 可以写好几个。

② 同一段实现要塞进几个不相干的类 → mixin

mixin Swimmer {
  int laps = 0;                                       // mixin 可以带字段
  void swim() { laps++; print('游第 ' + laps.toString() + ' 圈'); }
}

class Duck extends Bird with Swimmer {}      // 鸭会游
class Fish extends Animal with Swimmer {}    // 鱼也会游，但鱼不是鸟

• 「会游泳」这件事横跨了两条继承链，而 Dart 只能单继承——with 就是为这种情况准备的：把方法和字段整段混进来，不占用你唯一的那个 extends 名额。
• 多个混在一起写 with A, B，同名成员后写的赢。这是 mixin 唯一需要记的规则。

③ 想给别人的类加方法 → extension

extension StringX on String {
  String get reversed => split('').reversed.join();
}

'abc'.reversed;   // 'cba'——String 是内置类型，源码你改不了

• 它不修改原类，只是让编译器把 'abc'.reversed 翻译成一次普通函数调用。给第三方类型、内置类型加便利写法，这是唯一的正路。

extension 是静态解析——这决定了它的全部脾气

• 扩展方法在编译期按静态类型选中，不进虚方法表。所以接收者一旦是 dynamic，编译器无从选择，运行时直接 NoSuchMethodError（本卡 pitfall 有报错原文）；
• 推论一：扩展方法不能被覆写、不参与多态。同名的实例方法永远赢过扩展方法——库作者以后给类加了个同名方法，你的扩展会无声地失效；
• 推论二：必须 import 才生效。扩展不在类型上，跟着库走——「同事那边能跑我这边报错」十有八九是少了一行 import；
• 因此 extension 适合给类型加纯粹的便利写法（'abc'.capitalize()），不适合承载业务多态——那是接口和 mixin 的活。

四条路怎么挑

要连实现一起继承（复用「是什么」）      → extends（只能一个）
只要求长成某个样子（复用「形状」）      → implements（可以多个）
同一段实现塞进几个不相干的类           → with mixin（可以多个）
给改不了源码的类加便利方法             → extension

类型参数与约束

• <T> 让类/方法对任意类型工作且保持类型安全（与 TS 泛型相通）。
• 约束：<T extends num> 限定 T 必须是 num 子类型。
• 集合本身就是泛型：List<int>、Map<String, User>。
• 返回带泛型的 Future：Future<List<User>>。

实化泛型：Dart 与 Java/TS 的根本分歧

final xs = <int>[1, 2];
xs is List<int>   → true        类型参数在运行时真的存在
xs.runtimeType    → List<int>
xs is List<num>   → true              协变：List<int> 也是 List<num>

• Java 的泛型在编译后被擦除成 List，TS 的类型信息运行时干脆不存在——两者都做不到上面第一行；
• 实化的直接好处：is 判断、jsonDecode 之后的类型校验、依赖注入按类型查找都能正常工作，不必额外传一个 Class<T> 参数；
• 代价是协变留下的运行时洞：List<int> 可以当 List<num> 用，于是 add(1.5) 能过编译、在运行时才抛 type 'double' is not a subtype of type 'int' of 'value'（本卡 pitfall）。把可变集合当协变类型传出去，是这类崩溃的唯一来源——只读场合传 Iterable<num> 就安全了。

枚举即受限的类

• 现代 Dart 枚举不只是常量，可声明字段、构造函数和方法。
• 适合表达带数据的固定取值集合（状态、配置项）。
• .values 拿到全部；.name 拿名字；.index 拿序号。
• 搭配 switch 表达式做穷尽匹配特别顺手。

它取代了什么

enum Plan {
  free(0), pro(30);
  final int price;
  const Plan(this.price);
  bool get paid => price > 0;
}

Plan.pro.price → 30      Plan.pro.paid → true
Plan.values    → [Plan.free, Plan.pro]
Plan.values.byName('free') → Plan.free

• 旧写法是「一个枚举 + 一个 Map<Plan, int> 常量表 + 一个 switch 函数」，三处分散、加成员时容易漏改；
• 现在数据与行为跟成员绑在一起，加一个成员编译器会逼你把构造参数补齐；
• 再配 03 章的 switch 表达式做穷尽匹配，「新增枚举值忘了处理」也会变成编译错误——两条合起来才是完整的收益。

on / catch / finally

• on 类型 按异常类型捕获；catch (e, st) 拿到异常对象和堆栈。
• finally 无论是否异常都执行（释放资源）。
• 可 throw 任意对象，但约定抛 Exception/Error 的子类。
• rethrow 在 catch 内重新抛出原异常，保留堆栈。

rethrow 与 throw e 的区别是可见的

• rethrow 保留原始堆栈——栈顶仍指向最初抛出的那一行；
• throw e 是一次全新的抛出，堆栈从当前行重算，最初的现场就此丢失；
• 排查线上问题时，这个差别决定了你看到的是「真正出错的那一行」还是「某个 catch 块的那一行」——后者等于没有线索。

下划线与库边界

• 以 _ 开头的标识符是「库级私有」（不是类私有）——同文件可访问。
• import 'x.dart' as p; 加前缀；show/hide 选择性导入。
• 包导入：import 'package:flutter/material.dart';。
• export 重新导出，做聚合入口（barrel 文件）。

轻量多值聚合

• 无需定义类即可打包多个值：(1, 'a', true)。
• 位置字段用 .$1 .$2 访问；命名字段用名字访问。
• 最常见用途：函数返回多个值（替代 out 参数 / 临时类 / Map）。
• 完全类型安全，且自动有 == 与 hashCode——比 Map 强得多。
• 可用 typedef 给记录类型起名，提升可读性。

它和 class / Map 的分界线

• 选择规则很干脆：临时装两三个值、就地拆开用 → record；要挂方法、要长期演化、要出现在公开 API 里 → class；Map 只用于「键在运行时才知道」的真动态数据；
• 那条「== 与 hashCode 自动成立」尤其值钱——它正好补上了 02 章「继承」卡里那个「覆写 == 忘了 hashCode」的坑。

匹配与解构合成一个动作

• 模式可出现在变量声明、for、switch、if-case 中。
• 支持解构记录、List、Map、对象，并绑定到变量。
• List 模式可用 ... 匹配剩余元素；可加 when 守卫条件。
• 对照 JS 解构，但 Dart 还能同时做类型判断与穷尽检查。

从语句升级成表达式

• switch 现在可作表达式直接赋值/返回，分支用 =>，逗号分隔。
• _ 作通配（default）；关系/逻辑模式可写 >= 90 这类条件。
• 对 enum/sealed 类型可省略 _，由编译器强制穷尽。
• 在 Flutter build 里按状态返回不同 widget 极其顺手。
• 下方 build 示例用到了 sealed 类与对象模式解构（Loading()、Data(:final items)）——这两者见本页「Sealed 密封类」（3.5）。

穷尽检查：什么时候能省掉 _

sealed / enum 类型  → 可以省 _，漏分支直接编译错：
  The type 'Result' isn't exhaustively matched by the switch
  cases since it doesn't match the pattern 'Err()'.

int / String 等开放类型 → 必须写 _，漏了同样是编译错：
  The type 'int' isn't exhaustively matched … pattern 'int()'.

• 区别在于编译器数不数得清全集：sealed 的子类被限制在同一个库里、enum 的成员是写死的，所以它能数清；int 有无穷多个值，只能靠你兜底；
• 这条性质正是 sealed 建模状态的全部价值所在——新增一个状态子类，所有没处理它的 switch 立刻变成编译错误，编译器替你做穷举检查。

单分支的匹配与解构

• if (value case Pattern) { … } —— 匹配成功才进入分支并解构。
• 适合「只关心一种情况」的解构，比完整 switch 更轻。
• 可与 when 守卫组合，做更细的条件。
• 常用于安全解析未知结构的 JSON / 动态数据。

它最实用的场合：解析不可信的动态数据

final data = jsonDecode(text);   // 类型是 dynamic
if (data case {'user': {'name': String name, 'age': int age}}) {
  // 走到这里时 name 是 String、age 是 int，已经校验过了
} else {
  // 结构不对、类型不对、字段缺失 —— 全部落到这里
}

• 一个模式同时完成了四件事：判断是不是 Map、判断嵌套结构、判断每个字段的类型、把值绑到变量上；
• 换成手写要四五层 is 判断加类型转换，而且漏一层就是运行时崩溃。这是 Dart 3 对日常代码改善最大的一处；
• 配 when 守卫还能加业务条件：if (data case {'age': int age} when age >= 18)。

封闭清单与穷尽检查

• sealed 类的所有直接子类必须在同一库（通常即同一文件）——编译器因此知道全集。
• 对 sealed 类型做 switch 时，漏掉任一子类会报编译错误。
• 是建模「有限状态」（加载/成功/失败）的现代标准做法。
• 配合 records/patterns，大幅取代过去 freezed 的联合类型用途。

它取代了 freezed 的哪一半

• Dart 3 之前，要表达「加载中 / 成功 / 失败」这种封闭状态集，标准做法是上 freezed 生成联合类型——现在 sealed + record + 模式匹配原生就够了，少一个代码生成器、少一轮 build_runner；
• freezed 仍然有用的那一半是样板生成：copyWith、toJson/fromJson、深比较。sealed 一个都不给你；
• 所以现实的选择是：状态建模用语言原生的 sealed，数据类的样板才请 freezed——而不是像以前那样一上来全套生成。

五个开关，控制继承面

• final：禁止被继承或实现（库外）。
• base：可被继承但不可被实现，保证子类继承实现。
• interface：可被实现但不可被继承（当纯接口用）。
• sealed：隐式 abstract + final，且启用穷尽检查。
• mixin class：既能 extends 又能 with。设计库 API 时用于约束扩展方式。

五个修饰符各禁掉什么

• 限制只对「库外」生效：同一个库（通常即同一文件）里这些约束都不拦你，它们是给包的使用者划的线；
• 约束会传染：父类是 base 或 final，子类也必须标 base/final/sealed，报 The type 'D' must be 'base', 'final' or 'sealed' because the supertype 'B' is 'base'.——否则「不可实现」这条保证会从子类漏掉；
• 应用内部代码基本不需要这些。它们是库作者的工具，用在自己项目里多半只是给未来的自己添堵。

上下文已知就省掉类型名

• 目标类型已知时，枚举值/静态成员/命名构造可写 .value 省略类型名。
• 例：Status.running → .running。但 Colors.blue 写不成 .blue——简写只查上下文类型自身的静态成员，参数类型是 Color，而 blue 定义在 Colors 上。
• Flutter 里给 mainAxisAlignment: 这类参数赋值时尤其省字。
• Dart 3.11 进一步完善了 IDE 对它的补全与提示支持。
• 本质是借鉴 Swift 的隐式成员表达式，少打字、更聚焦。

macros 取消后的现状

• Dart 团队于 2025 年初取消了 macros（因严重拖慢热重载）——不要再等它。
• 当前代码生成仍靠 build_runner（json_serializable、freezed 等）。
• augmentations（增强声明）是元编程的后续方向：允许把类定义拆分到多文件。
• Dart 3 的语言特性已让你在很多场景不再需要 freezed。
• 心态：优先用语言原生特性，代码生成按需引入，别一上来全套生成器。

为什么 macros 被砍：热重载与它不可兼得

• macros 的设想是「编译期跑用户代码来生成代码」。问题在于：热重载要求改一行就能在一秒内把新代码塞进运行中的 VM，而宏意味着每次改动都要重新执行一遍任意用户程序，再重新做一遍类型推断；
• Dart 团队 2025 年初正式取消该特性，理由正是对分析与热重载的性能影响不可接受——而热重载恰恰是 Dart 存在的理由，这个取舍没有别的答案；
• 取而代之的方向是 augmentations（增强声明）：允许把一个类的定义拆到多个文件、由生成器补齐缺的部分。它不需要在编译期跑用户逻辑，因此对增量编译友好。

把「稍后的值」变成普通变量

• Future<T> 代表「未来某刻的一个值」，≈ JS 的 Promise。
• async 标记函数返回 Future；await 等待其完成并取值。
• 未捕获的 await 异常会向上抛——用 try/catch 包裹。
• await 不阻塞线程，只是挂起当前异步流，UI 继续响应。

await 不阻塞线程——这句话的准确含义

Future<void> f() async {
  print('A');            // 同步执行
  await Future.value();
  print('C');            // 恢复后执行
}
f();
print('B');

实际输出：A → B → C

• async 函数体在遇到第一个 await 之前是彻底同步的——所以「调用一个 async 函数」不等于「稍后才开始」，它已经跑了一段；
• 碰到 await 时，函数把「剩下的部分」登记成一个回调然后立即返回，控制权还给调用者（打印 B），等值就绪后再从事件循环回来接着跑（打印 C）；
• 推论一：await 挂起的是这一条异步流，不是线程。UI 线程回去继续处理手势与渲染，这就是「不卡界面」的全部机制；
• 推论二：如果 await 之前那段是重计算，它照样卡 UI——async 关键字救不了同步阻塞，那是 isolate 的活。

并发、超时与错误策略

• Future.wait([...]) 并发等待多个，全部完成才返回（≈Promise.all）。
• Future.any、Future.delayed、.timeout(...) 控制时序。
• 回调式：.then()/.catchError()/.whenComplete()——但 async/await 更清晰。
• Future.value / Future.error 构造即时完成的 future。

Future.wait 是真并发

三个任务分别耗时 100 / 200 / 300 ms：
await Future.wait([...])  总耗时 309 ms   ← 约等于最慢的那个，不是 600

• 之所以能并发，是因为这三个 Future 在传进 wait 之前就已经启动了——Dart 的 Future 是「已经在跑的任务」，不是 JS 里也不是 Rust 里那种惰性对象；
• 推论：await a; await b; 是串行（300+200），Future.wait([a, b]) 才是并发。这两行长得像，耗时差一倍，是性能问题的高发地；
• 类型不同的少数几个 future 用记录扩展 (f1, f2).wait，解构后各自保留精确类型（int / String），比 Future.wait 返回 List<dynamic> 再强转干净得多。

一串值的抽象

• Stream<T> = 「会陆续到来的一串值」，≈ 可监听的事件源。
• 单订阅流（默认，只能 listen 一次）vs 广播流 .asBroadcastStream()。
• 用 await for 在 async 函数里逐个消费；或 .listen(cb)。
• Stream 也支持 map/where/take 等变换。
• Flutter 中 StreamBuilder 直接把流绑定到 UI。

yield 与 yield*

• sync* + yield 惰性产生 Iterable（按需计算）。
• async* + yield 产生 Stream。
• yield* 委托给另一个序列，把其元素逐个产出。
• 适合无限序列、分页拉取、逐步计算等场景。

手工造一条流

• 当事件来自命令式代码（按钮、WebSocket、定时器）时，用它构造流。
• .sink.add(event) 推送；.stream 暴露给消费者；用完 .close()。
• broadcast() 支持多订阅者。
• 很多状态管理（如 Bloc）底层就是 StreamController 的封装。

解决「算」的问题

• Dart 单线程跑事件循环；Isolate 是独立内存的并行执行单元（≈ Web Worker）。
• isolate 间不共享内存，只能通过消息（端口）通信——天然无数据竞争。
• CPU 密集任务（解析大 JSON、图像处理）放进 isolate，避免掉帧。
• compute(fn, arg) 是开箱即用的简化入口，自动起一个 isolate。

不共享内存换来了什么，又要付什么

• 换来：没有共享可变状态，就没有数据竞争、不需要锁。Dart 里你永远不会写 mutex——这是它并发模型最大的省心之处；
• 付出：跨 isolate 只能传消息，对象要被拷贝过去（大对象有实打实的序列化开销）；能传的东西也有限制——捕获了 ReceivePort、Socket 之类不可发送对象的闭包，直接抛 Illegal argument in isolate message: object is unsendable；
• 现代写法是一行：final r = await Isolate.run(() => heavy());（可用，isolate 里抛的异常会原样传回 await 处、能正常 catch）。Flutter 的 compute 如今就是它的封装；
• 判据：任务是「等」（网络、文件、定时）就用 async/await，是「算」（解析大 JSON、图像处理、加解密）才上 isolate。用错方向不会更快，只会多一次拷贝。

两条队列，一条规则

• Dart 有两个队列：微任务队列（优先）和事件队列。
• scheduleMicrotask / 已完成的 Future 回调进微任务队列。
• I/O、计时器走事件队列；await 等待的事件（timer/IO）也在事件队列，事件到达后其后的续体（continuation）经微任务恢复。
• 微任务全清空后才处理下一个事件——与 JS 的 microtask/macrotask 模型相通。
• 实务：别在微任务里写死循环，会饿死事件队列让 UI 卡死。

把顺序跑出来（输出就是 1→2→3→4→5）

print('1 同步');
Future.microtask(() => print('3 微任务'));
Future(() => print('5 事件队列'));
Future.value().then((_) => print('4 已完成 Future 的 then'));
print('2 同步');

• 同步代码先全部跑完（1、2）——哪怕那个 Future 已经完成了，它的 then 也不会同步执行；
• 然后清空整个微任务队列（3、4）；微任务里再产生的微任务还会在这一轮被清掉；
• 最后才轮到事件队列的第一项（5）。Future(fn) 与 Timer 走的都是事件队列，因此比所有微任务都晚；
• 实务推论：别在微任务里写循环产生微任务——事件队列（含 UI 帧、手势、IO）会被饿死，表现为界面完全无响应而 CPU 跑满。

从 create 到 runApp

• 装好 Flutter SDK 后跑 flutter doctor 自检环境（Android Studio/Xcode、设备），再用 flutter create my_app 生成模板工程。
• 入口是 main()，其中调用一次 runApp(根 widget) 把整棵 widget 树挂到屏幕——根通常是 MaterialApp。
• flutter run 跑到模拟器/真机；改代码按 r 热重载，秒级看到效果。
• 目录：lib/ 放 Dart 代码（lib/main.dart 是入口），pubspec.yaml 声明依赖与资源，android/ ios/ web/ 是各端壳工程。

runApp 那一行到底做了什么

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

• runApp 把你给的 widget 接到渲染树的根上，并启动整条流水线：构建 → 布局 → 绘制 → 合成，之后每一帧都由框架驱动；
• 它只该被调用一次。热重启（R）会重新走一遍 main()，热重载（r）则不会——这正是 01 章那张卡里「改 main() 必须按 R」的原因；
• 根 widget 通常是 MaterialApp：它一口气提供了导航器（Navigator）、主题（Theme）、本地化与方向信息。很多「Navigator.of(context) 找不到」「Theme.of 拿到默认值」的报错，根因就是某个 widget 不在 MaterialApp 之下。

目录里哪些该动、哪些别动

• lib/ —— 你的全部 Dart 代码，入口是 lib/main.dart。日常 99% 的改动都在这里；
• pubspec.yaml —— 依赖与资源声明。图片、字体必须在这里登记，否则运行时找不到；改了它 r 和 R 都不够，要停掉重跑；
• test/ —— flutter test 的地盘，见 13 章；
• android/ ios/ web/ windows/… —— 各端壳工程。平时不要动，只有配权限、改包名、加原生依赖时才进去；它们由 flutter create 生成，也可以用 flutter create --platforms=… 事后补；
• build/、.dart_tool/ —— 产物与缓存，永远进 .gitignore；构建出怪问题时 flutter clean 就是删它们。

组合而非继承

• Widget 是 UI 的不可变配置描述，不是真正渲染的对象。
• 界面通过组合小 widget 构建（而非继承大组件）——与 React/Vue 组件思路一致。
• padding、对齐、手势、主题……都是 widget，用「包一层」表达。
• Widget 很廉价：框架频繁重建它们，真正昂贵的是底层 RenderObject。

「widget 是配置不是对象」这句话的三个后果

• 它可以被极其频繁地创建：一个 widget 只是一小撮字段，build 每帧重跑、造出成百上千个 widget 实例都不是问题——真正昂贵的是它背后的 RenderObject，而那一层框架会尽量复用（见「三棵树」卡）；
• 它必须是不可变的：所有字段都是 final。想改界面不是去改 widget，而是造一个新的让框架去 diff——这与 React 的「不要直接改 state」是同一条纪律；
• 「包一层」成了唯一的表达手段：要留白就包 Padding，要居中就包 Center，要能点就包 GestureDetector。好处是正交、可任意组合；代价是嵌套深、可读性靠格式化撑着——这就是 Flutter 代码那种「金字塔缩进」观感的来源，也是尾随逗号必须写的原因。

和 React / Vue 的对照

• 结构上几乎一一对应，唯一的根本差别是最底层：Flutter 不用平台控件，自己往画布上画每一个像素；
• 这解释了它的长处（跨端像素级一致、动画不受控件限制）与代价（包体积大、无障碍与平台质感要自己补、文本选择/输入法这类系统能力要重新实现）。

有没有内部可变状态

• StatelessWidget：只依赖传入参数，无内部可变状态，给定输入→固定输出。
• StatefulWidget：有随时间变化的内部状态，需要重建 UI。
• Stateful 由两部分组成：不可变的 Widget + 可变的 State 对象。
• 经验法则：能用 Stateless 就用 Stateless；状态尽量上提或交给状态管理。

为什么 Stateful 要拆成两个类

class Counter extends StatefulWidget { … }   // 不可变，会被反复丢弃重建
class _CounterState extends State<Counter> { … } // 可变，跨重建存活

• 拆开的理由就是「widget 不可变」这条纪律：状态必须活得比 widget 长，所以不能放在 widget 里；
• State 对象由 Element 持有，只要 widget 的类型与 key 不变，同一个 State 就一直被复用——你的计数器、滚动位置、动画进度因此能跨重建保留；
• 反过来，类型或 key 一变，旧 State 就被 dispose、新的重新 initState，状态清零。列表里的「状态串台」和「状态莫名清空」都是这条规则的两面（见「Key 的作用」卡）；
• 在 State 里访问 widget 的参数写 widget.xxx——它总是指向最新那个 widget 实例，所以 State 里不要缓存构造参数。

标脏，下一帧重建

• 在 setState(() {...}) 里修改状态，框架会重新调用 build。
• 只标记当前 State 子树为脏，框架做最小化的 diff 与重绘。
• 别在 build 里调 setState：对自身调用会被框架静默忽略（不抛错），在 build 中牵连其他 widget 则抛「setState() or markNeedsBuild() called during build.」；别在异步回调里对已 dispose 的 State 调它。
• setState 是最基础的状态机制——先吃透它，再考虑 Provider/Riverpod。

它不是「立刻重绘」，是「登记一下」

• setState 做两件事：跑你给的回调（改字段），然后把这个 Element 标记为脏。build 不会同步发生，要等到下一帧；
• 所以在一个函数里连着调三次 setState，只会重建一次——不必为了性能去合并它们；
• 也所以 setState 之后立刻读取「界面上的」尺寸、位置是拿不到新值的，那要等布局完成（WidgetsBinding.instance.addPostFrameCallback）；
• 回调里其实可以什么都不写（setState(() {})）——字段在外面改也一样生效。但约定俗成把修改写进回调，是为了让读代码的人一眼看到「哪些字段是界面依赖的」。

树中位置的句柄

• context 是当前 widget 在 Element 树中位置的引用。
• 靠它向上查找祖先：Theme.of(context)、MediaQuery.of(context)、Navigator.of(context)。
• 常见坑：在 widget 还没插入树时用 context（如构造函数里）会失败。
• .of(context) 本质是沿树向上找对应的 InheritedWidget。

.of(context) 是一次向上查找

• Theme.of(context) 的本质是：从 context 这个位置出发，沿 Element 树往上走，找最近的那个 Theme。找到就返回，找不到就报错或给默认值；
• 「往上」这个方向决定了两条常见故障：①在提供者同一层或上面取，一定取不到——最典型的是在 MaterialApp 所在的那个 build 里 Navigator.of(context)；②在 widget 还没进树时用（构造函数里、initState 里取 Inherited），拿不到位置；
• ①的标准解法是再包一层 Builder：Builder 唯一的作用就是「凭空造一个更深的 context」；②的解法是挪到 didChangeDependencies 或 build 里；
• 顺带解释了另一个直觉：不同位置的 context 不等价。把 context 存进变量跨页面用，或者在异步回调里用一个早已失效的 context，都会出问题——BuildContext 是「位置」，不是「全局句柄」。

五个回调的分工

• initState：创建后调一次，做订阅、控制器初始化（不能用 context 取 Inherited）。
• didChangeDependencies：依赖的 Inherited 变化时调用（首次在 initState 后）。
• build：每次重建都调，必须纯粹、无副作用。
• didUpdateWidget：父级重建传入新配置时调，用于对比新旧 widget。
• dispose：销毁时调，务必释放控制器、取消订阅，防内存泄漏。

各写什么，一张表说清

• 记忆线索：initState 与 dispose 必须成对——在前者里 new 出来、listen 上去的每一样东西，后者里都要有一行对应的清理。这条纪律能挡掉 Flutter 里绝大多数内存泄漏。

配置、实例、渲染

• Widget 树：你写的不可变配置，频繁重建、廉价。
• Element 树：widget 的实例化，持有状态与 context，框架在此做 diff/复用。
• RenderObject 树：真正负责布局、绘制、命中测试，昂贵、尽量复用。
• 重建 widget ≠ 重建 render object——同类型同 key 的 element 会被复用，性能由此而来。
• 理解这层，才能解释 key、const、性能优化为什么有效。

三层各自的寿命与代价

• 关键结论：「重建 widget」≠「重新布局绘制」。build 跑一万次，只要 Element 复用、RenderObject 的输入没变，屏幕上什么都不用重做；
• 这一层分工把三个看似无关的优化统一起来了：const 让框架用引用相等立刻判定「没变」；Key 决定 Element 能不能被认出来复用；把 setState 下沉到小组件则是缩小标脏的范围；
• 调试时 DevTools 的 Widget Inspector 看的是 widget/element 树，Layout Explorer 看的是 RenderObject 的约束与尺寸——找不到「为什么这么大」时要看后者。

让框架认出谁是谁

• 当 widget 列表的顺序或身份会变时，key 让框架认出「谁是谁」。
• ValueKey（按值）、ObjectKey（按对象）、UniqueKey（每次都唯一）。
• GlobalKey 全局唯一，可跨树访问 State / context（开销大，慎用）。
• 典型 bug：可重排的 StatefulWidget 列表不加 key，状态会「串台」。
• 类比 React/Vue 列表的 key —— 同一思想。

没有 key 时框架怎么配对

• 默认规则：同一位置、同一类型的 widget 就认为是同一个，复用它的 Element 与 State；
• 于是列表重排时会出问题——第 1 项和第 2 项都是 TodoItem，交换后框架按「位置 + 类型」配对，State 留在原位没有跟着走，表现为勾选状态、动画进度、输入框内容串台；
• 加了 key，配对就改成按 key 找，Element 与 State 跟着数据走；
• 判据：只要列表里的 StatefulWidget 会被增删或重排，就必须给 key；纯展示的 StatelessWidget 列表则可以不给（没有 State 可串）。

最便宜的一条优化

• const widget 在编译期就确定，重建时框架直接跳过它（同实例）。
• 尽量给不变的 widget 加 const——几乎零成本的提速。
• 开启 lint prefer_const_constructors 让 IDE 自动提示。
• 这是 Flutter 性能优化里「投入最低、回报最稳」的一条。

为什么它有效：一条引用比较

• 框架 diff 时先比新旧 widget：引用相同就直接判定「没变」，整棵子树跳过。而 02 章验证过 identical(const Point(1), const Point(1)) 为 true——const 表达式在编译期被规范化成同一个实例；
• 于是 const Text('提交') 在每次 build 里都是同一个对象，框架连比字段都省了；
• 开 lint prefer_const_constructors，IDE 会把所有能加的地方标出来，dart fix --apply 可以一键补全（12 章那张分析器卡）；
• 限制也很明确：构造参数里只要有一个运行时值，整个 const 就不成立。所以实践中 const 大多加在叶子节点（图标、固定文案、SizedBox）上——但这些恰恰是数量最多的那些。

一趟遍历，三句话

• 父 widget 给子 widget 传约束（最小/最大宽高）。
• 子 widget 在约束内决定自己的尺寸，向上回报给父级。
• 父级再决定子级的位置。三句话解释了几乎所有布局行为。
• 「为什么我的 Container 没有变大/居中？」90% 是没理解约束传递。
• 调试利器：debugPaintSizeEnabled = true 或 DevTools 的 Layout Explorer。

两个极端约束，解释一半的报错

• 无界约束的意思是「你想多高都行」——这时子级不能说「我要和父级一样高」（没有「一样」可言），于是 Expanded、double.infinity、CrossAxisAlignment.stretch 在这个方向上全部失效；
• 把这两行记住，Flutter 里绝大多数布局报错都能自己定位：先问「这个方向上父级给的是无界还是紧约束」；
• 看不出来就打开 debugPaintSizeEnabled = true，或用 DevTools 的 Layout Explorer——它会把每一层收到的约束和报上去的尺寸直接标在图上。

单子级的日常需求

• Container 是组合体：内外边距、装饰、约束、对齐，一个顶多个。
• Padding 加内边距；Center/Align 控制子级对齐。
• SizedBox 固定尺寸，或当作间距（SizedBox(height: 16)）。
• DecoratedBox / BoxDecoration 做圆角、边框、渐变、阴影。

Container 是组合体——知道它等于什么才好取舍

• 一个 Container 内部按需组合出 Padding + Align + DecoratedBox + ConstrainedBox + Transform：你传了哪几个参数，它就只装配哪几层；
• 所以「只加内边距」时直接写 Padding 比 Container(padding:) 更直白，但性能上没有区别——Container 不会造出你没要的层；
• 真正的取舍是可读性：参数超过两三个时 Container 更紧凑，只有一个诉求时专用 widget 更能表达意图；
• 一个常见困惑：不带任何参数的 Container() 会尽可能大（有子级时包裹子级，无子级时占满）——想要「零尺寸占位」用 SizedBox.shrink()。

主轴与交叉轴

• Row 横向、Column 纵向排列子级（≈ CSS flex-direction）。
• mainAxisAlignment 控制主轴分布；crossAxisAlignment 控制交叉轴。
• mainAxisSize 决定占满还是包裹内容。
• 子级溢出会显示黄黑条警告——用 Expanded/Flexible 或可滚动容器解决。

主轴剩余空间怎么分

• Expanded 占满剩余空间；多个 Expanded 按 flex 比例分配。
• Flexible 允许占用剩余空间但不强制占满（fit: FlexFit.loose）。
• Spacer 是弹性空白，等价于不带 child 的 Expanded。
• 只能放在 Row/Column/Flex 内部，否则报错。

Expanded 与 Flexible 差在一个字段

Expanded  ≡ Flexible(fit: FlexFit.tight,  child: …)   必须占满分到的份额
Flexible  ≡ Flexible(fit: FlexFit.loose,  child: …)   最多占这么多，可以更小

• 差别只有在子级本身比分到的空间小时才看得出来：Expanded 会把子级拉大到占满，Flexible 让它保持自己的尺寸；
• 所以「按钮组要等宽」用 Expanded，「文字尽量占但别拉伸」用 Flexible；
• flex: 是比例不是像素：两个 Expanded(flex: 2) 和 Expanded(flex: 1) 按 2:1 分剩余空间——是剩余，不是总宽，这一点很容易算错；
• Spacer() 就是 Expanded(child: SizedBox())，用来把两侧的东西推开，比 MainAxisAlignment.spaceBetween 更灵活（可以只在某两项之间推）。

布局系统里的 absolute

• Stack 让子级互相重叠，后面的盖在前面。
• Positioned 用 top/left/right/bottom 精确定位（类似 CSS absolute）。
• 未 Positioned 的子级按 alignment 对齐。
• 用 Positioned.fill 让子级铺满；常配合背景图、徽标、悬浮按钮。

改写传给子级的约束

• ConstrainedBox 施加最小/最大尺寸约束。
• AspectRatio 维持宽高比（如 16:9 视频框）。
• FractionallySizedBox 按父级尺寸的百分比设定大小。
• IntrinsicHeight/Width 按内容固有尺寸对齐（开销较大，慎用）。

无限主轴与懒加载

• SingleChildScrollView 让任意内容可滚动（适合短内容）。
• ListView(children: [...]) 一次性构建全部——仅用于少量固定项。
• 长列表必须用 ListView.builder：按需懒构建可见项，省内存。
• ListView.separated 自动加分隔线；itemCount 控制数量。

三个构造函数的分界线

• 判据很简单：项数不由你写死，就用 builder。一千项的 ListView(children:) 会在首帧构建一千个 widget 并全部布局，直接卡住；
• itemCount 别忘了传——不传的话 builder 会被认为是无限列表，配合 shrinkWrap 会挂死。

列表 + 一条切列规则

• GridView.builder + SliverGridDelegateWithFixedCrossAxisCount 固定列数。
• ...WithMaxCrossAxisExtent 按最大宽度自适应列数（响应式）。
• childAspectRatio 控制每个格子的宽高比。
• 同样优先用 builder 版本做懒加载。

两个 delegate，对应两种设计诉求

• 做多端适配时后者几乎总是更好——不必自己写断点，宽屏自然多排几列；
• childAspectRatio 是宽÷高，容易记反；格子里内容溢出时先怀疑它。要按内容高度自适应，固定网格做不到，得上 SliverGrid 的其他 delegate 或第三方瀑布流；
• 和 ListView 一样，优先 .builder。

把一屏滚动拆成几段

• Sliver 是「可滚动区域的一段」，由 CustomScrollView 把多段组合起来。
• SliverAppBar 做可折叠/吸顶的标题栏（floating/pinned/snap）。
• SliverList/SliverGrid/SliverToBoxAdapter 拼出复杂滚动页。
• 当一个页面需要「头图折叠 + 列表 + 网格」混排时，就该上 Sliver。

什么时候必须上 Sliver

• 判据：同一个滚动视图里有异质的段落——头图会折叠、中间是列表、下面接一个网格。用嵌套 ListView 实现这种页面，要么报错要么丢掉懒加载；
• CustomScrollView 提供一个滚动位置，把若干 Sliver 拼成一条完整的滚动内容——每段各自懒加载，性能与单个 ListView 一致；
• 常用几件：SliverAppBar（floating 上滑即现 / pinned 吸顶 / snap 吸附）、SliverList、SliverGrid、SliverToBoxAdapter（把一个普通 widget 塞进 Sliver 世界）；
• 报「A RenderViewport expected a child of type RenderSliver」就是把普通 widget 直接放进了 CustomScrollView ——包一层 SliverToBoxAdapter 即可。

感知设备与可用空间

• SafeArea 自动避开刘海、状态栏、底部手势条。
• MediaQuery.of(context) 获取屏幕尺寸、方向、文字缩放、亮度等。
• LayoutBuilder 拿到父级约束，按可用宽度切换布局（响应式核心）。
• Flutter 较新版本可用 MediaQuery.sizeOf(context) 精准订阅单个属性，减少重建。

三者的作用域完全不同

• 最常见的误用是拿 MediaQuery 的宽度当自己可用的宽度——侧边栏里、对话框里、分屏时，这两个数字完全不同。做响应式布局要用 LayoutBuilder；
• MediaQuery.of(context) 会订阅整个 MediaQueryData，键盘一弹、字号一改就重建；新版本用 MediaQuery.sizeOf(context) 只订阅需要的那一项，能显著减少无谓重建；
• SafeArea 别一律套在最外层：全屏背景图要顶到刘海下面，只有内容区才需要避让——正确做法是把它包在内容上，而不是整页上。

尺寸与平台是两件事

• 响应式：随尺寸连续调整（断点切换列数、间距）。
• 自适应：随平台/输入方式调整（鼠标 vs 触摸、Material vs Cupertino）。
• 工具：LayoutBuilder、MediaQuery、Flex、断点常量、Wrap（自动换行）。
• 桌面/Web 还需考虑：键盘、悬停、可调窗口、更大信息密度。

两条轴，别混着设计

• 响应式（responsive）＝ 随尺寸连续变化：断点切列数、调间距、侧边栏收起来。工具是 LayoutBuilder + 一组断点常量；
• 自适应（adaptive）＝ 随平台与输入方式变化：鼠标要 hover 反馈、触摸要更大的点击区、桌面有右键菜单与键盘快捷键、iOS 用 Cupertino 观感；
• 混着做的典型错误是「按宽度猜平台」——用窗口宽度判断「这是桌面」，然后给了鼠标交互；结果平板横屏、手机分屏、桌面窄窗口全部误判。要判平台用 Theme.of(context).platform 或 defaultTargetPlatform，要判尺寸用约束；
• 桌面/Web 还有一批容易漏的：窗口可以被拖到很窄（布局不能假设下限）、需要键盘导航与焦点管理、信息密度期望更高（照搬手机布局会显得空旷）。

两套设计语言

• material.dart 提供 Android/通用风格；cupertino.dart 提供 iOS 风格。
• Flutter 默认推 Material 3（Material You），通过 useMaterial3: true（新版默认开启）。
• 多数 App 全平台用 Material 即可；追求 iOS 原生质感才混用 Cupertino。
• MaterialApp / CupertinoApp 是各自的根 widget。

页面骨架的槽位

• Scaffold 提供标准页面结构，是大多数页面的容器。
• 常用槽位：appBar、body、floatingActionButton、drawer、bottomNavigationBar。
• AppBar 含 title、actions、leading，自动适配主题色。
• Scaffold.of(context) 可打开 Drawer；SnackBar 走 ScaffoldMessenger（见本章「反馈」卡）。

单样式与多样式

• Text 显示文字；style: TextStyle(...) 控制字号/字重/颜色/行高。
• 用主题排版：Theme.of(context).textTheme.titleLarge 保证全局一致。
• RichText / Text.rich + TextSpan 实现一段内多样式。
• maxLines + overflow: TextOverflow.ellipsis 处理超长文本。

别硬编码字号：走 textTheme

• Theme.of(context).textTheme.titleLarge 这类取法有三个好处：全局统一、跟随主题亮暗自动换色、跟随系统字体缩放；
• 最后一条是无障碍的硬要求——用户在系统里调大字体后，硬编码 fontSize: 14 的文字纹丝不动，而周围跟随主题的部分会变大，界面直接错位；
• 要在主题基础上微调用 copyWith：textTheme.bodyMedium?.copyWith(color: …)，而不是从头 new 一个 TextStyle；
• 超长文本一定要配 maxLines + overflow: TextOverflow.ellipsis——否则在窄屏或大字号下直接溢出，就是 06 章那条黄黑警告。

五级视觉强调

• Material 3 层级：FilledButton（主操作）→ElevatedButton→OutlinedButton→TextButton。
• IconButton 纯图标；FloatingActionButton 页面主操作。
• onPressed: null 会让按钮变灰禁用——常用 enabled ? fn : null。
• style: ...styleFrom(...) 定制颜色、内边距、形状。

选哪一个，看这一屏里它排第几

• onPressed: null 就是禁用——这是 Flutter 的统一约定，不需要额外的 enabled 参数。写法是 onPressed: canSubmit ? _submit : null；
• 由此引出一个高频 bug：把 onPressed: () {}（空函数）当禁用，按钮看起来是可点的、点了没反应，用户只会以为应用卡了；
• 统一定制用主题里的 filledButtonTheme 等，而不是每处写 styleFrom——后者改一次要改几十处。

本地图、网络图与图标

• Image.asset('a.png') 用本地资源（需在 pubspec 声明 assets）。
• Image.network(url) 加载网络图，配 loadingBuilder/errorBuilder。
• 生产环境用 cached_network_image 做磁盘缓存。
• Icon(Icons.xxx) 用内置图标字体；BoxFit 控制缩放裁剪方式。

输入、控制器与焦点

• TextField 接收输入；controller: TextEditingController() 读写文本。
• decoration: InputDecoration(...) 配标签、提示、图标、边框。
• onChanged 实时回调；keyboardType/obscureText（密码）按需设置。
• 控制器要 dispose，否则泄漏；焦点用 FocusNode 管理。

GlobalKey 统管校验

• Form 用 GlobalKey<FormState> 统一管理子字段。
• TextFormField 的 validator 返回错误文案或 null（通过）。
• _formKey.currentState!.validate() 触发全表单校验。
• onSaved / AutovalidateMode 控制保存与自动校验时机。

三种校验时机，体验差很多

• validator 的契约是：校验通过返回 null，不通过返回错误文案。返回空字符串会占位但不显示文字，容易误以为「没生效」；
• _formKey.currentState!.validate() 返回 bool，提交前必须先看它；save() 触发所有 onSaved；
• 异步校验（查用户名是否重复）validator 做不了——它是同步的。要么在提交时单独发请求，要么把结果存进 State 再让 validator 读。

受控组件

• 这些是受控组件：自身不存状态，靠 value + onChanged 回写。
• Switch/Checkbox 布尔；Radio 单选组；Slider 连续值。
• Material 3 新增 DropdownMenu（带搜索补全）替代旧 DropdownButton。
• 在 StatefulWidget 里用 setState 更新值，或交给状态管理。

现成的信息组件

• Card 带圆角阴影的容器，承载分组内容。
• ListTile 标准列表项：leading/title/subtitle/trailing + onTap。
• Chip 系列（ActionChip/FilterChip/ChoiceChip）做标签与筛选。
• Divider/VerticalDivider 分隔；ListTileTheme 统一样式。

先找现成的，再考虑自己拼

• ListTile 一个顶一大段布局代码：leading / title / subtitle / trailing 四个槽位加上点击态、内边距、最小高度、无障碍语义全都给好了，还自动跟随主题；
• 自己用 Row + Column 拼出来的「列表项」通常会漏掉后三样，在大字号或读屏软件下露馅；
• Card 在 Material 3 里默认是低阴影 + 圆角，不再是老版那种明显的浮起——想要边框感用 Card.outlined；
• 要统一改所有 ListTile 的样式，用 ListTileTheme 包一层，而不是每处传参。

三种反馈通道

• showDialog 弹模态对话框（AlertDialog/SimpleDialog）。
• showModalBottomSheet 从底部滑出面板，承载选项或表单。
• ScaffoldMessenger.of(context).showSnackBar(...) 弹出底部轻提示。
• showDialog / showModalBottomSheet 返回 Future，可 await 用户的选择结果；showSnackBar 返回的是控制器，等它关闭要用 .closed。

选哪一种：看要不要打断用户

• 前两个返回的是 Future<T?>：用户点了叉或点了外面，拿到的是 null——这个分支必须处理，忘了就是空指针；
• 三者都在异步之后回来，所以用之前先判 mounted（05 章 setState 卡）；
• 不要用 Dialog 做「操作成功」提示——它强制用户多点一次。成功用 SnackBar，失败且需要用户处理才用 Dialog。

一颗种子色生成整套

• Material 3 用单一种子色生成整套协调配色：ColorScheme.fromSeed(seedColor: ...)。
• ThemeData 集中定义颜色、排版、组件样式；全局一处改，全局生效。
• MaterialApp 的 theme + darkTheme + themeMode 支持亮暗切换。
• 组件内取色用 Theme.of(context).colorScheme.primary 而非硬编码。

ColorScheme.fromSeed 到底给了你什么

• 输入一个种子色，M3 的算法生成一整套语义化配色：primary/onPrimary/primaryContainer/surface/error… 每一对「色 + on色」都保证了对比度；
• 关键收益是无障碍：只要你用 colorScheme.onPrimary 在 colorScheme.primary 上写字，对比度就是达标的——不必自己算；
• 亮暗两套只需把 brightness 换一下再生成一次，MaterialApp 的 theme + darkTheme + themeMode 负责切换；
• 硬编码 Colors.blue 会在暗色模式下当场露馅——这是暗色模式适配里最常见、也最容易避免的一类问题。取色一律走 Theme.of(context).colorScheme.*。

裸手势与水波反馈

• GestureDetector 捕获 tap/doubleTap/longPress/拖拽/缩放等手势。
• InkWell / InkResponse 在点击时显示 Material 水波纹（需在 Material 之上）。
• onTap: null 让它失效；可包裹任意 widget 让其可点击。
• 复杂手势冲突用 GestureArena 机制仲裁；多数场景直接用现成 widget 即可。

够用就别升级

• 组件自己的、不需要共享的状态，直接 setState 即可——不要过度设计。
• 适用：开关、当前 tab、表单临时输入、动画状态。
• 局限：状态无法跨 widget 共享，深层传递会变成「prop 钻取」。
• 判断标准：状态只服务于当前组件 → setState 足矣。

先问三个问题再决定要不要上框架

• 这个状态有几个组件要读？ 一个 → setState，到此为止；
• 它们的距离有多远？ 父子或隔一层 → 状态提升 + 回调；隔了很多层或跨页面 → 才需要 InheritedWidget 之上的方案；
• 它是异步的吗？ 要处理加载中/成功/失败三态、要缓存、要去重请求 → 这才是 Riverpod / Bloc 真正的战场；
• 反模式：项目第一天就搭一整套 Riverpod，然后用它管「这个对话框开没开」。作用域小的状态放进全局容器，等于把局部问题变成全局问题——调试时你得在全局状态里找一个只有一个组件关心的布尔值。

props down / callback up

• 当多个组件需要同一状态：把它提升到最近公共父级。
• 父级通过构造参数把数据向下传，通过回调函数让子级向上通知。
• 这就是经典的 props down / callback up 数据流——Flutter 用回调函数把子级的事件通知给父级。
• 先用纯参数传递把数据流理清，是上任何状态框架前的必修课。

共享状态的物理原理

• InheritedWidget 让子树高效访问祖先数据，无需逐层传参。
• Theme、MediaQuery、Navigator 等都是它的封装——这是「.of(context)」的本质。
• 数据变化时，只通知依赖了它的子级重建，精准高效。
• 几乎所有状态管理框架（Provider/Riverpod）底层都构建在它之上。
• 理解它，你就理解了 Flutter 共享状态的物理原理，不再是「黑魔法」。

它凭什么做到「精准通知」

• 子级调 context.dependOnInheritedWidgetOfExactType<T>()（也就是各种 .of(context) 内部干的事）时，框架把这个 Element 登记为该 InheritedWidget 的依赖者；
• 数据变化时，框架调 updateShouldNotify 判断要不要通知，然后只标记登记过的那些 Element 为脏——没读过它的子树一动不动；
• 所以它是 O(依赖者数量) 而不是 O(子树大小)，这就是「无需逐层传参又不会全树重建」的全部秘密；
• 知道这一层之后，两件事不再是黑魔法：①Theme.of(context) 会让当前 widget 订阅主题变化（所以在不需要订阅的地方用 Theme.of(context, listen: false) 式的读法更省）；②所有状态管理框架都是在它之上加语法糖——Provider 几乎就是它的直接封装，Riverpod 则把「provider 的声明」搬出了 widget 树。

零依赖的最小方案

• ValueNotifier<T> 持有一个值，变更时通知监听者（.value = x）。
• ValueListenableBuilder 仅在该值变化时局部重建对应 UI。
• ChangeNotifier + ListenableBuilder 适合更复杂的可监听对象。
• 纯 Flutter 内置、零依赖，小型应用或局部场景非常够用。

比 setState 强在哪：重建范围

setState                  → 重建整个 State 的 build
ValueListenableBuilder    → 只重建 builder 里那一小块

• 所以在一个复杂页面里，把「频繁变的那一小块」用 ValueListenableBuilder 包起来，比整页 setState 省得多；
• ValueNotifier 适合单个值；一个对象里有多个字段要通知就用 ChangeNotifier + notifyListeners()，配 ListenableBuilder；
• 它们也是 ChangeNotifier，同样必须 dispose；
• 一个容易忽略的坑：ValueNotifier 用 == 判断值变没变。把 List 原地 add 之后再赋给自己，通知不会发出——必须赋一个新列表。这与「widget 不可变」是同一条纪律。

InheritedWidget 的友好封装

• Provider 把对象注入 widget 树，子级用 context.watch/read 取用。
• ChangeNotifierProvider + notifyListeners() 是经典组合。
• 理解 Provider 有助于看懂大量存量项目与教程。
• 新项目里，它在很大程度上被 Riverpod 取代（同作者的进化版）。

把 provider 搬出 widget 树

• Riverpod 不依赖 BuildContext，解决了 Provider 的若干痛点，是当前社区主流之一。
• 用 @riverpod 注解 + 代码生成声明 provider；ref.watch 订阅、ref.read 一次性读。
• Notifier/AsyncNotifier 管理同步/异步状态，天然适配加载/错误态。
• 支持自动依赖追踪、缓存、销毁（autoDispose），可组合 provider。
• 但：它解决的是「跨组件共享 + 异步 + 可测试」，不是「我有个开关要切」。

它相对 Provider 解决了什么

• AsyncValue 那一条在 Dart 3 下特别顺手：它本身就是个封闭的三态联合，配 switch 模式匹配渲染 UI，漏一个状态编译器会报错（03 章 sealed 卡）；
• ref.watch 订阅、ref.read 一次性读——与 Provider 的 watch/read 是同一条纪律，用混的后果也一样；
• autoDispose 让 provider 在没人用时自动销毁，避免「切走了还在跑」；@riverpod 注解 + 代码生成能省掉一大半样板，但也把 build_runner 拉进了项目（03 章）；
• 它解决的是「跨组件共享 + 异步 + 可测试」。只是「我有个开关要切」的话，setState 更合适。

事件进，状态出

• Cubit 暴露方法直接发新状态；Bloc 用「事件 → 状态」更严格的单向流。
• 强调可预测性、可测试性、清晰的状态转移——大型/团队项目常见。
• 配合 sealed class 建模状态，穷尽 switch 渲染 UI，非常契合 Dart 3。
• 学习曲线比 Riverpod 陡，样板更多；按团队规范与项目规模选择。

用样板换什么

• 换来可追溯：每一次状态变化都由一个具名事件触发，配 BlocObserver 可以把「什么事件导致了什么状态」全部打进日志——线上问题复盘时这是实打实的价值；
• 换来可测试：Bloc 是纯粹的「事件流 → 状态流」，不碰 widget、不碰 context，用 bloc_test 断言「给这串事件，应得这串状态」，不需要跑 UI；
• 换来强约定：十个人的团队里，状态怎么改只有一条路——这在大项目里比灵活性更值钱；
• 代价是样板：一个功能要写事件类、状态类、Bloc 三份。Cubit 是简化版（直接暴露方法、省掉事件类），大多数场景 Cubit 就够；
• 与 Dart 3 契合得很好：状态用 sealed class 建模，UI 用 switch 表达式穷尽渲染——新增一个状态，所有没处理它的地方直接编译错。

三个维度，从简单开始

• 局部、临时：setState / ValueNotifier。
• 小范围共享：状态提升 + 回调，或 InheritedWidget。
• 跨页面 + 异步 + 可测试：Riverpod（社区现代默认之一）。
• 大型、强约定、团队：Bloc。
• 原则：从简单开始，被真实复杂度推着升级，而不是预先套最重的方案。

一张表对上号

• 原则：被真实复杂度推着升级，而不是预先套最重的方案。一个方案能撑到痛为止，痛点会告诉你下一步该换什么；
• 反过来也要警惕另一个极端：整个应用只用 setState + 全局单例——能跑，但没人说得清某个值是谁改的，测试无从下手；
• 混用是正常的：全局用 Riverpod、组件内部用 setState 是绝大多数成熟项目的实际形态，不必强求统一。

页面就是一个栈

• 页面是一个栈：Navigator.push 入栈、Navigator.pop 出栈。
• MaterialPageRoute 提供平台默认转场动画。
• pop 可携带返回值；push 返回 Future，await 即可拿到。
• 适合简单 App 与局部跳转；深链接/Web 场景能力有限。

push 返回的 Future，什么时候完成

• Navigator.push 返回 Future<T?>，它在被推入的那个页面 pop 时才完成，值就是 pop 的第二个参数；
• 所以「跳到选择页、选完回来拿结果」是一行 await，不需要回调、不需要全局状态——这是 Navigator 1.0 最好用的地方；
• 用户按系统返回键或 iOS 侧滑返回时，拿到的是 null；这个分支必须处理；
• await 之后照例先判 mounted 再用 context——页面可能已经不在了。

构造参数进，pop 带回

• 传参：直接把数据作为目标页 widget 的构造参数（类型安全，推荐）。
• 返回值：Navigator.pop(context, value)，调用方 await 接收。
• 避免用字符串 arguments 传强类型数据，易出错且无类型检查。
• 需要返回结果的页面（如选择器、确认弹层），这是标准模式。

为什么别用字符串 arguments

// 推荐：类型安全，改了字段编译器会告诉你
Navigator.push(context, MaterialPageRoute(
  builder: (_) => DetailPage(user: user)));

// 不推荐：类型全丢，取的时候要强转
Navigator.pushNamed(context, '/detail', arguments: user);
final user = ModalRoute.of(context)!.settings.arguments as User;

• 第二种写法把编译期检查全部换成了运行时强转：改了参数类型、传错了对象、忘了传，全都要等到运行时崩溃才知道；
• 但命名路由与 Web URL 有天然联系——真需要 URL 同步时不该用 arguments 硬撑，而该上 go_router：它用路径参数 /user/:id 表达，再配代码生成拿回类型安全。

集中注册的路由表

• 在 MaterialApp(routes: {...}) 注册路径到 builder 的映射。
• 用 Navigator.pushNamed(context, '/detail') 按名字跳转。
• 集中管理利于维护，但强类型传参较弱、嵌套/深链支持不足。
• 中大型或需要 Web URL 同步的项目，建议直接上 go_router。

页面栈是状态的函数

• 声明式：页面栈由应用状态决定，而非命令式 push/pop。
• 解决 Web 地址栏同步、深链接、复杂返回栈等问题。
• 原始 API（Router/RouterDelegate/RouteInformationParser）较繁琐。
• 实践中很少直接手写，而是用封装好的库（go_router）——但理解其思想很有用。

为什么要有这么一套

• 命令式 push/pop 的根本问题是：页面栈的真相只存在于框架内部，你没法从应用状态推出「现在应该显示什么」；
• 而 Web 要求反过来：URL 是真相——用户直接输入一个地址、按浏览器返回、分享链接给别人，界面都必须能从 URL 恢复出来；
• Navigator 2.0 的思路是把整个页面栈变成一个由应用状态计算出来的列表：状态变 → 重新算出栈 → 框架 diff 出该 push/pop 谁。这与 widget 的声明式思路完全一致；
• 但原始 API 极其繁琐（RouterDelegate + RouteInformationParser + BackButtonDispatcher，一个最简单的应用要写上百行）——所以实践中几乎没人手写，理解思想、使用 go_router 是正确姿势。

声明式路由的事实标准

• 用路径字符串声明路由树，自动处理 Web URL、深链接、浏览器前进后退。
• context.go('/x') 替换栈、context.push('/x') 压栈。
• redirect 做登录守卫；ShellRoute 实现带底部导航的持久外壳。
• 支持路径参数 /user/:id、查询参数、类型安全跳转（配合代码生成）。
• 是目前 Flutter 路由的事实标准选择之一。

四件事一次到位

• go 与 push 的区别是最常搞混的一处：go('/x') 是「导航到」，会按路由树重建整个栈（返回键回到父路径）；push('/x') 是「压一层上去」（返回键回到刚才那页）。选错的表现是返回键行为诡异；
• redirect 是纯函数，每次导航都会跑——里面别做异步请求，登录态要预先放在可同步读到的地方（配合 refreshListenable 在登录态变化时重算）；
• 它由 Flutter 官方维护，是目前事实标准；配 go_router_builder 做代码生成还能把跳转也变成类型安全的。

三态映射成 UI 分支

• FutureBuilder 监听一个 Future，按「未完成/有数据/出错」渲染不同 UI。
• StreamBuilder 同理监听流，持续更新。
• 用 snapshot.connectionState 与 snapshot.hasError/snapshot.data 分支。
• 坑：别在 build 里直接调接口创建 Future（每次重建都重新请求）——先在 initState/状态层创建好。

三态一个都不能省

• snapshot.hasError 必须处理——漏掉它的表现是「转圈转到天荒地老」，因为出错时 hasData 是 false，你的代码就一直显示加载中；
• connectionState 有四个值，日常只需分 waiting 与其余；但 StreamBuilder 要额外注意 active（流还在推、已有数据）；
• 顺序要对：先判 error，再判 waiting，最后才用 data——反过来写会在出错时先落进加载分支；
• 页面稍微复杂一点，就该把这三态搬到状态层用 AsyncValue（08 章）统一处理，而不是每个 FutureBuilder 里抄一遍分支。

从 http 到 dio

• http 包做基础 GET/POST，返回 Response，手动解析 response.body。
• dio 提供拦截器、超时、取消、上传下载、统一错误处理——生产首选。
• 网络调用务必 try/catch，并区分超时、4xx、5xx、无网络。
• 把网络逻辑收进 Repository 层，UI 不直接碰 HTTP。

什么时候该从 http 换到 dio

• 「取消」那一行最值钱：04 章验证过 .timeout 不取消底层操作——用户切走页面时，只有真正能取消的客户端才会释放连接、停止回调；
• 无论用哪个，网络调用一律 try/catch，并且区分开超时、4xx、5xx、无网络——把它们混成一句「网络错误」，用户和你自己都无法判断下一步该干什么；
• 网络逻辑收进 Repository 层（本章最后一卡），UI 里不应该出现任何 HTTP 相关的类型。

jsonDecode 之后靠自己

• jsonDecode 把字符串转成 Map<String, dynamic>；jsonEncode 反向。
• 在模型类里写 fromJson(Map) 工厂构造与 toJson() 方法。
• 用 Dart 3 的模式匹配可更安全地校验 + 解构 JSON。
• 小项目、字段少时，手写最直接、零依赖、易调试。

为什么 Dart 不能像 Java 那样自动映射

• Dart 没有可用的运行时反射：dart:mirrors 在 Flutter 里被禁用，因为 AOT 编译要做 tree shaking——能反射就意味着任何类都可能被用到，无法裁剪；
• 这是 12 章「AOT 让产物只有 6.36 MB」那件事的代价的另一面：体积与启动速度换掉了反射；
• 所以映射只有两条路：手写（本卡）或代码生成（下一卡）。没有第三条；
• 手写时用 Dart 3 的模式匹配最稳（03 章 if-case 卡）：一个 Map 模式同时完成结构校验、类型校验与解构，比一串 as String 安全得多——后者遇到 null 或类型不符直接崩在解析处，而且报错不告诉你是哪个字段。

模型一多就交给生成器

• 字段多、模型多时，手写易错——用 json_serializable 自动生成。
• 给类加 @JsonSerializable()，运行 dart run build_runner build 生成 .g.dart。
• freezed 还能同时生成不可变类 + copyWith + ==（但 Dart 3 已覆盖部分场景）。
• 生成物 .g.dart 用 part 挂在源文件上，改字段后需重跑生成器。

成本与收益的交叉点

• 收益：字段改名、增删时，生成器保证 fromJson/toJson 同步更新——手写时这里是最高发的 bug（改了字段忘了改映射，编译不报错，运行时静默丢数据）；
• 成本：多一个 build_runner 步骤、多一批 .g.dart 文件、全量构建变慢、CI 里要多一步生成；
• 交叉点大概在「模型超过五六个、或字段超过十个」。一个只有三个字段的响应体，手写更快也更好读；
• 改完源文件必须重跑生成器，否则用的还是旧的 .g.dart——开发时挂 build_runner watch 可以免掉这一步；
• 生成物进不进版本库看团队约定：进则拉下来就能编、CI 更快；不进则版本库干净、但每个人和 CI 都要先跑一次生成。

键值偏好

• shared_preferences 存小型键值（主题、token、开关、上次选择）。
• 异步 API：await SharedPreferences.getInstance() 后读写。
• 不要用它存大量数据或结构化数据——那是数据库的活。
• 敏感信息（token）应用 flutter_secure_storage 加密存储。

SQL 系与对象系

• sqflite：原生 SQLite，写 SQL，控制力强但样板多。
• drift：基于 SQLite 的类型安全 ORM（代码生成 + 响应式查询）。
• Isar / Hive：NoSQL 风格、高性能、API 简洁，适合对象存储。
• 维护状态需留意：Isar 长期停更、社区自行维护分叉，新项目更稳妥的选择是 drift 或维护活跃的方案。
• 选型看：是否需要复杂查询/关系（→drift/sqflite）还是简单快存（→Hive/Isar）。

四个候选，两条路线

• 判据是「要不要复杂查询与关系」：要 → drift（新项目里它基本是默认答案）；不要、只是按 key 存取对象 → Hive；
• 选型时务必看维护状态：Isar 的情况就是活例子——性能再好，主仓库停更之后每次 Flutter 升级都可能变成你的问题。pub.dev 上先看最近一次发版时间和 issue 处理速度，再看 likes；
• 无论选哪个，都要从第一天就想好迁移（schema migration）：用户手机上的旧数据不会消失，加一个字段就要考虑老库怎么升级。

单向依赖

• Repository 封装「数据从哪来」（网络或本地），对上只暴露领域方法。
• UI → 状态层（Riverpod/Bloc）→ Repository → 数据源（API / DB），单向依赖。
• 好处：可替换数据源、可 mock 测试、UI 不关心网络细节。
• 别一上来就上完整 Clean Architecture——按项目复杂度逐步分层。

Repository 真正买到的是什么

• 可替换：「先读缓存、没有再请求网络、拿到后写回缓存」这套逻辑属于 Repository。UI 与状态层完全不知道数据从哪来，你可以随时改策略而不动上层一行；
• 可测试：状态层依赖的是 Repository 这个接口，测试时塞一个假的进去，不需要网络、不需要数据库、跑得飞快。这是分层最实在的回报；
• 可定位：网络出问题只看 data 层，界面出问题只看 presentation 层——分层的本质是把「出了问题该去哪找」变成确定的；
• 但别一上来就上完整 Clean Architecture：三个人的项目里搞四层加 UseCase，每加一个字段要改六个文件。先 UI + Repository 两层，等 domain 逻辑真的复杂到需要独立表达时再拆。

改属性，自动补间

• AnimatedContainer/AnimatedOpacity/AnimatedPadding 等：你改属性，它自动补间。
• 只需提供 duration 与（可选）curve，无需手写控制器。
• AnimatedSwitcher 在子 widget 切换时自动做进出动画。
• 实现 80% 的日常动画需求——优先选它，简单稳妥。

为什么它能「自动」：新旧值 diff

• AnimatedContainer 是个 StatefulWidget，它在 didUpdateWidget 里比较新旧属性，发现变了就自己起一个控制器从旧值补到新值；
• 所以触发它的方式就是普通的 setState——「会 setState 就会做动画」不是修辞，是它的实现方式决定的；
• 推论：第一次 build 不会有动画（没有「旧值」可补），需要入场动画得用 TweenAnimationBuilder 或显式动画；
• AnimatedSwitcher 是同一思路的另一形态——它比较的是子 widget 的类型与 key，所以切换两个都是 Text 的子级时必须给不同的 key，否则它认为没变、没有动画。这是这一卡最高发的一个坑。

拿回时间轴

• AnimationController 控制时间轴（forward/reverse/repeat），需 vsync。
• Tween(begin, end).animate(controller) 把 0~1 映射到目标范围。
• AnimatedBuilder / AnimatedWidget 监听并局部重建动画部分。
• State 需 with SingleTickerProviderStateMixin 提供 vsync，并在 dispose 释放控制器。