附录A：Flutter 版本差异速查

本文档基于 Flutter 3.41.x（当前最新稳定版），汇总了近几个重要版本中与文档内容相关的 API 变更。

版本发布节奏

Flutter 从 3.16 起采用 每 3 个月一个稳定版 的发布节奏（CalVer），每年 4 个版本：

版本	发布时间	Dart SDK
3.44	2026-05（预计）	3.12
3.41	2026-02	3.11
3.38	2025-11	3.10
3.35	2025-08	3.9
3.32	2025-05	3.8
3.29	2025-02	3.7
3.27	2024-11	3.6
3.24	2024-08	3.5
3.22	2024-05	3.4
3.19	2024-02	3.3
3.16	2023-11	3.2

破坏性变更速查

以下变更会导致旧代码编译失败，升级时必须处理。

Flutter 3.22 — MaterialState → WidgetState

所有 MaterialState 相关类型已重命名为 WidgetState：

旧 API（已移除）	新 API
MaterialState.pressed	WidgetState.pressed
MaterialState.hovered	WidgetState.hovered
MaterialState.focused	WidgetState.focused
MaterialState.disabled	WidgetState.disabled
MaterialState.selected	WidgetState.selected
MaterialStateProperty	WidgetStateProperty
MaterialStateProperty.all()	WidgetStateProperty.all()
MaterialStateProperty.resolveWith()	WidgetStateProperty.resolveWith()

// ❌ 旧写法（3.22 之前）
MaterialStateProperty.resolveWith((states) {
  if (states.contains(MaterialState.pressed)) return Colors.red;
  return Colors.blue;
})

// ✅ 新写法（3.22+）
WidgetStateProperty.resolveWith((states) {
  if (states.contains(WidgetState.pressed)) return Colors.red;
  return Colors.blue;
})

废弃 API 速查

以下 API 目前仍可使用但会产生编译警告，建议尽快迁移。

Flutter 3.16 — Material 3 默认启用

ThemeData.useMaterial3 默认为 true，不再需要手动开启。

旧 API	新 API	说明
textScaleFactor	TextScaler.linear(value)	支持非线性字体缩放

// ❌ 旧写法
MediaQuery(
  data: MediaQuery.of(context).copyWith(textScaleFactor: 1.0),
  child: child,
)

// ✅ 新写法
MediaQuery(
  data: MediaQuery.of(context).copyWith(
    textScaler: TextScaler.linear(1.0),
  ),
  child: child,
)

Flutter 3.27 — Edge-to-Edge 默认启用

应用默认全屏绘制（内容延伸到状态栏和导航栏区域）。

• 通过 SafeArea 适配安全区域
• 通过 MediaQuery.of(context).padding 获取安全区域尺寸
• 如需回退，在 AndroidManifest.xml 中设置 android:enableOnBackInvokedCallback="false"

Flutter 3.29 — Material 3 组件更新

• ThemeData.dialogBackgroundColor 废弃 → DialogThemeData.backgroundColor
• Material 3 Slider、ProgressIndicator 外观更新

Flutter 3.32 — 主题系统更新

旧 API	新 API	说明
ThemeData.indicatorColor	TabBarThemeData.indicatorColor	Tab 指示器颜色
InputDecoration.maintainHintHeight	InputDecoration.maintainHintSize	提示文本高度行为
ExpansionTileController	ExpansibleController	展开面板控制

Flutter 3.35 — AppBar 和表单变更

旧 API	新 API / 替代方案	说明
AppBarTheme.backgroundColor	colorScheme.surface + surfaceTintColor	AppBar 颜色由色彩方案决定
AppBarTheme.foregroundColor	colorScheme.onSurface	AppBar 前景色
DropdownButtonFormField.value	DropdownButtonFormField.initialValue	语义更明确

// ❌ 旧写法
AppBarTheme(
  backgroundColor: Colors.blue,
  foregroundColor: Colors.white,
)

// ✅ 新写法
AppBarTheme(
  surfaceTintColor: Colors.transparent,
)

Flutter 3.38 — SnackBar 行为变更

行为变更（非 API 变更）

带 action 的 SnackBar 不再自动消失，用户必须手动操作（点击按钮或关闭）后才会消失。无 action 的 SnackBar 仍按 duration 自动消失。

// 带 action 的 SnackBar —— 3.38+ 不会自动消失
SnackBar(
  content: const Text('已删除'),
  action: SnackBarAction(label: '撤销', onPressed: () { /* ... */ }),
)

Flutter 3.38 — Android 页面过渡变更

Android 平台默认页面过渡动画改为 PredictiveBackPageTransitionBuilder（支持预测性返回手势）。如需恢复旧动画：

MaterialApp(
  theme: ThemeData(
    pageTransitionsTheme: const PageTransitionsTheme(
      builders: {
        TargetPlatform.android: CupertinoPageTransitionsBuilder(),
      },
    ),
  ),
)

Flutter 3.41 — Material 3 Tokens 更新 & API 清理

旧 API	新 API	说明
findChildIndexCallback	findItemIndexCallback	ListView / SliverList
containsSemantics	isSemantics	语义属性
OverlayPortal.targetsRootOverlay	已移除	使用新 API

迁移建议

新项目

直接使用 Flutter 3.41.x，所有文档中的代码示例均已适配此版本。

旧项目升级

# 1. 升级 Flutter SDK
flutter upgrade

# 2. 自动修复部分废弃 API
dart fix --apply

# 3. 手动处理剩余警告
flutter analyze

遇到编译错误

1. MaterialState → WidgetState（全局搜索替换）
2. textScaleFactor → TextScaler.linear()
3. 检查 ThemeData 中废弃属性
4. 运行 dart fix --apply 自动修复